feat(timers)!: expose setTickMode from fake-timers

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

The new `setTickMode` 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.nextAsync().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. `setTickMode({mode: "nextAsync"})` advances time as quickly possible and as far as necessary.

See: sinonjs/fake-timers@108efae

Author: atscott

docs/api/vi.md

@@ -1034,6 +1034,46 @@ The implementation is based internally on [`@sinonjs/fake-timers`](https://githu
 But you can enable it by specifying the option in `toFake` argument: `vi.useFakeTimers({ toFake: ['nextTick', 'queueMicrotask'] })`.
 :::
 
+### vi.setTimerTickMode
+
+- **Type:** `(mode: 'manual' | 'nextTimerAsync') => Vitest | (mode: 'interval', interval?: number) => Vitest`
+
+Controls how fake timers are advanced.
+
+- `manual`: The default behavior. Timers will only advance when you call one of `vi.advanceTimers...()` methods.
+- `nextTimerAsync`: Timers will be advanced automatically to the next available timer after each macrotask.
+- `interval`: Timers are advanced automatically by a specified interval.
+
+When `mode` is `'interval'`, you can also provide an `interval` in milliseconds.
+
+**Example:**
+
+```ts
+import { vi } from 'vitest'
+
+vi.useFakeTimers()
+
+// Manual mode (default)
+vi.setTimerTickMode({ mode: 'manual' })
+
+let i = 0
+setInterval(() => console.log(++i), 50)
+
+vi.advanceTimersByTime(150) // logs 1, 2, 3
+
+// nextTimerAsync mode
+vi.setTimerTickMode({ mode: 'nextTimerAsync' })
+
+// Timers will advance automatically after each macrotask
+await new Promise(resolve => setTimeout(resolve, 150)) // logs 4, 5, 6
+
+// interval mode (default when 'fakeTimers.shouldAdvanceTime' is `true`)
+vi.setTimerTickMode({ mode: 'interval', interval: 50 })
+
+// Timers will advance automatically every 50ms
+await new Promise(resolve => setTimeout(resolve, 150)) // logs 7, 8, 9
+```
+
 ### vi.isFakeTimers {#vi-isfaketimers}
 
 ```ts

packages/vitest/src/integrations/mock/timers.ts

@@ -212,6 +212,23 @@ export class FakeTimers {
     return 0
   }
 
+  setTimerTickMode(mode: 'manual' | 'nextTimerAsync' | 'interval', interval?: number): void {
+    if (this._checkFakeTimers()) {
+      if (mode === 'manual') {
+        this._clock.setTickMode({ mode: 'manual' })
+      }
+      else if (mode === 'nextTimerAsync') {
+        this._clock.setTickMode({ mode: 'nextAsync' })
+      }
+      else if (mode === 'interval') {
+        this._clock.setTickMode({ mode: 'interval', delta: interval })
+      }
+      else {
+        throw new Error(`Invalid tick mode: ${mode}`)
+      }
+    }
+  }
+
   configure(config: FakeTimerInstallOpts): void {
     this._userConfig = config
   }

packages/vitest/src/integrations/vi.ts

@@ -97,6 +97,16 @@ export interface VitestUtils {
    */
   clearAllTimers: () => VitestUtils
 
+  /**
+   * Controls how fake timers are advanced.
+   * @param mode The mode to use for advancing timers.
+   * - `manual`: The default behavior. Timers will only advance when you call one of `vi.advanceTimers...()` methods.
+   * - `nextTimerAsync`: Timers will be advanced automatically to the next available timer after each macrotask.
+   * - `interval`: Timers are advanced automatically by a specified interval.
+   * @param interval The interval in milliseconds to use when `mode` is `'interval'`.
+   */
+  setTimerTickMode: ((mode: 'manual' | 'nextTimerAsync') => VitestUtils) & ((mode: 'interval', interval?: number) => VitestUtils)
+
   /**
    * Creates a spy on a method or getter/setter of an object similar to [`vi.fn()`](https://vitest.dev/api/vi#vi-fn). It returns a [mock function](https://vitest.dev/api/mock).
    * @example
@@ -553,6 +563,11 @@ function createVitest(): VitestUtils {
       return utils
     },
 
+    setTimerTickMode(mode: 'manual' | 'nextTimerAsync' | 'interval', interval?: number) {
+      timers().setTimerTickMode(mode, interval)
+      return utils
+    },
+
     // mocks
 
     spyOn,

test/core/test/fixtures/timers.suite.ts

@@ -10,7 +10,7 @@
  * LICENSE file in the root directory of https://github.com/facebook/jest.
  */
 
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { FakeTimers } from '../../../../packages/vitest/src/integrations/mock/timers'
 
 class FakeDate extends Date {}
@@ -1503,4 +1503,86 @@ describe('FakeTimers', () => {
       timers.useRealTimers()
     })
   })
+
+  describe('setTimerTickMode', () => {
+    const realTimeout = setTimeout;
+    let timers: FakeTimers;
+
+    beforeEach(() => {
+      timers = new FakeTimers({ global })
+      timers.useFakeTimers();
+    })
+    afterEach(() => {
+      timers.useRealTimers();
+    })
+
+    it('can be set to manual', async () => {
+      const spy = vi.fn()
+      setTimeout(spy, 10)
+
+      timers.setTimerTickMode('manual')
+      await new Promise(resolve => realTimeout(resolve, 20))
+
+      expect(spy).not.toHaveBeenCalled()
+
+      timers.advanceTimersByTime(100)
+      expect(spy).toHaveBeenCalledOnce()
+    })
+
+    it('can be set to nextTimerAsync', async () => {
+      const spy = vi.fn()
+      setTimeout(spy, 10_000_000)
+
+      timers.setTimerTickMode('nextTimerAsync')
+      await new Promise(resolve => setTimeout(resolve, 20_000_000))
+
+      expect(spy).toHaveBeenCalledOnce()
+    })
+
+    it('can be set to interval', async () => {
+      const spy = vi.fn()
+      setTimeout(spy, 10)
+
+      timers.setTimerTickMode('interval', 5)
+      await new Promise(resolve => setTimeout(resolve, 15))
+
+      expect(spy).toHaveBeenCalledOnce()
+    })
+
+    it('can switch from nextTimerAsync to manual', async () => {
+      const spy = vi.fn()
+      setTimeout(spy, 10)
+
+      timers.setTimerTickMode('nextTimerAsync')
+
+      // Let one macrotask run, but the timer is not due yet.
+      await new Promise(resolve => setTimeout(resolve, 5))
+      expect(spy).not.toHaveBeenCalled()
+
+      timers.setTimerTickMode('manual')
+
+      await new Promise(resolve => realTimeout(resolve, 10))
+
+      expect(spy).not.toHaveBeenCalled()
+
+      timers.advanceTimersByTime(100)
+      expect(spy).toHaveBeenCalledOnce()
+    })
+
+    it('nextTimerAsync advances timers scheduled inside other timers', async () => {
+      const nestedSpy = vi.fn()
+      const spy = vi.fn(() => {
+        setTimeout(nestedSpy, 50)
+      })
+      setTimeout(spy, 100)
+
+      timers.setTimerTickMode('nextTimerAsync')
+
+      // Wait long enough for both timers to have a chance to run
+      await new Promise(resolve => setTimeout(resolve, 300))
+
+      expect(spy).toHaveBeenCalledOnce()
+      expect(nestedSpy).toHaveBeenCalledOnce()
+    })
+  })
 })