Vitest Best Practices

Comprehensive performance optimization and best practices guide for Vitest testing framework. Contains 44 rules across 8 categories, prioritized by impact to guide test writing, refactoring, and code review.

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

Rule Categories by Priority

Quick Reference

1. Async Patterns (CRITICAL)

• async-await-assertions – Await async assertions to prevent false positives
• 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

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

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

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

Read individual reference files for detailed explanations and code examples:

• Section definitions – Category structure and impact levels
• Rule template – Template for adding new rules
• async-await-assertions – Example rule file
• mock-vi-mock-hoisting – Example rule file

Related Skills

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

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md