vitest-v4

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

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