vitest-mocking

| 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 |

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));

```

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

```

For complete examples including default imports, named imports, classes, partial mocks, snapshot testing, composables, and verification patterns, see [references/cheat-sheet.md](references/cheat-sheet.md).