test-mocking

Guides Vitest module mocking with vi.fn, vi.mocked, and per-test reset strategies.

Updated Jan 12, 2026
One-click install
npx skills add https://github.com/brandonarbini/arbini.family --skill test-mocking-brandonarbini
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: test-mocking
Source: https://github.com/brandonarbini/arbini.family/tree/main/.agents/skills/test-mocking
Command: npx skills add https://github.com/brandonarbini/arbini.family --skill test-mocking-brandonarbini

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Vitest tests often suffer from mock state leaking between tests, temporal-dead-zone errors from hoisted vi.mock factories, and hand-rolled call tracking that duplicates what vi.fn() already provides. This Skill defines a consistent mocking style so tests stay isolated, readable, and free of order-dependent failures. ## Core Features & Use Cases - Preferred mocking pattern: Mock modules with vi.fn() per exported function, configure behavior per test with vi.mocked(), and assert calls with toHaveBeenCalledWith instead of hand-rolled state boxes. - vi.hoisted guidance: Explains that vi.hoisted exists only to work around hoisting-order errors, not as a mutable shared state container that couples tests together. - Setup vs per-file mocks: Clarifies what belongs in vitest.setup.ts (framework-wide neutralizations like server-only guards) versus file-specific vi.mock calls. - Reset strategy: Distinguishes vi.clearAllMocks (clears call history, keeps implementations) from vi.resetAllMocks (also clears implementations), run in beforeEach. - Use Case: When reviewing a diff that adds a const { state } = vi.hoisted(...) box mutated by every test, use this Skill to refactor it into per-test vi.mocked() configuration with proper beforeEach resets. ## Quick Start Review my Vitest test file and refactor the vi.hoisted state box into vi.fn and vi.mocked mocks with proper per-test resets.

Frequently Asked Questions about test-mocking

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I mock a module in Vitest with vi.mock?▼

Call vi.mock with the module path and a factory returning vi.fn() for each exported function, then import the module normally. Configure behavior per test with vi.mocked(fn).mockResolvedValue(...) and assert calls with toHaveBeenCalledWith.

What is vi.hoisted used for in Vitest?▼

vi.hoisted lifts a value above hoisted vi.mock factories to avoid temporal-dead-zone errors like cannot access X before initialization. It is a workaround for module load order, not a place to store mutable test state shared across tests.

What is the difference between vi.clearAllMocks and vi.resetAllMocks?▼

vi.clearAllMocks wipes call history but keeps configured implementations, suiting tests that share one mockResolvedValue from beforeEach. vi.resetAllMocks also clears implementations, returning every vi.fn() to undefined, which suits tests that configure behavior individually.

Why does my Vitest mock leak state between tests?▼

Leaks happen when tests share a mutable object, such as a vi.hoisted state box, or when mocks are never reset. Run vi.clearAllMocks or vi.resetAllMocks in beforeEach so no test inherits a previous test's call history or implementations.

Should I mock the database or ORM in Vitest tests?▼

No. Mocking the ORM produces tests that pass against queries that do not actually work. Use a per-worker truncated test database instead, as described by the db-test-isolation approach, and reserve module mocking for non-database dependencies.