testing

Testing

Load this skill when writing, debugging, or planning tests.

Vitest mock patterns

vi.mock and hoisting

• When using vi.mock(), extract each vi.fn() stub to a module-scope variable and reset it in beforeEach — vi.restoreAllMocks() only operates on vi.spyOn() spies, not on vi.fn() instances. Use .mockReset() when the stub has no default implementation. Use .mockClear() when the vi.mock() factory provides a default implementation that tests must preserve.
• When a vi.mock() factory references a module-scope vi.fn() stub, wrap the stub declaration in vi.hoisted() — Vitest hoists vi.mock() above normal declarations, so unhoisted variables are undefined when the factory runs.
• When mocking a class constructor with vi.mock(), use vi.fn() with no implementation — not vi.fn(() => ({})). Arrow-function implementations are not constructable; new MockClass() throws "is not a constructor".
• When mocking node:* built-in modules with vi.mock(), include a default key mirroring the named exports — omitting it causes "No default export defined on the mock" errors.
• A vi.mock("node:*") factory that returns an object literal replaces the module: every export it omits becomes undefined, so a later call to a sibling export (lstatSync, tmpdir) throws TypeError in unrelated tests in that file. To stub one export and keep the rest, spread await vi.importActual<typeof import("node:fs")>("node:fs") in the factory and override only the target.
• Import the module-under-test with a static top-level import, not a per-test await import(...) — Vitest hoists vi.mock()/vi.hoisted() above static imports, so the mock still applies. A per-test dynamic import of a module that transitively pulls heavy deps pays the transform/resolve cost inside each test's testTimeout window and can flake CI.

Typing mock functions

• When a vi.fn() factory returns an empty array or narrow literal, annotate its return type explicitly — vi.fn((): string[] => []), not vi.fn(() => []). Without the annotation TypeScript infers never[], and subsequent mockReturnValueOnce([...]) calls fail with “not assignable to never”. Use import type to pull domain types (e.g., AgentConfig, PreloadedSkill) for the annotation.
• When typing a mock field on an interface, use Mock<specific-signature> — e.g., Mock<() => void>, Mock<(arg: string) => Promise<void>>. Do not use ReturnType<typeof vi.fn> — in Vitest v4 it expands to Mock<Procedure | Constructable>, a union that TypeScript cannot call.