vitest - SKILL.md Agent Skill

name: vitest description: Use when the user asks about Vitest mocking, spies, stubs, fake timers, config, or test runner behavior. Triggers on questions like "vi.fn", "vi.spyOn", "vi.mocked", "Mocked", "mockResolvedValue", "restoreMocks", "vitest mock", "createMockInstance", "useFakeTimers", or how to accomplish test double patterns with Vitest. allowed-tools: - Read - Bash - WebFetch - WebSearch

Vitest Documentation Lookup

Look up Vitest APIs, patterns, and best practices via WebFetch against the official docs. Use this skill to answer questions about vi.*, mock instances, assertions, fake timers, and config options. Project-specific test conventions (naming, stubbing strategy, node-deps.ts pattern) live in .claude/rules/unit-tests.md - reference that rule rather than re-deriving the conventions.

Sources

Base URL: https://vitest.dev

Topic	Path	Use for
Getting started	`/guide/`	General concepts, project setup, runner behavior
Mocking guide	`/guide/mocking`	Worked examples: modules, timers, dates, classes
Config reference	`/config/`	`vitest.config.ts` options (`restoreMocks`, `pool`, coverage)
`vi` API	`/api/vi`	Top-level helpers (`vi.fn`, `vi.spyOn`, `vi.mocked`, timers)
Mock instance API	`/api/mock`	Methods on a `Mock` (`.mockReturnValue`, `.mockImplementation`)
Assertions	`/api/expect`	`expect()` matchers, argument matchers
Fake timers	`/api/vi#vi-usefaketimers`	`vi.useFakeTimers`, `advanceTimersByTimeAsync`
CLI	`/guide/cli`	`vitest run`, flags, watch mode

Process

Determine the question type
- API reference (exact signature, options, return type) → /api/* pages
- Pattern guidance / worked examples → /guide/mocking or /guide/
- Config option behavior → /config/
- CLI flag / runner behavior → /guide/cli
Check project rules first - read .claude/rules/unit-tests.md before fetching. It already documents: restoreMocks: true behavior, the node-deps.ts namespace pattern, createMockInstance, constructor-stub gotchas, and the vi.mock anti-pattern. Don't re-explain these; cite the rule and only fetch docs for anything beyond it.
Fetch the relevant page with WebFetch:
```
WebFetch: https://vitest.dev/api/mock
Prompt: "Find the signature and options for [specific method, e.g. mockImplementationOnce]"
```
For cross-cutting questions (e.g. "how do I mock a class constructor"), fetch the guide page (/guide/mocking) alongside the API page.
Look at existing project tests for pattern examples before synthesizing your own:
```
Grep: "vi\.spyOn|createMockInstance|vi\.useFakeTimers" --glob "**/*.test.ts"
```
Good reference files: src/confluent/telemetry.test.ts (many spies), src/cli.test.ts (env-proxy spying), src/confluent/oauth/token-store.test.ts (async + timers).
Cross-reference version: this project is on Vitest v4. If a WebSearch result or older example uses vi.mock factories or pre-v1 APIs, verify against the v4 /api/* page before recommending.

Topic Selection Examples

User asks about…	Fetch
"how do I stub a class constructor?"	`/guide/mocking` + `/api/vi`
"what's the difference between `vi.fn` and `vi.spyOn`?"	`/api/vi`
"mock returns different value on second call"	`/api/mock` (`mockReturnValueOnce`)
"how do I advance fake timers in an async test?"	`/api/vi#vi-usefaketimers`
"what does `restoreMocks` do?"	`/config/` (search: restoreMocks)
"how to type a stubbed class instance?"	`unit-tests.md` (project helper) + `/api/vi` (`Mocked<T>`)
"argument matcher for partial object"	`/api/expect` (`expect.objectContaining`)
"why can't I spy on this ESM import?"	`unit-tests.md` §Design for Stubbing (no fetch needed)

Output Format

API Reference

## Vitest: [method/feature]

### Signature

[From /api/*]

### Example

[Adapted to project patterns where relevant]

### Project usage

[Reference to unit-tests.md section or a real `.test.ts` file if applicable]

Pattern Guidance

## Pattern: [description]

### From the docs

[Approach recommended by /guide/mocking or /api/*]

### In this project

[How existing tests implement it; cite file paths]

### Gotchas

[Edge cases - e.g. arrow-fn constructor, ESM live bindings, mock hoisting]

Anti-patterns (project-specific)

Don't use vi.mock: it hoists above imports, loses type safety, and splits the project's stubbing model. If a dependency can't be spied on, wrap it in a namespace object (see src/confluent/node-deps.ts). Full rationale in .claude/rules/unit-tests.md §Why vi.mock is not used in this project.
Don't add afterEach restore blocks: restoreMocks: true in vitest.config.ts handles it.
Don't use arrow functions for constructor mocks: arrows aren't constructable. Use a regular function with vi.spyOn(ns, "Ctor").mockImplementation(function () { return {...}; }).

Tips

Prefer /api/* pages for signature lookups, /guide/* for worked examples.
/api/vi covers top-level helpers (vi.fn, vi.spyOn, timers, module hooks); /api/mock covers methods on a Mock instance. Pick the right one based on whether the user is asking "how do I create this mock" vs. "how do I configure an existing mock".
v4 is current. Older blog posts and Stack Overflow answers often show pre-v1 or vi.mock-heavy patterns - verify against the current API page before recommending.
For anything that overlaps with .claude/rules/unit-tests.md, cite the rule instead of duplicating its tables in the response.