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: 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<T>", "mockResolvedValue", "restoreMocks", "vitest mock", "createMockInstance", "useFakeTimers", or how to accomplish test double patterns with Vitest.4---56# Vitest Documentation Lookup78Look up Vitest APIs, patterns, and best practices via WebFetch against the official docs. Use this9skill to answer questions about `vi.*`, mock instances, assertions, fake timers, and config10options. Project-specific test conventions (naming, stubbing strategy, `node-deps.ts` pattern) live11in `.claude/rules/unit-tests.md` - reference that rule rather than re-deriving the conventions.1213## Sources1415Base URL: `https://vitest.dev`1617| Topic | Path | Use for |18| ----------------- | -------------------------- | --------------------------------------------------------------- |19| Getting started | `/guide/` | General concepts, project setup, runner behavior |20| Mocking guide | `/guide/mocking` | Worked examples: modules, timers, dates, classes |21| Config reference | `/config/` | `vitest.config.ts` options (`restoreMocks`, `pool`, coverage) |22| `vi` API | `/api/vi` | Top-level helpers (`vi.fn`, `vi.spyOn`, `vi.mocked`, timers) |23| Mock instance API | `/api/mock` | Methods on a `Mock` (`.mockReturnValue`, `.mockImplementation`) |24| Assertions | `/api/expect` | `expect()` matchers, argument matchers |25| Fake timers | `/api/vi#vi-usefaketimers` | `vi.useFakeTimers`, `advanceTimersByTimeAsync` |26| CLI | `/guide/cli` | `vitest run`, flags, watch mode |2728## Process29301. **Determine the question type**31 - API reference (exact signature, options, return type) → `/api/*` pages32 - Pattern guidance / worked examples → `/guide/mocking` or `/guide/`33 - Config option behavior → `/config/`34 - CLI flag / runner behavior → `/guide/cli`35362. **Check project rules first** - read `.claude/rules/unit-tests.md` before fetching. It already37 documents: `restoreMocks: true` behavior, the `node-deps.ts` namespace pattern,38 `createMockInstance`, constructor-stub gotchas, and the `vi.mock` anti-pattern. Don't re-explain39 these; cite the rule and only fetch docs for anything beyond it.40413. **Fetch the relevant page** with WebFetch:4243 ```44 WebFetch: https://vitest.dev/api/mock45 Prompt: "Find the signature and options for [specific method, e.g. mockImplementationOnce]"46 ```4748 For cross-cutting questions (e.g. "how do I mock a class constructor"), fetch the guide page49 (`/guide/mocking`) alongside the API page.50514. **Look at existing project tests** for pattern examples before synthesizing your own:5253 ```54 Grep: "vi\.spyOn|createMockInstance|vi\.useFakeTimers" --glob "**/*.test.ts"55 ```5657 Good reference files: `src/confluent/telemetry.test.ts` (many spies), `src/cli.test.ts`58 (env-proxy spying), `src/confluent/oauth/token-store.test.ts` (async + timers).59605. **Cross-reference version**: this project is on Vitest v4. If a WebSearch result or older61 example uses `vi.mock` factories or pre-v1 APIs, verify against the v4 `/api/*` page before62 recommending.6364## Topic Selection Examples6566| User asks about… | Fetch |67| ------------------------------------------------------- | ---------------------------------------------------------- |68| "how do I stub a class constructor?" | `/guide/mocking` + `/api/vi` |69| "what's the difference between `vi.fn` and `vi.spyOn`?" | `/api/vi` |70| "mock returns different value on second call" | `/api/mock` (`mockReturnValueOnce`) |71| "how do I advance fake timers in an async test?" | `/api/vi#vi-usefaketimers` |72| "what does `restoreMocks` do?" | `/config/` (search: restoreMocks) |73| "how to type a stubbed class instance?" | `unit-tests.md` (project helper) + `/api/vi` (`Mocked<T>`) |74| "argument matcher for partial object" | `/api/expect` (`expect.objectContaining`) |75| "why can't I spy on this ESM import?" | `unit-tests.md` §Design for Stubbing (no fetch needed) |7677## Output Format7879### API Reference8081```markdown82## Vitest: [method/feature]8384### Signature8586[From /api/*]8788### Example8990[Adapted to project patterns where relevant]9192### Project usage9394[Reference to unit-tests.md section or a real `.test.ts` file if applicable]95```9697### Pattern Guidance9899```markdown100## Pattern: [description]101102### From the docs103104[Approach recommended by /guide/mocking or /api/*]105106### In this project107108[How existing tests implement it; cite file paths]109110### Gotchas111112[Edge cases - e.g. arrow-fn constructor, ESM live bindings, mock hoisting]113```114115## Anti-patterns (project-specific)116117- **Don't use `vi.mock`**: it hoists above imports, loses type safety, and splits the project's118 stubbing model. If a dependency can't be spied on, wrap it in a namespace object (see119 `src/confluent/node-deps.ts`). Full rationale in `.claude/rules/unit-tests.md` §Why `vi.mock`120 is not used in this project.121- **Don't add `afterEach` restore blocks**: `restoreMocks: true` in `vitest.config.ts` handles it.122- **Don't use arrow functions for constructor mocks**: arrows aren't constructable. Use a regular123 `function` with `vi.spyOn(ns, "Ctor").mockImplementation(function () { return {...}; })`.124125## Tips126127- Prefer `/api/*` pages for signature lookups, `/guide/*` for worked examples.128- `/api/vi` covers top-level helpers (`vi.fn`, `vi.spyOn`, timers, module hooks); `/api/mock`129 covers methods _on_ a `Mock` instance. Pick the right one based on whether the user is asking130 "how do I create this mock" vs. "how do I configure an existing mock".131- v4 is current. Older blog posts and Stack Overflow answers often show pre-v1 or `vi.mock`-heavy132 patterns - verify against the current API page before recommending.133- For anything that overlaps with `.claude/rules/unit-tests.md`, cite the rule instead of134 duplicating its tables in the response.
confluentinc