feat: update to sinon/fake-timers v15 and add setTickMode to timer controls (#8726)

atscott · sheremet-va · web-flow · commit 4b480aaedb53 · 2026-01-13T19:22:46.000+01:00
Co-authored-by: Vladimir &lt;sleuths.slews0s@icloud.com&gt;
diff --git a/docs/api/vi.md b/docs/api/vi.md
@@ -1052,6 +1052,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 <Version>4.1.0</Version> {#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
diff --git a/packages/vitest/package.json b/packages/vitest/package.json
@@ -195,15 +195,15 @@
     "@edge-runtime/vm": "^5.0.0",
     "@jridgewell/trace-mapping": "catalog:",
     "@opentelemetry/api": "^1.9.0",
-    "@sinonjs/fake-timers": "14.0.0",
+    "@sinonjs/fake-timers": "15.0.0",
     "@types/estree": "catalog:",
     "@types/istanbul-lib-coverage": "catalog:",
     "@types/istanbul-reports": "catalog:",
     "@types/jsdom": "^27.0.0",
     "@types/node": "^24.10.7",
     "@types/picomatch": "^4.0.2",
     "@types/prompts": "^2.4.9",
-    "@types/sinonjs__fake-timers": "^8.1.5",
+    "@types/sinonjs__fake-timers": "^15.0.0",
     "acorn-walk": "catalog:",
     "birpc": "catalog:",
     "cac": "catalog:",
diff --git a/packages/vitest/src/integrations/mock/timers.ts b/packages/vitest/src/integrations/mock/timers.ts
@@ -127,7 +127,6 @@ export class FakeTimers {
 
   runAllTicks(): void {
     if (this._checkFakeTimers()) {
-      // @ts-expect-error method not exposed
       this._clock.runMicrotasks()
     }
   }
@@ -212,6 +211,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
   }
diff --git a/packages/vitest/src/integrations/vi.ts b/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
@@ -555,6 +565,11 @@ function createVitest(): VitestUtils {
       return utils
     },
 
+    setTimerTickMode(mode: 'manual' | 'nextTimerAsync' | 'interval', interval?: number) {
+      timers().setTimerTickMode(mode, interval)
+      return utils
+    },
+
     // mocks
 
     spyOn,
diff --git a/patches/@sinonjs__fake-timers@15.0.0.patch b/patches/@sinonjs__fake-timers@15.0.0.patch
@@ -1,5 +1,5 @@
 diff --git a/src/fake-timers-src.js b/src/fake-timers-src.js
-index 11dab90bd4bafd8c3a232df20f82ec5bcf06e76d..1f633e6293bc4bff97ccf9a23214944c0f6f8395 100644
+index a9bcfd1ca..942539085 100644
 --- a/src/fake-timers-src.js
 +++ b/src/fake-timers-src.js
 @@ -2,14 +2,14 @@
@@ -20,7 +20,7 @@ index 11dab90bd4bafd8c3a232df20f82ec5bcf06e76d..1f633e6293bc4bff97ccf9a23214944c
      } catch (e) {
          // ignored
      }
-@@ -172,7 +172,7 @@ function withGlobal(_global) {
+@@ -197,7 +197,7 @@ function withGlobal(_global) {
          isPresent.hrtime && typeof _global.process.hrtime.bigint === "function";
      isPresent.nextTick =
          _global.process && typeof _global.process.nextTick === "function";
diff --git a/patches/@types__sinonjs__fake-timers@8.1.5.patch b/patches/@types__sinonjs__fake-timers@8.1.5.patch
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
@@ -38,8 +38,7 @@ overrides:
   vitest: workspace:*
 
 patchedDependencies:
-  '@sinonjs/fake-timers@14.0.0': patches/@sinonjs__fake-timers@14.0.0.patch
-  '@types/sinonjs__fake-timers@8.1.5': patches/@types__sinonjs__fake-timers@8.1.5.patch
+  '@sinonjs/fake-timers@15.0.0': patches/@sinonjs__fake-timers@15.0.0.patch
   acorn@8.11.3: patches/acorn@8.11.3.patch
   cac@6.7.14: patches/cac@6.7.14.patch
   istanbul-lib-source-maps: patches/istanbul-lib-source-maps.patch
diff --git a/test/core/test/fixtures/timers.suite.ts b/test/core/test/fixtures/timers.suite.ts
