README.md

GitHub

Vitest Best Practices Skill

A comprehensive testing best practices skill for Vitest, the next-generation testing framework powered by Vite.

Overview

This skill contains 44 rules across 8 categories, organized by impact level to help prioritize the most important patterns when writing and reviewing Vitest tests.

Categories

Category Impact Rules Description
Async Patterns CRITICAL 7 Prevent race conditions, false positives, and flaky async tests
Test Setup & Isolation CRITICAL 6 Ensure proper test isolation and cleanup
Mocking Patterns HIGH 7 Effective mocking strategies without over-mocking
Performance HIGH 6 Optimize test execution speed
Snapshot Testing MEDIUM 5 Maintainable snapshot practices
Environment MEDIUM 4 Proper environment configuration
Assertions LOW-MEDIUM 5 Effective assertion patterns
Test Organization LOW 4 File structure and naming conventions

File Structure

vitest/
├── SKILL.md              # Entry point with quick reference
├── AGENTS.md             # Compiled comprehensive guide
├── metadata.json         # Version and references
├── README.md             # This file
├── references/
│   ├── _sections.md      # Category definitions
│   ├── async-*.md        # Async pattern rules
│   ├── setup-*.md        # Setup and isolation rules
│   ├── mock-*.md         # Mocking pattern rules
│   ├── perf-*.md         # Performance rules
│   ├── snap-*.md         # Snapshot rules
│   ├── env-*.md          # Environment rules
│   ├── assert-*.md       # Assertion rules
│   └── org-*.md          # Organization rules
└── assets/templates/
    └── _template.md      # Rule template

Usage

For AI Agents

Reference SKILL.md for quick navigation or AGENTS.md for the complete compiled guide.

For Humans

Browse individual rule files in the references/ directory for detailed explanations and code examples.

Key Patterns

Critical: Async Testing

// Always await async assertions
await expect(asyncFn()).rejects.toThrow('Error')

// Use fake timers for time-dependent code
vi.useFakeTimers()
vi.advanceTimersByTime(1000)

// Use vi.waitFor instead of arbitrary timeouts
await vi.waitFor(() => expect(element).toBeVisible())

Critical: Test Isolation

// Clean up after each test
afterEach(() => {
  vi.restoreAllMocks()
  vi.useRealTimers()
})

// Avoid shared mutable state
let testData: User[]
beforeEach(() => {
  testData = [createTestUser()]  // Fresh for each test
})

High: Effective Mocking

// Prefer vi.spyOn for targeted mocking
vi.spyOn(api, 'fetchUser').mockResolvedValue(testUser)

// Use MSW for network mocking
const server = setupServer(
  http.get('/api/users', () => HttpResponse.json([testUser]))
)

High: Performance

// vitest.config.ts
export default defineConfig({
  test: {
    pool: 'threads',           // Faster than forks
    isolate: false,            // If tests are properly isolated
    environment: 'happy-dom',  // Faster than jsdom
  },
})

References