···10511051### vi.useFakeTimers
1052105210531053```ts
10541054-function useFakeTimers(config?: FakeTimerInstallOpts): Vitest
10541054+function useFakeTimers(config?: FakeTimersConfig): Vitest
10551055```
1056105610571057To enable mocking timers, you need to call this method. It will wrap all further calls to timers (such as `setTimeout`, `setInterval`, `clearTimeout`, `clearInterval`, `setImmediate`, `clearImmediate`, and `Date`) until [`vi.useRealTimers()`](#vi-userealtimers) is called.
···10641064`vi.useFakeTimers()` does not automatically mock `process.nextTick` and `queueMicrotask`.
10651065But you can enable it by specifying the option in `toFake` argument: `vi.useFakeTimers({ toFake: ['nextTick', 'queueMicrotask'] })`.
10661066:::
10671067+10681068+You can use `toFake` to specify which timers to mock, or `toNotFake` to specify which timers to keep native. Note that `toFake` and `toNotFake` cannot be specified together.
10691069+10701070+```ts
10711071+// only mock setTimeout and clearTimeout
10721072+vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] })
10731073+10741074+// mock all timers except setInterval
10751075+vi.useFakeTimers({ toNotFake: ['setInterval'] })
10761076+```
1067107710681078### vi.setTimerTickMode <Version>4.1.0</Version> {#vi-settimertickmode}
10691079
+15-4
docs/config/faketimers.md
···5566# fakeTimers
7788-- **Type:** `FakeTimerInstallOpts`
88+- **Type:** `FakeTimerConfig`
991010Options that Vitest will pass down to [`@sinon/fake-timers`](https://npmx.dev/package/@sinonjs/fake-timers) when using [`vi.useFakeTimers()`](/api/vi#vi-usefaketimers).
1111···2121- **Type:** `('setTimeout' | 'clearTimeout' | 'setImmediate' | 'clearImmediate' | 'setInterval' | 'clearInterval' | 'Date' | 'nextTick' | 'hrtime' | 'requestAnimationFrame' | 'cancelAnimationFrame' | 'requestIdleCallback' | 'cancelIdleCallback' | 'performance' | 'queueMicrotask')[]`
2222- **Default:** everything available globally except `nextTick` and `queueMicrotask`
23232424-An array with names of global methods and APIs to fake.
2424+An array with names of global methods and APIs to fake. For example, to only mock `setTimeout()` and `nextTick()`, specify this property as `['setTimeout', 'nextTick']`.
2525+2626+Mocking `nextTick` is not supported when running Vitest inside `node:child_process` by using `--pool=forks`. NodeJS uses `process.nextTick` internally in `node:child_process` and hangs when it is mocked. Mocking `nextTick` is supported when running Vitest with `--pool=threads`.
2727+2828+## fakeTimers.toNotFake
2929+3030+- **Type:** `('setTimeout' | 'clearTimeout' | 'setImmediate' | 'clearImmediate' | 'setInterval' | 'clearInterval' | 'Date' | 'nextTick' | 'hrtime' | 'requestAnimationFrame' | 'cancelAnimationFrame' | 'requestIdleCallback' | 'cancelIdleCallback' | 'performance' | 'queueMicrotask')[]`
3131+- **Default:** `[]`
3232+3333+An array with names of global methods and APIs to keep native. All other available timers will be mocked. For example, to keep `setInterval()` native and mock all other timers, specify this property as `['setInterval']`.
25342626-To only mock `setTimeout()` and `nextTick()`, specify this property as `['setTimeout', 'nextTick']`.
3535+Mocking `nextTick` is not supported when running Vitest inside `node:child_process` by using `--pool=forks`. When running with `--pool=forks`, Vitest automatically adds `nextTick` to the `toNotFake` array.
27362828-Mocking `nextTick` is not supported when running Vitest inside `node:child_process` by using `--pool=forks`. NodeJS uses `process.nextTick` internally in `node:child_process` and hangs when it is mocked. Mocking `nextTick` is supported when running Vitest with `--pool=threads`.
3737+::: warning
3838+Using both `toFake` and `toNotFake` together is not supported.
3939+:::
29403041## fakeTimers.loopLimit
3142
···66 */
7788import type {
99- FakeTimerInstallOpts,
1010- FakeTimerWithContext,
1111- InstalledClock,
99+ Clock,
1010+ FakeMethod,
1111+ Config as FakeTimersConfig,
1212+ FakeTimers as FakeTimersContext,
1213} from '@sinonjs/fake-timers'
1314import { withGlobal } from '@sinonjs/fake-timers'
1415import { isChildProcess } from '../../runtime/utils'
···16171718export class FakeTimers {
1819 private _global: typeof globalThis
1919- private _clock!: InstalledClock
2020+ private _clock!: Clock
2021 // | _fakingTime | _fakingDate |
2122 // +-------------+-------------+
2223 // | false | falsy | initial
···2526 // | true | truthy | unreachable
2627 private _fakingTime: boolean
2728 private _fakingDate: Date | null
2828- private _fakeTimers: FakeTimerWithContext
2929- private _userConfig?: FakeTimerInstallOpts
2929+ private _fakeTimers: FakeTimersContext
3030+ private _userConfig?: FakeTimersConfig
3031 private _now = RealDate.now
31323233 constructor({
···3435 config,
3536 }: {
3637 global: typeof globalThis
3737- config: FakeTimerInstallOpts
3838+ config: FakeTimersConfig
3839 }) {
3940 this._userConfig = config
4041···154155 this._clock.uninstall()
155156 }
156157157157- const toFake = Object.keys(this._fakeTimers.timers)
158158- // Do not mock timers internally used by node by default. It can still be mocked through userConfig.
159159- .filter(
160160- timer => timer !== 'nextTick' && timer !== 'queueMicrotask',
161161- ) as (keyof FakeTimerWithContext['timers'])[]
162162-163163- if (this._userConfig?.toFake?.includes('nextTick') && isChildProcess()) {
158158+ let toFake = this._userConfig?.toFake
159159+ if (isChildProcess() && toFake?.includes('nextTick')) {
164160 throw new Error(
165161 'process.nextTick cannot be mocked inside child_process',
166162 )
167163 }
168164165165+ let toNotFake = this._userConfig?.toNotFake
166166+ if (toFake === undefined && toNotFake === undefined) {
167167+ // Do not mock timers internally used by node by default. It can still be mocked through userConfig.
168168+ toFake = (Object.keys(this._fakeTimers.timers) as FakeMethod[])
169169+ .filter(timer => timer !== 'nextTick' && timer !== 'queueMicrotask')
170170+ }
171171+ if (isChildProcess() && toNotFake && !toNotFake.includes('nextTick')) {
172172+ toNotFake = [...toNotFake, 'nextTick']
173173+ }
174174+169175 this._clock = this._fakeTimers.install({
170176 now: fakeDate,
171177 ...this._userConfig,
172172- toFake: this._userConfig?.toFake || toFake,
178178+ ...(toFake && { toFake }),
179179+ ...(toNotFake && { toNotFake }),
173180 ignoreMissingTimers: true,
174181 })
175182···228235 }
229236 }
230237231231- configure(config: FakeTimerInstallOpts): void {
238238+ configure(config: FakeTimersConfig): void {
232239 this._userConfig = config
233240 }
234241
+3-3
packages/vitest/src/integrations/vi.ts
···11-import type { FakeTimerInstallOpts } from '@sinonjs/fake-timers'
11+import type { Config as FakeTimersConfig } from '@sinonjs/fake-timers'
22import type {
33 MaybeMocked,
44 MaybeMockedDeep,
···2727 /**
2828 * This method wraps all further calls to timers until [`vi.useRealTimers()`](https://vitest.dev/api/vi#vi-userealtimers) is called.
2929 */
3030- useFakeTimers: (config?: FakeTimerInstallOpts) => VitestUtils
3030+ useFakeTimers: (config?: FakeTimersConfig) => VitestUtils
3131 /**
3232 * Restores mocked timers to their original implementations. All timers that were scheduled before will be discarded.
3333 */
···496496 const _envBooleans = ['PROD', 'DEV', 'SSR']
497497498498 const utils: VitestUtils = {
499499- useFakeTimers(config?: FakeTimerInstallOpts) {
499499+ useFakeTimers(config?: FakeTimersConfig) {
500500 if (isChildProcess()) {
501501 if (
502502 config?.toFake?.includes('nextTick')
+2-2
packages/vitest/src/node/types/config.ts
···11-import type { FakeTimerInstallOpts } from '@sinonjs/fake-timers'
11+import type { Config as FakeTimersConfig } from '@sinonjs/fake-timers'
22import type { PrettyFormatOptions } from '@vitest/pretty-format'
33import type { SequenceHooks, SequenceSetupFiles, SerializableRetry, TestTagDefinition } from '@vitest/runner'
44import type { SnapshotStateOptions } from '@vitest/snapshot'
···617617 /**
618618 * Options for @sinon/fake-timers
619619 */
620620- fakeTimers?: FakeTimerInstallOpts
620620+ fakeTimers?: FakeTimersConfig
621621622622 /**
623623 * Custom handler for console.log in tests.
+2-2
packages/vitest/src/runtime/config.ts
···11-import type { FakeTimerInstallOpts } from '@sinonjs/fake-timers'
11+import type { Config as FakeTimersConfig } from '@sinonjs/fake-timers'
22import type { PrettyFormatOptions } from '@vitest/pretty-format'
33import type { SequenceHooks, SequenceSetupFiles, SerializableRetry, TestTagDefinition } from '@vitest/runner'
44import type { SnapshotEnvironment, SnapshotUpdateState } from '@vitest/snapshot'
···3434 unstubGlobals: boolean
3535 unstubEnvs: boolean
3636 // TODO: make optional
3737- fakeTimers: FakeTimerInstallOpts
3737+ fakeTimers: FakeTimersConfig
3838 maxConcurrency: number
3939 defines: Record<string, any>
4040 expect: {