Vitest

name: mocking description: Mock functions, modules, timers, and dates with vi utilities

Mocking

Mock Functions

import { expect, vi } from 'vitest'

// Create mock function
const fn = vi.fn()
fn('hello')

expect(fn).toHaveBeenCalled()
expect(fn).toHaveBeenCalledWith('hello')

// With implementation
const add = vi.fn((a, b) => a + b)
expect(add(1, 2)).toBe(3)

// Mock return values
fn.mockReturnValue(42)
fn.mockReturnValueOnce(1).mockReturnValueOnce(2)
fn.mockResolvedValue({ data: true })
fn.mockRejectedValue(new Error('fail'))

// Mock implementation
fn.mockImplementation((x) => x * 2)
fn.mockImplementationOnce(() => 'first call')

fn.mock.instances (and contexts) has one entry per call: this for plain calls, or the object new returned (undefined if the constructor threw). mockReturnValue/mockResolvedValue etc. throw when the mock is called with new; use mockImplementation for classes.

fn.mock.calls stores arguments by reference. If the argument is mutated after the call, assertions see the mutated value; clone at call time (e.g. mockImplementation(arg => calls.push(structuredClone(arg)))) when you need the pre-mutation state.

Spying on Objects

const cart = {
  getTotal: () => 100,
}

const spy = vi.spyOn(cart, 'getTotal')
cart.getTotal()

expect(spy).toHaveBeenCalled()

// Mock implementation
spy.mockReturnValue(200)
expect(cart.getTotal()).toBe(200)

// Restore original
spy.mockRestore()

Since v4, vi.spyOn/vi.fn can mock constructors — provide a function or class implementation (an arrow function throws "not a constructor"):

const Spy = vi.spyOn(cart, 'Apples').mockImplementation(class {
  getApples() { return 0 }
})
const instance = new Spy()

Conditional Mocking with vi.when (v5)

Define per-argument behaviors without writing if/switch in mockImplementation:

vi.when(db.findById)
  .calledWith(1)
  .thenResolve({ id: 1, name: 'Ella' })
  .calledWith(2)
  .thenResolve({ id: 2, name: 'Gracie' })

// Actions: thenReturn / thenThrow / thenResolve / thenReject (+ *Once variants)
// `calledWith` supports asymmetric matchers
vi.when(sendEmail).calledWith(expect.stringContaining('@')).thenReturn({ ok: true })

• Behaviors match first-in-first-out (register specific before broad); stacked actions on one behavior consume last-in-first-out, with { times } to limit.

• Handle unmatched calls with { onUnmatched: 'throw' | fn } (default falls through to the original implementation).

• Assert all behaviors ran with expect(w).toHaveBeenExhausted().

Auto-Cleanup with using

In runtimes with Explicit Resource Management (Node 24+, TS 5.2+), declare spies/mocks with using to auto-restore when the block exits — works with vi.spyOn, vi.fn, vi.doMock, and vi.when:

it('mocks console only here', () => {
  using spy = vi.spyOn(console, 'log').mockImplementation(() => {})
  debug('message')
  expect(spy).toHaveBeenCalled()
} ) // console.log restored automatically — no afterEach

Module Mocking

vi.mock, vi.unmock, and vi.hoisted are hoisted to the top of the file. In v5 calling them inside a function, block, or describe/test callback throws (it only warned before) — keep them at the module top level. Use vi.doMock/vi.doUnmock for non-hoisted, in-scope mocking.

// vi.mock is hoisted to top of file
vi.mock('./api', () => ({
  fetchUser: vi.fn(() => ({ id: 1, name: 'Mock' })),
}))

import { fetchUser } from './api'

test('mocked module', () => {
  expect(fetchUser()).toEqual({ id: 1, name: 'Mock' })
})

Typed Mocks with import()

Pass import('./db.js') instead of a string. TypeScript infers the module type, so the factory's return value is type-checked and importOriginal is typed. IDE renames/moves also update the path.

vi.mock(import('./db.js'), () => ({
  getUser: vi.fn(),
}))

Partial Mock

vi.mock(import('./utils'), async (importOriginal) => {
  const actual = await importOriginal()
  return {
    ...actual,
    specificFunction: vi.fn(),
  }
})

Auto-mock with Spy

// Keep implementation but spy on calls
vi.mock('./calculator', { spy: true })

import { add } from './calculator'

test('spy on module', () => {
  const result = add(1, 2) // Real implementation
  expect(result).toBe(3)
  expect(add).toHaveBeenCalledWith(1, 2)
})

Manual Mocks (mocks)

src/
  __mocks__/
    axios.ts      # Mocks 'axios'
  api/
    __mocks__/
      client.ts   # Mocks './client'
    client.ts

// Just call vi.mock with no factory
vi.mock('axios')
vi.mock('./api/client')

Dynamic Mocking (vi.doMock)

Not hoisted - use for dynamic imports:

test('dynamic mock', async () => {
  vi.doMock('./config', () => ({
    apiUrl: 'http://test.local',
  }))
  
  const { apiUrl } = await import('./config')
  expect(apiUrl).toBe('http://test.local')
  
  vi.doUnmock('./config')
})

Mock Timers

import { afterEach, beforeEach, vi } from 'vitest'

beforeEach(() => {
  vi.useFakeTimers()
})

afterEach(() => {
  vi.useRealTimers()
})

test('timers', () => {
  const fn = vi.fn()
  setTimeout(fn, 1000)
  
  expect(fn).not.toHaveBeenCalled()
  
  vi.advanceTimersByTime(1000)
  expect(fn).toHaveBeenCalled()
})

// Other timer methods
vi.runAllTimers()           // Run all pending timers
vi.runOnlyPendingTimers()   // Run only currently pending
vi.advanceTimersToNextTimer() // Advance to next timer

Async Timer Methods

test('async timers', async () => {
  vi.useFakeTimers()
  
  let resolved = false
  setTimeout(() => Promise.resolve().then(() => { resolved = true }), 100)
  
  await vi.advanceTimersByTimeAsync(100)
  expect(resolved).toBe(true)
})

Mock Dates

vi.setSystemTime(new Date('2024-01-01'))
expect(new Date().getFullYear()).toBe(2024)

vi.useRealTimers() // Restore

v5 fake timers (and vi.setSystemTime used without them) also mock Temporal when it's on the global object, not just Date:

vi.setSystemTime(0)
Temporal.Now.instant().epochMilliseconds // 0

// keep Temporal native:
vi.useFakeTimers({ toNotFake: ['Temporal'] })

Auto-advancing and Tick Modes

While fake timers are on, vi.waitFor/vi.waitUntil advance timers by interval before each check, and expect.poll advances by interval after each failed attempt, so they don't hang. vi.setTimerTickMode('interval' | 'nextTimerAsync') makes timers advance by themselves: interval steps fake time on a real-time interval (for state with a limited lifetime), nextTimerAsync fires the next pending timer after each macrotask (for code that eventually settles).

vi.setSystemTime and the now option of vi.useFakeTimers also accept Temporal.Instant/Temporal.ZonedDateTime. Set fakeTimers.fakeNodeBuiltins: true to also fake node:timers and node:timers/promises.

Mock Globals

vi.stubGlobal('fetch', vi.fn(() => 
  Promise.resolve({ json: () => ({ data: 'mock' }) })
))

// Restore
vi.unstubAllGlobals()

Mock Environment Variables

vi.stubEnv('API_KEY', 'test-key')
expect(import.meta.env.API_KEY).toBe('test-key')

// Restore
vi.unstubAllEnvs()

Clearing Mocks

const fn = vi.fn()
fn()

fn.mockClear()       // Clear call history
fn.mockReset()       // Clear history + implementation
fn.mockRestore()     // Restore original (for spies)

// Global
vi.clearAllMocks()
vi.resetAllMocks()
vi.restoreAllMocks()

Config Auto-Reset

// vitest.config.ts
defineConfig({
  test: {
    clearMocks: true,    // Clear call history before each test — v5 DEFAULT
    mockReset: true,     // Reset before each test
    restoreMocks: true,  // Restore after each test
    unstubEnvs: true,    // Restore env vars
    unstubGlobals: true, // Restore globals
  },
})

v5: clearMocks defaults to true, so mock call history no longer leaks between tests. Mocks set up outside the test body (setup files, module top level, beforeAll) are most affected — their recorded calls are cleared before the asserting test runs. Set clearMocks: false to restore the old behavior.

Hoisted Variables for Mocks

const mockFn = vi.hoisted(() => vi.fn())

vi.mock('./module', () => ({
  getData: mockFn,
}))

import { getData } from './module'

test('hoisted mock', () => {
  mockFn.mockReturnValue('test')
  expect(getData()).toBe('test')
})

v5 Behavior Changes

• Class mocks keep prototype methods. vi.fn(Dog), vi.spyOn(obj, 'Dog'), and .mockImplementation(class …) now chain the mock's prototype to the implementation's, so instance methods work and instanceof Dog passes. mockReset reverts the chain.

• Automocked modules stay automocked in the browser — their exports return undefined unless you pass { spy: true } or a factory.

v4 Behavior Changes

• vi.fn().getMockName() returns 'vi.fn()' (was 'spy'); snapshots show [MockFunction] instead of [MockFunction spy].

• vi.restoreAllMocks (and restoreMocks: true) now only restore vi.spyOn spies; automocks are unaffected. .mockRestore still resets a mock's implementation/state.

• vi.fn().mock.invocationCallOrder starts at 1 (Jest parity).

• Automocked getters return undefined by default; automocked methods can't be restored.

Key Points

• Prefer vi.mock for module mocking (hoisted - called before imports)

• Use vi.doMock for dynamic, non-hoisted mocking

• Use vi.when for argument-specific behaviors; using for scoped auto-restore

• Use { spy: true } to keep implementation but track calls

• vi.hoisted lets you reference variables in mock factories

• Prefer vi.mock(import('./mod'), factory) over a string path for type-checked factories

<!-- Source references: - https://vitest.dev/guide/mocking.html - https://vitest.dev/guide/learn/mock-functions - https://vitest.dev/api/vi.html - https://vitest.dev/guide/recipes/conditional-mocking - https://vitest.dev/guide/recipes/explicit-resources -->