vitest-unit

When to trigger

• Authoring a unit test for a function, React component, hook, or async handler.
• Coverage-gate work: ensuring the target package meets its coverage threshold.
• Snapshot review: deciding whether to update or reject a snapshot diff.
• Async-pattern test work: testing promises, async/await, timeouts, or event-driven code.
• Mock-strategy decisions: which layer to mock (module boundary vs. network boundary).

Procedure

1. Place test file colocated with implementation: <file>.test.ts (non-React) or <file>.test.tsx (React components) in the same directory as the source file. This makes it obvious when a test is missing and prevents "lost test" drift.

2. Test pyramid discipline: write many unit tests, fewer integration tests, fewest e2e tests. A unit test covers one function or component in isolation. If a test requires multiple real modules to be wired together, consider whether it should be an integration test.

3. Coverage threshold for the target package is {{ profile.test_recipe.coverage_gate }}. Do not invent a threshold; use the profile's gate. Verify with the project's coverage run that the PR does not lower the threshold below the defined minimum.

4. Snapshots only for stable serialization (config objects, API response shapes, serialized schemas). Never snapshot rendered React DOM — rendered output is brittle (class names, whitespace, auto-generated IDs change between builds). Replace DOM snapshots with role/testid assertions.

5. Async patterns: always await returned promises. Never use the done callback pattern (deprecated idiom; async/await is the supported form in Vitest). For timer-based code, use vi.useFakeTimers() + vi.runAllTimers().

6. Mocks via vi.mock at the module boundary: vi.mock('../path/to/module') hoists the mock above imports. Scope mocks to the test file — never use globalThis or vi.doMock for cross-file state. Reset mocks between tests with vi.clearAllMocks() in afterEach.