[jest-28] fix types of jest.useFakeTimers()

types/jest/index.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for Jest 27.4
+// Type definitions for Jest 28.0.0-alpha
 // Project: https://jestjs.io/
 // Definitions by: Asana (https://asana.com)
 //                 Ivo Stratev <https://github.com/NoHomey>
@@ -72,6 +72,77 @@ type ExtractEachCallbackArgs<T extends ReadonlyArray<any>> = {
         : 'fallback'
 ];
 
+export type FakeableAPI =
+  | 'Date'
+  | 'hrtime'
+  | 'nextTick'
+  | 'performance'
+  | 'queueMicrotask'
+  | 'requestAnimationFrame'
+  | 'cancelAnimationFrame'
+  | 'requestIdleCallback'
+  | 'cancelIdleCallback'
+  | 'setImmediate'
+  | 'clearImmediate'
+  | 'setInterval'
+  | 'clearInterval'
+  | 'setTimeout'
+  | 'clearTimeout';
+
+type FakeTimersConfig = {
+  /**
+   * If set to `true` all timers will be advanced automatically
+   * by 20 milliseconds every 20 milliseconds. A custom time delta
+   * may be provided by passing a number.
+   *
+   * @defaultValue
+   * The default is `false`.
+   */
+  advanceTimers?: boolean | number;
+  /**
+   * List of names of APIs (e.g. `Date`, `nextTick()`, `setImmediate()`,
+   * `setTimeout()`) that should not be faked.
+   *
+   * @defaultValue
+   * The default is `[]`, meaning all APIs are faked.
+   * */
+  doNotFake?: Array<FakeableAPI>;
+  /**
+   * Sets current system time to be used by fake timers.
+   *
+   * @defaultValue
+   * The default is `Date.now()`.
+   */
+  now?: number | Date;
+  /**
+   * The maximum number of recursive timers that will be run when calling
+   * `jest.runAllTimers()`.
+   *
+   * @defaultValue
+   * The default is `100_000` timers.
+   */
+  timerLimit?: number;
+  /**
+   * Use the old fake timers implementation instead of one backed by
+   * [`@sinonjs/fake-timers`](https://github.com/sinonjs/fake-timers).
+   *
+   * @defaultValue
+   * The default is `false`.
+   */
+  legacyFakeTimers?: false;
+};
+
+type LegacyFakeTimersConfig = {
+  /**
+   * Use the old fake timers implementation instead of one backed by
+   * [`@sinonjs/fake-timers`](https://github.com/sinonjs/fake-timers).
+   *
+   * @defaultValue
+   * The default is `false`.
+   */
+  legacyFakeTimers?: true;
+};
+
 declare namespace jest {
     /**
      * Disables automatic mocking in the module loader.
@@ -319,11 +390,20 @@ declare namespace jest {
      */
     function unmock(moduleName: string): typeof jest;
     /**
-     * Instructs Jest to use fake versions of the standard timer functions.
+     * Instructs Jest to use fake versions of the global date, performance,
+     * time and timer APIs. Fake timers implementation is backed by
+     * [`@sinonjs/fake-timers`](https://github.com/sinonjs/fake-timers).
+     *
+     * @remarks
+     * Calling `jest.useFakeTimers()` once again in the same test file would reinstall
+     * fake timers using the provided options.
      */
-    function useFakeTimers(implementation?: 'modern' | 'legacy'): typeof jest;
+    function useFakeTimers(
+        fakeTimersConfig?: FakeTimersConfig | LegacyFakeTimersConfig,
+      ): typeof jest;
     /**
-     * Instructs Jest to use the real versions of the standard timer functions.
+     * Instructs Jest to restore the original implementations of the global date,
+     * performance, time and timer APIs.
      */
     function useRealTimers(): typeof jest;
 

types/jest/jest-tests.ts

@@ -300,11 +300,68 @@ jest.autoMockOff()
 jest.advanceTimersToNextTimer();
 jest.advanceTimersToNextTimer(2);
 
-// https://jestjs.io/docs/en/jest-object#jestusefaketimersimplementation-modern--legacy
-jest.useFakeTimers('modern');
+// https://jestjs.io/docs/jest-object#jestusefaketimersfaketimersconfig
+jest.useFakeTimers({ advanceTimers: true });
+jest.useFakeTimers({ advanceTimers: 10 });
+// $ExpectError
+jest.useFakeTimers({ advanceTimers: 'fast' });
+
+jest.useFakeTimers({ doNotFake: ['Date'] });
+jest.useFakeTimers({
+    doNotFake: [
+        'Date',
+        'hrtime',
+        'nextTick',
+        'performance',
+        'queueMicrotask',
+        'requestAnimationFrame',
+        'cancelAnimationFrame',
+        'requestIdleCallback',
+        'cancelIdleCallback',
+        'setImmediate',
+        'clearImmediate',
+        'setInterval',
+        'clearInterval',
+        'setTimeout',
+        'clearTimeout',
+    ],
+});
+// $ExpectError
+jest.useFakeTimers({ doNotFake: ['globalThis'] });
+
+jest.useFakeTimers({ legacyFakeTimers: true });
+// $ExpectError
+jest.useFakeTimers({ legacyFakeTimers: 1000 });
+// $ExpectError
+jest.useFakeTimers({ doNotFake: ['Date'], legacyFakeTimers: true });
+// $ExpectError
+jest.useFakeTimers({ enableGlobally: true, legacyFakeTimers: true });
+// $ExpectError
+jest.useFakeTimers({ legacyFakeTimers: true, now: 1483228800000 });
+// $ExpectError
+jest.useFakeTimers({ legacyFakeTimers: true, timerLimit: 1000 });
+
+jest.useFakeTimers({ now: 1483228800000 });
+jest.useFakeTimers({ now: Date.now() });
+jest.useFakeTimers({ now: new Date(1995, 11, 17) });
+// $ExpectError
+jest.useFakeTimers({ now: '1995-12-17T03:24:00' });
+
+jest.useFakeTimers({ timerLimit: 1000 });
+// $ExpectError
+jest.useFakeTimers({ timerLimit: true });
+
+// $ExpectError
+jest.useFakeTimers({ enableGlobally: true });
+// $ExpectError
 jest.useFakeTimers('legacy');
 // $ExpectError
-jest.useFakeTimers('foo');
+jest.useFakeTimers('modern');
+
+jest.useRealTimers();
+// $ExpectError
+jest.useRealTimers(true);
+
 
 // https://jestjs.io/docs/en/jest-object#jestsetsystemtimenow-number--date
 jest.setSystemTime();