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.
1---2name: vitest3description:4 Use when the user asks about Vitest mocking, spies, stubs, fake timers, config, or test runner5 behavior. Triggers on questions like "vi.fn", "vi.spyOn", "vi.mocked", "Mocked<T>",6 "mockResolvedValue", "restoreMocks", "vitest mock", "createMockInstance", "useFakeTimers", or7 how to accomplish test double patterns with Vitest.8allowed-tools:9 - Read10 - Bash11 - WebFetch12 - WebSearch13metadata:14 source: https://skillmd.com/skills/confluentinc/vitest15---1617# Vitest Documentation Lookup1819Look up Vitest APIs, patterns, and best practices via WebFetch against the official docs. Use this20skill to answer questions about `vi.*`, mock instances, assertions, fake timers, and config21options. Project-specific test conventions (naming, stubbing strategy, `node-deps.ts` pattern) live22in `.claude/rules/unit-tests.md` - reference that rule rather than re-deriving the conventions.2324## Sources2526Base URL: `https://vitest.dev`2728| Topic | Path | Use for |29| ----------------- | -------------------------- | --------------------------------------------------------------- |30| Getting started | `/guide/` | General concepts, project setup, runner behavior |31| Mocking guide | `/guide/mocking` | Worked examples: modules, timers, dates, classes |32| Config reference | `/config/` | `vitest.config.ts` options (`restoreMocks`, `pool`, coverage) |33| `vi` API | `/api/vi` | Top-level helpers (`vi.fn`, `vi.spyOn`, `vi.mocked`, timers) |34| Mock instance API | `/api/mock` | Methods on a `Mock` (`.mockReturnValue`, `.mockImplementation`) |35| Assertions | `/api/expect` | `expect()` matchers, argument matchers |36| Fake timers | `/api/vi#vi-usefaketimers` | `vi.useFakeTimers`, `advanceTimersByTimeAsync` |37| CLI | `/guide/cli` | `vitest run`, flags, watch mode |3839## Process40411. **Determine the question type**42 - API reference (exact signature, options, return type) → `/api/*` pages43 - Pattern guidance / worked examples → `/guide/mocking` or `/guide/`44 - Config option behavior → `/config/`45 - CLI flag / runner behavior → `/guide/cli`46472. **Check project rules first** - read `.claude/rules/unit-tests.md` before fetching. It already48 documents: `restoreMocks: true` behavior, the `node-deps.ts` namespace pattern,49 `createMockInstance`, constructor-stub gotchas, and the `vi.mock` anti-pattern. Don't re-explain50 these; cite the rule and only fetch docs for anything beyond it.51523. **Fetch the relevant page** with WebFetch:5354 ```55 WebFetch: https://vitest.dev/api/mock56 Prompt: "Find the signature and options for [specific method, e.g. mockImplementationOnce]"57 ```5859 For cross-cutting questions (e.g. "how do I mock a class constructor"), fetch the guide page60 (`/guide/mocking`) alongside the API page.61624. **Look at existing project tests** for pattern examples before synthesizing your own:6364 ```65 Grep: "vi\.spyOn|createMockInstance|vi\.useFakeTimers" --glob "**/*.test.ts"66 ```6768 Good reference files: `src/confluent/telemetry.test.ts` (many spies), `src/cli.test.ts`69 (env-proxy spying), `src/confluent/oauth/token-store.test.ts` (async + timers).70715. **Cross-reference version**: this project is on Vitest v4. If a WebSearch result or older72 example uses `vi.mock` factories or pre-v1 APIs, verify against the v4 `/api/*` page before73 recommending.7475## Topic Selection Examples7677| User asks about… | Fetch |78| ------------------------------------------------------- | ---------------------------------------------------------- |79| "how do I stub a class constructor?" | `/guide/mocking` + `/api/vi` |80| "what's the difference between `vi.fn` and `vi.spyOn`?" | `/api/vi` |81| "mock returns different value on second call" | `/api/mock` (`mockReturnValueOnce`) |82| "how do I advance fake timers in an async test?" | `/api/vi#vi-usefaketimers` |83| "what does `restoreMocks` do?" | `/config/` (search: restoreMocks) |84| "how to type a stubbed class instance?" | `unit-tests.md` (project helper) + `/api/vi` (`Mocked<T>`) |85| "argument matcher for partial object" | `/api/expect` (`expect.objectContaining`) |86| "why can't I spy on this ESM import?" | `unit-tests.md` §Design for Stubbing (no fetch needed) |8788## Output Format8990### API Reference9192```markdown93## Vitest: [method/feature]9495### Signature9697[From /api/*]9899### Example100101[Adapted to project patterns where relevant]102103### Project usage104105[Reference to unit-tests.md section or a real `.test.ts` file if applicable]106```107108### Pattern Guidance109110```markdown111## Pattern: [description]112113### From the docs114115[Approach recommended by /guide/mocking or /api/*]116117### In this project118119[How existing tests implement it; cite file paths]120121### Gotchas122123[Edge cases - e.g. arrow-fn constructor, ESM live bindings, mock hoisting]124```125126## Anti-patterns (project-specific)127128- **Don't use `vi.mock`**: it hoists above imports, loses type safety, and splits the project's129 stubbing model. If a dependency can't be spied on, wrap it in a namespace object (see130 `src/confluent/node-deps.ts`). Full rationale in `.claude/rules/unit-tests.md` §Why `vi.mock`131 is not used in this project.132- **Don't add `afterEach` restore blocks**: `restoreMocks: true` in `vitest.config.ts` handles it.133- **Don't use arrow functions for constructor mocks**: arrows aren't constructable. Use a regular134 `function` with `vi.spyOn(ns, "Ctor").mockImplementation(function () { return {...}; })`.135136## Tips137138- Prefer `/api/*` pages for signature lookups, `/guide/*` for worked examples.139- `/api/vi` covers top-level helpers (`vi.fn`, `vi.spyOn`, timers, module hooks); `/api/mock`140 covers methods _on_ a `Mock` instance. Pick the right one based on whether the user is asking141 "how do I create this mock" vs. "how do I configure an existing mock".142- v4 is current. Older blog posts and Stack Overflow answers often show pre-v1 or `vi.mock`-heavy143 patterns - verify against the current API page before recommending.144- For anything that overlaps with `.claude/rules/unit-tests.md`, cite the rule instead of145 duplicating its tables in the response.