vitest-mocking

Vitest模拟模式和测试双重策略。编写需要模拟、间谍、存根或假对象的测试时使用。触发器包括:模拟模块、存根全局对象(fetch, Date, timers)、测试组合式函数、模拟导入(默认/命名)、创建测试双重对象、替换依赖项、验证模拟调用、清理模拟或任何关于"如何在Vitest中模拟X"的问题。审查测试以确认模拟实践时也使用。

📖 中文导读:Vitest模拟模式和测试双重策略。编写需要模拟、间谍、存根或假对象的测试时使用。触发器包括:模拟模块、存根全局对象(fetch, Date, timers)、测试组合式函数、模拟导入(默认/命名)、创建测试双重对象、替换依赖项、验证模拟调用、清理模拟或任何关于"如何在Vitest中模拟X"的问题。审查测试以确认模拟实践时也使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: vitest-mocking description: | Vitest mocking patterns and test double strategies. Use when writing tests that need mocks, spies, stubs, or fakes. Triggers include: mocking modules, stubbing globals (fetch, Date, timers), testing composables, mocking imports (default/named), creating test doubles, replacing dependencies, verifying mock calls, cleaning up mocks, or any question about "how do I mock X in Vitest". Also use when reviewing tests for proper mocking practices.

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

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)

vi.mock("./api-client");
vi.mocked(apiClient.fetch).mockResolvedValue({ data: "test" });

Use stubGlobal when: Replacing browser/Node globals

vi.stubGlobal("fetch", vi.fn().mockResolvedValue(mockResponse));

Essential Patterns

Mock Module (hoisted)

import { someFunc } from "./module";
vi.mock("./module"); // hoisted to top

it("test", () => {
  vi.mocked(someFunc).mockReturnValue("mocked");
});

Mock with Implementation

vi.mock("./module", () => ({
  someFunc: vi.fn().mockReturnValue("mocked"),
}));

Spy with Fake Return

const spy = vi.spyOn(obj, "method").mockReturnValue("fake");

Mock Global Fetch

globalThis.fetch = vi.fn().mockResolvedValue({
  ok: true,
  json: async () => ({ data: "test" }),
} as Response);

Fake Timers

beforeAll(() => vi.useFakeTimers());
afterAll(() => vi.useRealTimers());

it("test", async () => {
  // advance time
  await vi.advanceTimersByTimeAsync(5000);
});

Clean Up

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.