feat(jest-fake-timers): Add feature to configure how timers advance

This change exposes the `setTimerTickMode` function from the underlying `fake-timers` library.
This is to align with the new feature introduced in `fake-timers`.

The new `setTimerTickMode` method allows developers to configure whether time should auto advance and what the delta should be after the clock has been created. Prior to this, it could only be done at creation time with `shouldAdvanceTime: true`.

This also adds a new mode for automatically advancing time that moves more quickly than the existing shouldAdvanceTime, which uses real time.

Testing with mock clocks can often turn into a real struggle when dealing with situations where some work in the test is truly async and other work is captured by the mock clock. When using mock clocks, testers are always forced to write tests with intimate knowledge of when the mock clock needs to be ticked. It is ideal for test code to be written in a way that is independent of whether a mock clock is installed.

`shouldAdvanceTime` is essentially `setInterval(() => clock.tick(ms), ms)` while this feature is `const loop = () => setTimeout(() => clock.advancetimerstoNextTimerAsync().then(() => loop()), 0);`

There are two key differences:
1. `shouldAdvanceTime` uses `clock.tick(ms)` so it synchronously runs all timers inside the "ms" of the clock queue. This doesn't allow the microtask queue to empty between the macrotask timers in the clock.
2. `shouldAdvanceTime` uses real time to advance the same amount of real time in the mock clock. `setTimerTickMode({mode: "nextAsync"})` advances time as quickly possible and as far as necessary.

See: sinonjs/fake-timers@108efae

Author: atscott

CHANGELOG.md

@@ -3,6 +3,7 @@
 ### Features
 
 - `[jest-config]` Add `defineConfig` and `mergeConfig` helpers for type-safe Jest config ([#15844](https://github.com/jestjs/jest/pull/15844))
+- `[jest-fake-timers]` Add `setTimerTickMode` to configure how timers advance
 
 ### Fixes
 
@@ -12,6 +13,7 @@
 ### Chore & Maintenance
 
 - `[docs]` Update V30 migration guide to notify users on `jest.mock()` work with case-sensitive path ([#15849](https://github.com/jestjs/jest/pull/15849))
+- `[deps]` Update to sinon/fake-timers v15
 
 ## 30.2.0
 

docs/JestObjectAPI.md

@@ -1126,6 +1126,29 @@ This function is not available when using legacy fake timers implementation.
 
 :::
 
+### `jest.setTimerTickMode(mode)`
+
+Allows configuring how fake timers advance time.
+
+Configuration options:
+
+```ts
+type TimerTickMode =
+  | {mode: 'manual'}
+  | {mode: 'nextAsync'}
+  | {mode: 'interval'; delta?: number};
+```
+
+- `manual`: Timers do not advance without explicit, manual calls to the tick APIs (`jest.advanceTimersByTime(ms)`, `jest.runAllTimers()`, etc).
+- `nextAsync`: The clock will continuously break the event loop, then run the next timer until the mode changes.
+- `interval`: This is the same as specifying `advanceTimers: true` with an `advanceTimeDelta`. If the delta is not specified, 20 will be used by default.
+
+:::info
+
+This function is not available when using legacy fake timers implementation.
+
+:::
+
 ### `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/fake-timers/set-timer-tick-mode/__tests__/setTimerTickMode.test.js

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+const realSetTimeout = setTimeout;
+
+describe('jest.setTimerTickMode', () => {
+  it('should not advance the clock with manual', async () => {
+    jest.useFakeTimers();
+    jest.setTimerTickMode({mode: 'manual'});
+    const spy = jest.fn();
+    setTimeout(spy, 5);
+    await new Promise(resolve => realSetTimeout(resolve, 20));
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it('should advance the clock to next timer with nextAsync', async () => {
+    jest.useFakeTimers();
+    jest.setTimerTickMode({mode: 'nextAsync'});
+    await new Promise(resolve => setTimeout(resolve, 5000));
+    await new Promise(resolve => setTimeout(resolve, 5000));
+    await new Promise(resolve => setTimeout(resolve, 5000));
+    await new Promise(resolve => setTimeout(resolve, 5000));
+    // test should not time out
+  });
+
+  it('should advance the clock in real time with delta', async () => {
+    jest.useFakeTimers();
+    jest.setTimerTickMode({delta: 10, mode: 'interval'});
+    const spy = jest.fn();
+    setTimeout(spy, 10);
+    await new Promise(resolve => realSetTimeout(resolve, 5));
+    expect(spy).not.toHaveBeenCalled();
+    await new Promise(resolve => realSetTimeout(resolve, 5));
+    expect(spy).toHaveBeenCalled();
+  });
+});

e2e/fake-timers/set-timer-tick-mode/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "set-timer-tick-mode-e2e",
+  "private": true,
+  "version": "1.0.0"
+}

packages/jest-environment/src/index.ts

@@ -425,4 +425,25 @@ export interface Jest {
    * performance, time and timer APIs.
    */
   useRealTimers(): Jest;
+  /**
+   * Updates the mode of advancing timers when using fake timers.
+   *
+   * @param config The configuration to use for advancing timers
+   *
+   * When the mode is 'interval', timers will be advanced automatically by the [delta]
+   * milliseconds every [delta] milliseconds of real time. The default delta is 20 milliseconds.
+   *
+   * When mode is 'nextAsync', configures whether timers advance automatically to the next timer in the queue after each macrotask.
+   * This mode differs from 'interval' in that it advances all the way to the next timer, regardless
+   * of how far in the future that timer is scheduled (e.g. advanceTimersToNextTimerAsync).
+   *
+   * When mode is 'manual' (the default), timers will not advance automatically. Instead,
+   * timers must be advanced using APIs such as `advanceTimersToNextTimer`, `advanceTimersByTime`, etc.
+   *
+   * @remarks
+   * Not available when using legacy fake timers implementation.
+   */
+  setTimerTickMode(
+    config: {mode: 'manual' | 'nextAsync'} | {mode: 'interval'; delta?: number},
+  ): Jest;
 }

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

@@ -73,9 +73,7 @@ describe('FakeTimers', () => {
         Date,
         clearInterval,
         clearTimeout,
-        process: {
-          nextTick: origNextTick,
-        },
+        process: {nextTick: origNextTick},
         setInterval,
         setTimeout,
       } as unknown as typeof globalThis;
@@ -153,9 +151,7 @@ describe('FakeTimers', () => {
         Date,
         clearInterval,
         clearTimeout,
-        process: {
-          nextTick: () => {},
-        },
+        process: {nextTick: () => {}},
         setInterval,
         setTimeout,
       } as unknown as typeof globalThis;
@@ -186,9 +182,7 @@ describe('FakeTimers', () => {
         Date,
         clearInterval,
         clearTimeout,
-        process: {
-          nextTick,
-        },
+        process: {nextTick},
         setInterval,
         setTimeout,
       } as unknown as typeof globalThis;
@@ -205,9 +199,7 @@ describe('FakeTimers', () => {
         Date,
         clearInterval,
         clearTimeout,
-        process: {
-          nextTick: () => {},
-        },
+        process: {nextTick: () => {}},
         setInterval,
         setTimeout,
       } as unknown as typeof globalThis;
@@ -231,9 +223,7 @@ describe('FakeTimers', () => {
         Date,
         clearInterval,
         clearTimeout,
-        process: {
-          nextTick: () => {},
-        },
+        process: {nextTick: () => {}},
         setInterval,
         setTimeout,
       } as unknown as typeof globalThis;
@@ -902,9 +892,7 @@ describe('FakeTimers', () => {
         Date,
         clearInterval,
         clearTimeout,
-        process: {
-          nextTick: () => {},
-        },
+        process: {nextTick: () => {}},
         setImmediate: () => {},
         setInterval,
         setTimeout,
@@ -1430,6 +1418,48 @@ describe('FakeTimers', () => {
     });
   });
 
+  describe('setTimerTickMode', () => {
+    let global: typeof globalThis;
+    let timers: FakeTimers;
+    const realSetTimeout = setTimeout;
+    beforeEach(() => {
+      global = {
+        Date,
+        Promise,
+        clearInterval,
+        clearTimeout,
+        process,
+        setInterval,
+        setTimeout,
+      } as unknown as typeof globalThis;
+      timers = new FakeTimers({config: makeProjectConfig(), global});
+      timers.useFakeTimers();
+    });
+
+    afterEach(() => {
+      timers.useRealTimers();
+    });
+
+    it('should advance the clock to next timer with nextAsync', async () => {
+      timers.setTimerTickMode({mode: 'nextAsync'});
+      await new Promise(resolve => global.setTimeout(resolve, 5000));
+      await new Promise(resolve => global.setTimeout(resolve, 5000));
+      await new Promise(resolve => global.setTimeout(resolve, 5000));
+      await new Promise(resolve => global.setTimeout(resolve, 5000));
+      // test should not time out
+    });
+
+    it('should advance the clock in real time with delta', async () => {
+      timers.setTimerTickMode({delta: 10, mode: 'interval'});
+      const spy = jest.fn();
+      global.setTimeout(spy, 10);
+      await new Promise(resolve => realSetTimeout(resolve, 5));
+      expect(spy).not.toHaveBeenCalled();
+      await new Promise(resolve => realSetTimeout(resolve, 5));
+      expect(spy).toHaveBeenCalled();
+    });
+  });
+
   describe('now', () => {
     let timers: FakeTimers;
     let fakedGlobal: typeof globalThis;

packages/jest-runtime/src/index.ts

@@ -1161,10 +1161,7 @@ export default class Runtime {
   private _getFullTransformationOptions(
     options: InternalModuleOptions = defaultTransformOptions,
   ): TransformationOptions {
-    return {
-      ...options,
-      ...this._coverageOptions,
-    };
+    return {...options, ...this._coverageOptions};
   }
 
   requireModuleOrMock<T = unknown>(from: string, moduleName: string): T {
@@ -1337,10 +1334,7 @@ export default class Runtime {
       .map(result => {
         const transformedFile = this._v8CoverageSources!.get(result.url);
 
-        return {
-          codeTransformResult: transformedFile,
-          result,
-        };
+        return {codeTransformResult: transformedFile, result};
       });
   }
 
@@ -1444,9 +1438,7 @@ export default class Runtime {
 
   private _resolveCjsModule(from: string, to: string | undefined) {
     return to
-      ? this._resolver.resolveModule(from, to, {
-          conditions: this.cjsConditions,
-        })
+      ? this._resolver.resolveModule(from, to, {conditions: this.cjsConditions})
       : from;
   }
 
@@ -2120,10 +2112,7 @@ export default class Runtime {
         get: (_target, key) =>
           typeof key === 'string' ? this._moduleRegistry.get(key) : undefined,
         getOwnPropertyDescriptor() {
-          return {
-            configurable: true,
-            enumerable: true,
-          };
+          return {configurable: true, enumerable: true};
         },
         has: (_target, key) =>
           typeof key === 'string' && this._moduleRegistry.has(key),
@@ -2428,6 +2417,21 @@ export default class Runtime {
         }
       },
       setTimeout,
+      setTimerTickMode: (
+        mode:
+          | {mode: 'manual' | 'nextAsync'}
+          | {mode: 'interval'; delta?: number},
+      ) => {
+        const fakeTimers = _getFakeTimers();
+        if (fakeTimers === this._environment.fakeTimersModern) {
+          fakeTimers.setTimerTickMode(mode);
+        } else {
+          throw new TypeError(
+            '`jest.setTimerTickMode()` is not available when using legacy fake timers.',
+          );
+        }
+        return jestObject;
+      },
       spyOn,
       unmock,
       unstable_mockModule: mockModule,

packages/jest-types/__typetests__/jest.test.ts

@@ -651,6 +651,11 @@ expect(jest.useFakeTimers('modern')).type.toRaiseError();
 expect(jest.useRealTimers()).type.toBe<typeof jest>();
 expect(jest.useRealTimers(true)).type.toRaiseError();
 
+expect(jest.setTimerTickMode('manual')).type.toRaiseError();
+expect(jest.setTimerTickMode({mode: 'interval'})).type.toBe<typeof jest>();
+expect(jest.setTimerTickMode({mode: 'manual'})).type.toBe<typeof jest>();
+expect(jest.setTimerTickMode({mode: 'nextAsync'})).type.toBe<typeof jest>();
+
 // Misc
 
 expect(jest.retryTimes(3)).type.toBe<typeof jest>();