setSystemTime and getRealSystemTime type and doc update (#10169)

CHANGELOG.md

@@ -19,6 +19,8 @@
 - `[jest-core]` 🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉 ([#10000](https://github.com/facebook/jest/pull/10000))
 - `[jest-core, jest-reporters, jest-test-result, jest-types]` Cleanup `displayName` type ([#10049](https://github.com/facebook/jest/pull/10049))
 - `[jest-runtime]` Jest-internal sandbox escape hatch ([#9907](https://github.com/facebook/jest/pull/9907))
+- `[jest-fake-timers]` Update `now` param type to support `Date` in addition to `number`. ([#10169](https://github.com/facebook/jest/pull/10169))
+- `[docs]` Add param to `setSystemTime` docs and remove preceding period from it and `getRealSystemTime` ([#10169](https://github.com/facebook/jest/pull/10169))
 
 ### Performance
 

docs/JestObjectAPI.md

@@ -647,13 +647,13 @@ This means, if any timers have been scheduled (but have not yet executed), they
 
 Returns the number of fake timers still left to run.
 
-### `.jest.setSystemTime()`
+### `jest.setSystemTime(now?: number | Date)`
 
 Set the current system time used by fake timers. Simulates a user changing the system clock while your program is running. It affects the current time but it does not in itself cause e.g. timers to fire; they will fire exactly as they would have done without the call to `jest.setSystemTime()`.
 
 > Note: This function is only available when using modern fake timers implementation
 
-### `.jest.getRealSystemTime()`
+### `jest.getRealSystemTime()`
 
 When mocking time, `Date.now()` will also be mocked. If you for some reason need access to the real current time, you can invoke this function.
 

e2e/modern-fake-timers/from-config/__tests__/test.js

@@ -7,7 +7,7 @@
 
 'use strict';
 
-test('fake timers', () => {
+test('fake timers with number argument', () => {
   jest.setSystemTime(0);
 
   expect(Date.now()).toBe(0);
@@ -16,3 +16,13 @@ test('fake timers', () => {
 
   expect(Date.now()).toBe(1000);
 });
+
+test('fake timers with Date argument', () => {
+  jest.setSystemTime(new Date(0));
+
+  expect(Date.now()).toBe(0);
+
+  jest.setSystemTime(new Date(1000));
+
+  expect(Date.now()).toBe(1000);
+});

e2e/modern-fake-timers/from-jest-object/__tests__/test.js

@@ -7,7 +7,7 @@
 
 'use strict';
 
-test('fake timers', () => {
+test('fake timers with number argument', () => {
   jest.useFakeTimers('modern');
 
   jest.setSystemTime(0);
@@ -18,3 +18,15 @@ test('fake timers', () => {
 
   expect(Date.now()).toBe(1000);
 });
+
+test('fake timers with Date argument', () => {
+  jest.useFakeTimers('modern');
+
+  jest.setSystemTime(new Date(0));
+
+  expect(Date.now()).toBe(0);
+
+  jest.setSystemTime(new Date(1000));
+
+  expect(Date.now()).toBe(1000);
+});

packages/jest-environment/src/index.ts

@@ -306,5 +306,5 @@ export interface Jest {
    *
    *  > Note: This function is only available when using Lolex as fake timers implementation
    */
-  setSystemTime(now?: number): void;
+  setSystemTime(now?: number | Date): void;
 }

packages/jest-fake-timers/src/modernFakeTimers.ts

@@ -118,7 +118,7 @@ export default class FakeTimers {
     }
   }
 
-  setSystemTime(now?: number): void {
+  setSystemTime(now?: number | Date): void {
     if (this._checkFakeTimers()) {
       this._clock.setSystemTime(now);
     }

packages/jest-runtime/src/index.ts

@@ -1559,7 +1559,7 @@ class Runtime {
         _getFakeTimers().advanceTimersByTime(msToRun),
       setMock: (moduleName: string, mock: unknown) =>
         setMockFactory(moduleName, () => mock),
-      setSystemTime: (now?: number) => {
+      setSystemTime: (now?: number | Date) => {
         const fakeTimers = _getFakeTimers();
 
         if (fakeTimers instanceof ModernFakeTimers) {

website/versioned_docs/version-26.0/JestObjectAPI.md

@@ -648,13 +648,13 @@ This means, if any timers have been scheduled (but have not yet executed), they
 
 Returns the number of fake timers still left to run.
 
-### `.jest.setSystemTime()`
+### `jest.setSystemTime(now?: number | Date)`
 
 Set the current system time used by fake timers. Simulates a user changing the system clock while your program is running. It affects the current time but it does not in itself cause e.g. timers to fire; they will fire exactly as they would have done without the call to `jest.setSystemTime()`.
 
 > Note: This function is only available when using modern fake timers implementation
 
-### `.jest.getRealSystemTime()`
+### `jest.getRealSystemTime()`
 
 When mocking time, `Date.now()` will also be mocked. If you for some reason need access to the real current time, you can invoke this function.