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

async-

setup-

mock-

perf-

snap-

env-

assert-

org-

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