Vitest

---
name: vitest
description: Vitest 5 unit tests and mocking.
---

# 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:

```bash
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