Skip to content

fakeTimers ​

  • Type: FakeTimerConfig

Options that Vitest will pass down to @sinon/fake-timers when using vi.useFakeTimers().

fakeTimers.now ​

  • Type: number | Date
  • Default: Date.now()

Installs fake timers with the specified Unix epoch.

fakeTimers.toFake ​

  • Type: ('setTimeout' | 'clearTimeout' | 'setImmediate' | 'clearImmediate' | 'setInterval' | 'clearInterval' | 'Date' | 'nextTick' | 'hrtime' | 'requestAnimationFrame' | 'cancelAnimationFrame' | 'requestIdleCallback' | 'cancelIdleCallback' | 'performance' | 'queueMicrotask' | 'Intl' | 'Temporal')[]
  • Default: everything available globally except nextTick and queueMicrotask

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'].

Temporal is only faked when it is available on the global object: natively (Node.js >= 26 by default, behind --harmony-temporal on older versions, and supporting browsers) or through a globally installed polyfill such as import 'temporal-polyfill/global'.

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.

fakeTimers.toNotFake ​

  • Type: ('setTimeout' | 'clearTimeout' | 'setImmediate' | 'clearImmediate' | 'setInterval' | 'clearInterval' | 'Date' | 'nextTick' | 'hrtime' | 'requestAnimationFrame' | 'cancelAnimationFrame' | 'requestIdleCallback' | 'cancelIdleCallback' | 'performance' | 'queueMicrotask' | 'Intl' | 'Temporal')[]
  • Default: []

An array of global methods and APIs to exclude from fake timers. Vitest always excludes nextTick and queueMicrotask when this option is used. To fake either API, use toFake instead.

WARNING

Using both toFake and toNotFake together is not supported.

fakeTimers.loopLimit ​

  • Type: number
  • Default: 10_000

The maximum number of timers that will be run when calling vi.runAllTimers().

fakeTimers.shouldAdvanceTime ​

  • Type: boolean
  • Default: false

Tells @sinonjs/fake-timers to increment mocked time automatically based on the real system time shift (e.g. the mocked time will be incremented by 20ms for every 20ms change in the real system time).

fakeTimers.advanceTimeDelta ​

  • Type: number
  • Default: 20

Relevant only when using with shouldAdvanceTime: true. increment mocked time by advanceTimeDelta ms every advanceTimeDelta ms change in the real system time.

fakeTimers.fakeNodeBuiltins 5.1.0+ ​

  • Type: boolean
  • Default: false

Also fake the timers exported by the node:timers and node:timers/promises modules, following the same toFake and toNotFake selection as the global timers. This covers the setTimeout, setInterval, setImmediate and clear* functions of node:timers, and the promise-based setTimeout, setInterval and setImmediate of node:timers/promises. Named imports are updated together with the module objects.

ts
import { setTimeout as sleep } from 'node:timers/promises'

vi.useFakeTimers({ fakeNodeBuiltins: true })

const promise = sleep(1000)
await vi.advanceTimersByTimeAsync(1000)
await promise // resolved by the fake clock

This option has no effect in the browser.

fakeTimers.shouldClearNativeTimers ​

  • Type: boolean
  • Default: true

Tells fake timers to clear "native" (i.e. not fake) timers by delegating to their respective handlers. When disabled, it can lead to potentially unexpected behavior if timers existed prior to starting fake timers session.