vitest

Vitest Best Practices

Vitest 5-compatible testing guide with 46 rules across 8 categories. Vitest 5 requires Node.js 22.12+ and Vite 6.4+; Vitest 4.1 remains on backport support.

When to Apply

Reference these guidelines when:

• Writing new Vitest tests
• Debugging flaky or slow tests
• Setting up test configuration
• Reviewing test code in PRs
• Migrating from Jest to Vitest
• Optimizing CI/CD test performance

Jest-specific APIs and configuration outside documented migration differences are out of scope; use Jest's own documentation for tests that still run under Jest.

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Async Patterns	CRITICAL	async-
2	Test Setup & Isolation	CRITICAL	setup-
3	Mocking Patterns	HIGH	mock-
4	Performance	HIGH	perf-
5	Snapshot Testing	MEDIUM	snap-
6	Environment	MEDIUM	env-
7	Assertions	LOW-MEDIUM	assert-
8	Test Organization	LOW	org-

Quick Reference

1. Async Patterns (CRITICAL)

• async-await-assertions - Await async assertions (Vitest 5 fails unawaited ones)
• async-return-promises - Return promises from test functions
• async-fake-timers - Use fake timers for time-dependent code
• async-waitfor-polling - Use vi.waitFor for async conditions
• async-concurrent-expect - Use test context expect in concurrent tests
• async-act-wrapper - Await user events to avoid act warnings
• async-error-handling - Test async error handling properly

2. Test Setup & Isolation (CRITICAL)

• setup-beforeeach-cleanup - Clean up state in afterEach hooks
• setup-restore-mocks - Restore mocks after each test
• setup-avoid-shared-state - Avoid shared mutable state between tests
• setup-beforeall-expensive - Use beforeAll for expensive one-time setup
• setup-reset-modules - Reset modules when testing module state
• setup-test-factories - Use test factories for complex test data
• setup-vitest5-migration - Plan the Vitest 5 migration deliberately (5.0)

3. Mocking Patterns (HIGH)

• mock-vi-mock-hoisting - Understand vi.mock hoisting behavior
• mock-spyon-vs-mock - Choose vi.spyOn vs vi.mock appropriately
• mock-implementation-not-value - Use mockImplementation for dynamic mocks
• mock-msw-network - Use MSW for network request mocking
• mock-avoid-overmocking - Avoid over-mocking
• mock-type-safety - Maintain type safety in mocks
• mock-clear-between-tests - Clear mock state between tests (default in Vitest 5)

4. Performance (HIGH)

• perf-pool-selection - Choose the right pool for performance
• perf-disable-isolation - Disable test isolation when safe
• perf-happy-dom - Use happy-dom over jsdom when possible
• perf-sharding - Use sharding for CI parallelization
• perf-run-mode-ci - Use run mode in CI environments
• perf-bail-fast-fail - Use bail for fast failure in CI
• perf-bench-test-context - Write Vitest 5 benchmarks with the bench fixture

5. Snapshot Testing (MEDIUM)

• snap-inline-over-file - Prefer inline snapshots for small values
• snap-avoid-large - Avoid large snapshots
• snap-stable-serialization - Ensure stable snapshot serialization
• snap-review-updates - Review snapshot updates before committing
• snap-describe-intent - Name snapshot tests descriptively

6. Environment (MEDIUM)

• env-per-file-override - Override environment per file when needed
• env-setup-files - Use setup files for global configuration
• env-globals-config - Configure globals consistently
• env-browser-api-mocking - Mock browser APIs not available in test environment

7. Assertions (LOW-MEDIUM)

• assert-specific-matchers - Use specific matchers over generic ones
• assert-edge-cases - Test edge cases and boundaries
• assert-one-assertion-concept - Test one concept per test
• assert-expect-assertions - Use expect.assertions for async tests
• assert-toequal-vs-tobe - Choose toBe vs toEqual correctly

8. Test Organization (LOW)

• org-file-colocation - Colocate test files with source files
• org-describe-nesting - Use describe blocks for logical grouping
• org-test-naming - Write descriptive test names
• org-test-skip-only - Use skip and only appropriately

How to Use

Run in the project root first:

npx -y @pymodel/react-frontend-skills detect               # installed vs. targeted versions
npx -y @pymodel/react-frontend-skills scan --skill vitest  # deprecated APIs → rule IDs

Read references/<rule-id>.md for each rule above that matches the task and for each scan hit: why it matters, then incorrect vs. correct code.

Related Skills

• For TDD methodology, see tdd skill
• For API mocking with MSW, see msw skill
• For TypeScript testing patterns, see typescript skill