Vitest Mocking
Test Double Types
| Type | Purpose | Changes Implementation? |
|---|---|---|
| Spy | Record calls, verify interactions | No (uses real code) |
| Mock | Replace module entirely | Yes |
| Stub | Return canned responses | Yes |
| Fake | Working but simplified impl | Yes |
Decision Guide
Use spy when: Verifying a function was called correctly while keeping real behavior
ts
const fetchSpy = vi.spyOn(globalThis, "fetch");
await doSomething();
expect(fetchSpy).toHaveBeenCalledWith("https://api.example.com");
Use mock when: Replacing external dependencies (network, database, third-party modules)
ts
vi.mock("./api-client");
vi.mocked(apiClient.fetch).mockResolvedValue({ data: "test" });
Use stubGlobal when: Replacing browser/Node globals
ts
vi.stubGlobal("fetch", vi.fn().mockResolvedValue(mockResponse));
Essential Patterns
Mock Module (hoisted)
ts
import { someFunc } from "./module";
vi.mock("./module"); // hoisted to top
it("test", () => {
vi.mocked(someFunc).mockReturnValue("mocked");
});
Mock with Implementation
ts
vi.mock("./module", () => ({
someFunc: vi.fn().mockReturnValue("mocked"),
}));
Spy with Fake Return
ts
const spy = vi.spyOn(obj, "method").mockReturnValue("fake");
Mock Global Fetch
ts
globalThis.fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ data: "test" }),
} as Response);
Fake Timers
ts
beforeAll(() => vi.useFakeTimers());
afterAll(() => vi.useRealTimers());
it("test", async () => {
// advance time
await vi.advanceTimersByTimeAsync(5000);
});
Clean Up
ts
beforeEach(() => vi.clearAllMocks()); // reset call counts afterEach(() => vi.restoreAllMocks()); // restore originals
Reference
For complete examples including default imports, named imports, classes, partial mocks, snapshot testing, composables, and verification patterns, see references/cheat-sheet.md.