variable
test.vi
Vitest-compatible mocking utilities, for migrating tests from Vitest to Bun.
vi.
vi.
vi.
vi.
function vi.advanceTimersByTime(
milliseconds: number
): { fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): Promise<unknown>; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): Promise<unknown>; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): Promise<unknown>; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): Promise<unknown>; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> };
Advance the fake clock and run the timers that come due.
function vi.advanceTimersByTimeAsync(
milliseconds: number
): Promise<{ fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): unknown; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): unknown; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): unknown; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): unknown; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> }>;
Like advanceTimersByTime, but runs promise jobs and one turn of the real event loop between timers, so it picks up timers that a callback schedules after an await.
function vi.advanceTimersToNextFrame(): { fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): Promise<unknown>; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): Promise<unknown>; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): Promise<unknown>; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): Promise<unknown>; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> };
Advance the fake clock to the next multiple of 16 milliseconds. That's when a faked requestAnimationFrame runs its callbacks.
function vi.advanceTimersToNextTimer(
steps?: number
): { fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): Promise<unknown>; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): Promise<unknown>; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): Promise<unknown>; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): Promise<unknown>; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> };
Advance the fake clock to the next timer and run every timer due at that time. Repeats steps times.
function vi.advanceTimersToNextTimerAsync(
steps?: number
): Promise<{ fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): unknown; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): unknown; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): unknown; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): unknown; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> }>;
Like advanceTimersToNextTimer, but runs promise jobs and one turn of the real event loop between timers.
function vi.clearAllMocks(): { fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): Promise<unknown>; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): Promise<unknown>; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): Promise<unknown>; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): Promise<unknown>; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> };
Clear all mock state (calls, results, etc.) without restoring original implementation
function vi.clearAllTimers(): { fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): Promise<unknown>; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): Promise<unknown>; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): Promise<unknown>; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): Promise<unknown>; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> };
function vi.doMock(
id: string,
): Disposable | Disposable & Promise<void>;
Like vi.mock, but the call isn't hoisted, so it only applies to imports that run after it.
Disposing the return value removes the mock, as in using _ = vi.doMock("./math", factory).
function vi.doMock<T>(
module: Promise<T>,
): Disposable | Disposable & Promise<void>;
function vi.doUnmock(
id: string | Promise<unknown>
): void;
Like vi.unmock, but the call isn't hoisted.
function vi.dynamicImportSettled(): Promise<void>;
Wait until every in-flight import() has settled, including ones that start during the wait.
function vi.getMockedSystemTime(): null | Date;
Returns the mocked time, or null if neither vi.setSystemTime() nor vi.useFakeTimers() is in effect.
function vi.getRealSystemTime(): number;
Returns the real time in milliseconds since the epoch, no matter what's faked.
function vi.getTimerCount(): number;
function vi.hoisted<T>(
factory: () => T
): T;
Calls factory and returns its result. The statement is hoisted above the file's imports, so a vi.mock factory can use the result.
const mocks = vi.hoisted(() => ({ add: vi.fn() }));
vi.mock("./math", () => ({ add: mocks.add }));function vi.importActual<T = any>(
id: string
): Promise<T>;
Import the real module id, even if it's mocked.
function vi.importMock<T = any>(
id: string
Import the mocked version of the module id, even if it isn't mocked.
function vi.isFakeTimers(): boolean;
function vi.mock<T>(
module: Promise<T>,
): void | Promise<void>;
Like vi.mock(id, factory), but takes import("./math") instead of a string, so importOriginal is typed as that module.
function vi.mock(
id: string,
): void | Promise<void>;
Replace a module with the return value of factory. The call is hoisted above the file's imports.
Without a factory, the module is replaced with the file of the same name in a __mocks__ directory. If there isn't one, it's replaced with a copy of the module where every function is a mock. With { spy: true }, the functions keep their implementation.
import { add } from "./math";
vi.mock("./math", async importOriginal => ({ ...(await importOriginal()), add: vi.fn(() => 3) }));function vi.mockObject<T>(
value: T,
options?: { spy: boolean }
Deeply mock value, the same way vi.mock() mocks a module when it has no factory. Returns a copy where functions and classes are mocks that return undefined and arrays are empty. Primitives and builtin objects are kept.
With { spy: true }, functions keep their implementation, arrays keep their elements, and objects are modified in place instead of copied.
const mocked = vi.mockObject({ add: (a: number, b: number) => a + b });
mocked.add(1, 2); // undefined
mocked.add.mockReturnValue(3);function vi.resetAllMocks(): { fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): Promise<unknown>; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): Promise<unknown>; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): Promise<unknown>; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): Promise<unknown>; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> };
Clear all mock state and implementations. A vi.fn(implementation) mock goes back to implementation, and a vi.spyOn() spy goes back to the original. Mocks made with jest.fn(), mock() or spyOn() return undefined.
function vi.resetConfig(): void;
Undo every vi.setConfig() call.
function vi.resetModules(): { fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): Promise<unknown>; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): Promise<unknown>; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): Promise<unknown>; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): Promise<unknown>; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> };
Re-evaluate each module on its next import() or require(). Mocked modules stay mocked.
function vi.restoreAllMocks(): { fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): Promise<unknown>; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): Promise<unknown>; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): Promise<unknown>; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): Promise<unknown>; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> };
Restore every spied-on property. A vi.spyOn() spy keeps its recorded calls and its implementation.
function vi.runAllTicks(): { fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): Promise<unknown>; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): Promise<unknown>; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): Promise<unknown>; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): Promise<unknown>; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> };
Run the callbacks queued with a faked process.nextTick or queueMicrotask.
function vi.runAllTimers(): { fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): Promise<unknown>; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): Promise<unknown>; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): Promise<unknown>; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): Promise<unknown>; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> };
Run timers until none are left. Throws after loopLimit timers.
function vi.runAllTimersAsync(): Promise<{ fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): unknown; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): unknown; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): unknown; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): unknown; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> }>;
Like runAllTimers, but runs promise jobs and one turn of the real event loop between timers.
function vi.runOnlyPendingTimers(): { fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): Promise<unknown>; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): Promise<unknown>; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): Promise<unknown>; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): Promise<unknown>; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> };
Advance the fake clock to the last timer that's currently pending.
function vi.runOnlyPendingTimersAsync(): Promise<{ fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): unknown; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): unknown; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): unknown; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): unknown; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> }>;
Like runOnlyPendingTimers, but runs promise jobs and one turn of the real event loop between timers.
function vi.setConfig(
config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }
): void;
Change the configuration for the rest of the test file. If a preload script calls it, the change applies to every test file. Vitest's other options are accepted but ignored.
function vi.setSystemTime(
now?: string | number | Date
): { fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): Promise<unknown>; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): Promise<unknown>; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): Promise<unknown>; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): Promise<unknown>; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> };
Set the time Date reports. Without fake timers, only Date is mocked, until you call vi.useRealTimers().
function vi.setTimerTickMode(
mode: 'manual' | 'nextTimerAsync'
): { fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): Promise<unknown>; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): Promise<unknown>; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): Promise<unknown>; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): Promise<unknown>; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> };
Choose how the fake clock moves when the test doesn't move it.
manual: it doesn't move. This is the default.nextTimerAsync: each turn of the real event loop runs the next timer.interval: it advances byintervalmilliseconds (default 20) everyintervalreal milliseconds.
function vi.setTimerTickMode(
mode: 'interval',
interval?: number
): { fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): Promise<unknown>; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): Promise<unknown>; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): Promise<unknown>; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): Promise<unknown>; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> };
function vi.stubEnv<T extends string>(
name: T,
value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string
): { fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): Promise<unknown>; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): Promise<unknown>; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): Promise<unknown>; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): Promise<unknown>; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> };
Set process.env[name], which is also import.meta.env[name]. The stub lasts until vi.unstubAllEnvs() or the end of the test file. Passing undefined deletes the variable.
function vi.stubGlobal(
name: string | number | symbol,
value: unknown
): { fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): Promise<unknown>; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): Promise<unknown>; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): Promise<unknown>; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): Promise<unknown>; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> };
Define globalThis[name]. The stub lasts until vi.unstubAllGlobals() or the end of the test file.
function vi.unmock(
id: string | Promise<unknown>
): void;
Stop mocking the module. The call is hoisted above the file's imports.
function vi.unstubAllEnvs(): { fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): Promise<unknown>; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): Promise<unknown>; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): Promise<unknown>; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): Promise<unknown>; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> };
Restore every variable changed by vi.stubEnv() to the value it had before it was first stubbed.
function vi.unstubAllGlobals(): { fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): Promise<unknown>; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): Promise<unknown>; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): Promise<unknown>; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): Promise<unknown>; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> };
Restore every global changed by vi.stubGlobal() to the property descriptor it had before it was first stubbed.
function vi.useFakeTimers(
): { fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): Promise<unknown>; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): Promise<unknown>; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): Promise<unknown>; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): Promise<unknown>; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> };
Replace the timer functions on globalThis with fakes that use a fake clock. The clock only moves when the test moves it. A reference saved before this call, such as const savedSetTimeout = setTimeout, stays real.
The real timers are restored when the test file ends, unless a preload made this call at its top level.
function vi.useRealTimers(): { fn: typeof jest.fn; isMockFunction: typeof jest.isMockFunction; mocked: typeof jest.mocked; spyOn: typeof spyOn; advanceTimersByTime(milliseconds: number): unknown; advanceTimersByTimeAsync(milliseconds: number): Promise<unknown>; advanceTimersToNextFrame(): unknown; advanceTimersToNextTimer(steps?: number): unknown; advanceTimersToNextTimerAsync(steps?: number): Promise<unknown>; clearAllMocks(): unknown; clearAllTimers(): unknown; doMock(id: string, factory?: ModuleMockOptions | ModuleMockFactory<any>): Disposable | Disposable & Promise<void>; doUnmock(id: string | Promise<unknown>): void; dynamicImportSettled(): Promise<void>; getMockedSystemTime(): null | Date; getRealSystemTime(): number; getTimerCount(): number; hoisted(factory: () => T): T; importActual(id: string): Promise<T>; importMock(id: string): Promise<Mocked<T>>; isFakeTimers(): boolean; mock(module: Promise<T>, factory?: ModuleMockOptions | ModuleMockFactory<T>): void | Promise<void>; mockObject(value: T, options?: { spy: boolean }): Mocked<T>; resetAllMocks(): unknown; resetConfig(): void; resetModules(): unknown; restoreAllMocks(): unknown; runAllTicks(): unknown; runAllTimers(): unknown; runAllTimersAsync(): Promise<unknown>; runOnlyPendingTimers(): unknown; runOnlyPendingTimersAsync(): Promise<unknown>; setConfig(config: { clearMocks: boolean; hookTimeout: number; maxConcurrency: number; mockReset: boolean; restoreMocks: boolean; testTimeout: number; unstubEnvs: boolean; unstubGlobals: boolean }): void; setSystemTime(now?: string | number | Date): unknown; setTimerTickMode(mode: 'manual' | 'nextTimerAsync'): unknown; stubEnv(name: T, value: T extends 'PROD' | 'DEV' | 'SSR' ? undefined | boolean : undefined | string): unknown; stubGlobal(name: string | number | symbol, value: unknown): unknown; unmock(id: string | Promise<unknown>): void; unstubAllEnvs(): unknown; unstubAllGlobals(): unknown; useFakeTimers(options?: 'modern' | FakeTimersOptions | 'legacy'): unknown; useRealTimers(): unknown; waitFor(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<T>; waitUntil(callback: () => T | Promise<T>, options?: number | { interval: number; timeout: number }): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>> };
Restore the real timer functions and clocks, and discard pending fake timers.
function vi.waitFor<T>(
callback: () => T | Promise<T>,
options?: number | { interval: number; timeout: number }
): Promise<T>;
Call callback right away, then every interval milliseconds, until it doesn't throw or reject. Resolves with its value. After timeout milliseconds, rejects with its last error.
The wait uses the real clock. While fake timers are on, vi.advanceTimersByTime(interval) runs before each call.
@param options
the timeout, or { timeout = 1000, interval = 50 }
await vi.waitFor(() => expect(server.isReady).toBe(true), { timeout: 500 });function vi.waitUntil<T>(
callback: () => T | Promise<T>,
options?: number | { interval: number; timeout: number }
): Promise<Exclude<T, undefined | null | false | '' | 0 | 0>>;
Call callback right away, then every interval milliseconds, until it returns a truthy value. Resolves with that value. Rejects right away if callback throws or rejects, and with a timeout error after timeout milliseconds.
The wait uses the real clock. While fake timers are on, vi.advanceTimersByTime(interval) runs before each call.
@param options
the timeout, or { timeout = 1000, interval = 50 }
const element = await vi.waitUntil(() => document.querySelector(".element"));