diff --git a/types/jest/index.d.ts b/types/jest/index.d.ts index f3e2c34e122726..c3dd4e6f852d64 100644 --- a/types/jest/index.d.ts +++ b/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 @@ -72,6 +72,77 @@ type ExtractEachCallbackArgs> = { : '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; + /** + * 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; diff --git a/types/jest/jest-tests.ts b/types/jest/jest-tests.ts index 908caf0078d8dc..91e3b7da8eb4d8 100644 --- a/types/jest/jest-tests.ts +++ b/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();