1---
2name: vi-utilities
3description: vi helper for mocking, timers, utilities
4---
5 
6# Vi Utilities
7 
8The `vi` helper provides mocking and utility functions.
9 
10```ts
11import { vi } from 'vitest'
12```
13 
14## Mock Functions
15 
16```ts
17// Create mock
18const fn = vi.fn()
19const fnWithImpl = vi.fn((x) => x * 2)
20 
21// Check if mock
22vi.isMockFunction(fn) // true
23 
24// Mock methods
25fn.mockReturnValue(42)
26fn.mockReturnValueOnce(1)
27fn.mockResolvedValue(data)
28fn.mockRejectedValue(error)
29fn.mockImplementation(() => 'result')
30fn.mockImplementationOnce(() => 'once')
31 
32// Clear/reset
33fn.mockClear()    // Clear call history
34fn.mockReset()    // Clear history + implementation
35fn.mockRestore()  // Restore original (for spies)
36```
37 
38## Spying
39 
40```ts
41const obj = { method: () => 'original' }
42 
43const spy = vi.spyOn(obj, 'method')
44obj.method()
45 
46expect(spy).toHaveBeenCalled()
47 
48// Mock implementation
49spy.mockReturnValue('mocked')
50 
51// Spy on getter/setter
52vi.spyOn(obj, 'prop', 'get').mockReturnValue('value')
53```
54 
55## Module Mocking
56 
57```ts
58// Hoisted to top of file
59vi.mock('./module', () => ({
60  fn: vi.fn(),
61}))
62 
63// Partial mock
64vi.mock('./module', async (importOriginal) => ({
65  ...(await importOriginal()),
66  specificFn: vi.fn(),
67}))
68 
69// Spy mode - keep implementation
70vi.mock('./module', { spy: true })
71 
72// Import actual module inside mock
73const actual = await vi.importActual('./module')
74 
75// Import as mock
76const mocked = await vi.importMock('./module')
77```
78 
79## Dynamic Mocking
80 
81```ts
82// Not hoisted - use with dynamic imports
83vi.doMock('./config', () => ({ key: 'value' }))
84const config = await import('./config')
85 
86// Unmock
87vi.doUnmock('./config')
88vi.unmock('./module') // Hoisted
89```
90 
91## Reset Modules
92 
93```ts
94// Clear module cache
95vi.resetModules()
96 
97// Wait for dynamic imports
98await vi.dynamicImportSettled()
99```
100 
101## Fake Timers
102 
103```ts
104vi.useFakeTimers()
105 
106setTimeout(() => console.log('done'), 1000)
107 
108// Advance time
109vi.advanceTimersByTime(1000)
110vi.advanceTimersByTimeAsync(1000)  // For async callbacks
111vi.advanceTimersToNextTimer()
112vi.advanceTimersToNextFrame()      // requestAnimationFrame
113 
114// Run all timers
115vi.runAllTimers()
116vi.runAllTimersAsync()
117vi.runOnlyPendingTimers()
118 
119// Clear timers
120vi.clearAllTimers()
121 
122// Check state
123vi.getTimerCount()
124vi.isFakeTimers()
125 
126// Restore
127vi.useRealTimers()
128```
129 
130## Mock Date/Time
131 
132```ts
133vi.setSystemTime(new Date('2024-01-01'))
134expect(new Date().getFullYear()).toBe(2024)
135 
136vi.getMockedSystemTime()  // Get mocked date
137vi.getRealSystemTime()    // Get real time (ms)
138```
139 
140## Global/Env Mocking
141 
142```ts
143// Stub global
144vi.stubGlobal('fetch', vi.fn())
145vi.unstubAllGlobals()
146 
147// Stub environment
148vi.stubEnv('API_KEY', 'test')
149vi.stubEnv('NODE_ENV', 'test')
150vi.unstubAllEnvs()
151```
152 
153## Hoisted Code
154 
155Run code before imports:
156 
157```ts
158const mock = vi.hoisted(() => vi.fn())
159 
160vi.mock('./module', () => ({
161  fn: mock, // Can reference hoisted variable
162}))
163```
164 
165## Waiting Utilities
166 
167```ts
168// Wait for callback to succeed
169await vi.waitFor(async () => {
170  const el = document.querySelector('.loaded')
171  expect(el).toBeTruthy()
172}, { timeout: 5000, interval: 100 })
173 
174// Wait for truthy value
175const element = await vi.waitUntil(
176  () => document.querySelector('.loaded'),
177  { timeout: 5000 }
178)
179```
180 
181## Mock Object
182 
183Mock all methods of an object:
184 
185```ts
186const original = {
187  method: () => 'real',
188  nested: { fn: () => 'nested' },
189}
190 
191const mocked = vi.mockObject(original)
192mocked.method()  // undefined (mocked)
193mocked.method.mockReturnValue('mocked')
194 
195// Spy mode
196const spied = vi.mockObject(original, { spy: true })
197spied.method()  // 'real'
198expect(spied.method).toHaveBeenCalled()
199```
200 
201## Test Configuration
202 
203```ts
204vi.setConfig({
205  testTimeout: 10_000,
206  hookTimeout: 10_000,
207})
208 
209vi.resetConfig()
210```
211 
212## Global Mock Management
213 
214```ts
215vi.clearAllMocks()   // Clear all mock call history
216vi.resetAllMocks()   // Reset + clear implementation
217vi.restoreAllMocks() // Restore originals (spies)
218```
219 
220## vi.mocked Type Helper
221 
222TypeScript helper for mocked values:
223 
224```ts
225import { myFn } from './module'
226vi.mock('./module')
227 
228// Type as mock
229vi.mocked(myFn).mockReturnValue('typed')
230 
231// Deep mocking
232vi.mocked(myModule, { deep: true })
233 
234// Partial mock typing
235vi.mocked(fn, { partial: true }).mockResolvedValue({ ok: true })
236```
237 
238## Key Points
239 
240- `vi.mock` is hoisted - use `vi.doMock` for dynamic mocking
241- `vi.hoisted` lets you reference variables in mock factories
242- Use `vi.spyOn` to spy on existing methods
243- Fake timers require explicit setup and teardown
244- `vi.waitFor` retries until assertion passes
245 
246<!-- 
247Source references:
248- https://vitest.dev/api/vi.html
249-->
250