1---
2name: mocking
3description: Mock functions, modules, timers, and dates with vi utilities
4---
5 
6# Mocking
7 
8## Mock Functions
9 
10```ts
11import { expect, vi } from 'vitest'
12 
13// Create mock function
14const fn = vi.fn()
15fn('hello')
16 
17expect(fn).toHaveBeenCalled()
18expect(fn).toHaveBeenCalledWith('hello')
19 
20// With implementation
21const add = vi.fn((a, b) => a + b)
22expect(add(1, 2)).toBe(3)
23 
24// Mock return values
25fn.mockReturnValue(42)
26fn.mockReturnValueOnce(1).mockReturnValueOnce(2)
27fn.mockResolvedValue({ data: true })
28fn.mockRejectedValue(new Error('fail'))
29 
30// Mock implementation
31fn.mockImplementation((x) => x * 2)
32fn.mockImplementationOnce(() => 'first call')
33```
34 
35## Spying on Objects
36 
37```ts
38const cart = {
39  getTotal: () => 100,
40}
41 
42const spy = vi.spyOn(cart, 'getTotal')
43cart.getTotal()
44 
45expect(spy).toHaveBeenCalled()
46 
47// Mock implementation
48spy.mockReturnValue(200)
49expect(cart.getTotal()).toBe(200)
50 
51// Restore original
52spy.mockRestore()
53```
54 
55## Module Mocking
56 
57```ts
58// vi.mock is hoisted to top of file
59vi.mock('./api', () => ({
60  fetchUser: vi.fn(() => ({ id: 1, name: 'Mock' })),
61}))
62 
63import { fetchUser } from './api'
64 
65test('mocked module', () => {
66  expect(fetchUser()).toEqual({ id: 1, name: 'Mock' })
67})
68```
69 
70### Partial Mock
71 
72```ts
73vi.mock('./utils', async (importOriginal) => {
74  const actual = await importOriginal()
75  return {
76    ...actual,
77    specificFunction: vi.fn(),
78  }
79})
80```
81 
82### Auto-mock with Spy
83 
84```ts
85// Keep implementation but spy on calls
86vi.mock('./calculator', { spy: true })
87 
88import { add } from './calculator'
89 
90test('spy on module', () => {
91  const result = add(1, 2) // Real implementation
92  expect(result).toBe(3)
93  expect(add).toHaveBeenCalledWith(1, 2)
94})
95```
96 
97### Manual Mocks (__mocks__)
98 
99```
100src/
101  __mocks__/
102    axios.ts      # Mocks 'axios'
103  api/
104    __mocks__/
105      client.ts   # Mocks './client'
106    client.ts
107```
108 
109```ts
110// Just call vi.mock with no factory
111vi.mock('axios')
112vi.mock('./api/client')
113```
114 
115## Dynamic Mocking (vi.doMock)
116 
117Not hoisted - use for dynamic imports:
118 
119```ts
120test('dynamic mock', async () => {
121  vi.doMock('./config', () => ({
122    apiUrl: 'http://test.local',
123  }))
124  
125  const { apiUrl } = await import('./config')
126  expect(apiUrl).toBe('http://test.local')
127  
128  vi.doUnmock('./config')
129})
130```
131 
132## Mock Timers
133 
134```ts
135import { afterEach, beforeEach, vi } from 'vitest'
136 
137beforeEach(() => {
138  vi.useFakeTimers()
139})
140 
141afterEach(() => {
142  vi.useRealTimers()
143})
144 
145test('timers', () => {
146  const fn = vi.fn()
147  setTimeout(fn, 1000)
148  
149  expect(fn).not.toHaveBeenCalled()
150  
151  vi.advanceTimersByTime(1000)
152  expect(fn).toHaveBeenCalled()
153})
154 
155// Other timer methods
156vi.runAllTimers()           // Run all pending timers
157vi.runOnlyPendingTimers()   // Run only currently pending
158vi.advanceTimersToNextTimer() // Advance to next timer
159```
160 
161### Async Timer Methods
162 
163```ts
164test('async timers', async () => {
165  vi.useFakeTimers()
166  
167  let resolved = false
168  setTimeout(() => Promise.resolve().then(() => { resolved = true }), 100)
169  
170  await vi.advanceTimersByTimeAsync(100)
171  expect(resolved).toBe(true)
172})
173```
174 
175## Mock Dates
176 
177```ts
178vi.setSystemTime(new Date('2024-01-01'))
179expect(new Date().getFullYear()).toBe(2024)
180 
181vi.useRealTimers() // Restore
182```
183 
184## Mock Globals
185 
186```ts
187vi.stubGlobal('fetch', vi.fn(() => 
188  Promise.resolve({ json: () => ({ data: 'mock' }) })
189))
190 
191// Restore
192vi.unstubAllGlobals()
193```
194 
195## Mock Environment Variables
196 
197```ts
198vi.stubEnv('API_KEY', 'test-key')
199expect(import.meta.env.API_KEY).toBe('test-key')
200 
201// Restore
202vi.unstubAllEnvs()
203```
204 
205## Clearing Mocks
206 
207```ts
208const fn = vi.fn()
209fn()
210 
211fn.mockClear()       // Clear call history
212fn.mockReset()       // Clear history + implementation
213fn.mockRestore()     // Restore original (for spies)
214 
215// Global
216vi.clearAllMocks()
217vi.resetAllMocks()
218vi.restoreAllMocks()
219```
220 
221## Config Auto-Reset
222 
223```ts
224// vitest.config.ts
225defineConfig({
226  test: {
227    clearMocks: true,    // Clear before each test
228    mockReset: true,     // Reset before each test
229    restoreMocks: true,  // Restore after each test
230    unstubEnvs: true,    // Restore env vars
231    unstubGlobals: true, // Restore globals
232  },
233})
234```
235 
236## Hoisted Variables for Mocks
237 
238```ts
239const mockFn = vi.hoisted(() => vi.fn())
240 
241vi.mock('./module', () => ({
242  getData: mockFn,
243}))
244 
245import { getData } from './module'
246 
247test('hoisted mock', () => {
248  mockFn.mockReturnValue('test')
249  expect(getData()).toBe('test')
250})
251```
252 
253## Key Points
254 
255- `vi.mock` is hoisted - called before imports
256- Use `vi.doMock` for dynamic, non-hoisted mocking
257- Always restore mocks to avoid test pollution
258- Use `{ spy: true }` to keep implementation but track calls
259- `vi.hoisted` lets you reference variables in mock factories
260 
261<!-- 
262Source references:
263- https://vitest.dev/guide/mocking.html
264- https://vitest.dev/api/vi.html
265-->
266