vitest-best-practices

name	vitest-best-practices
description	Comprehensive vitest testing patterns covering test structure, AAA pattern, parameterized tests, assertions, mocking, test doubles, error handling, async testing, and performance optimization. Use when writing, reviewing, or refactoring vitest tests, or when user mentions vitest, testing, TDD, test coverage, mocking, assertions, or test files (*.test.ts, *.spec.ts).
compatibility	Requires vitest testing framework

Vitest Best Practices

When to Apply This Skill

Use this skill when you encounter any of these scenarios:

File Patterns

• Working with *.test.ts, *.spec.ts, or similar test files
• Creating new test files for TypeScript/JavaScript modules
• Reviewing existing vitest test suites

User Intent Keywords

• User mentions: vitest, testing, TDD, BDD, unit tests, integration tests
• User asks to: write tests, add test coverage, fix failing tests, refactor tests
• User discusses: mocking, stubbing, assertions, test performance, test organization

Code Context

• Files importing from vitest (describe, it, expect, vi)
• Test setup/teardown code (beforeEach, afterEach, beforeAll, afterAll)
• Mock/spy implementations using vi.mock(), vi.spyOn(), vi.fn()
• Assertion chains (expect(...).toEqual(), .toBe(), .toThrow(), etc.)

Common Tasks

• Writing new test cases for existing functionality
• Refactoring tests for better clarity or performance
• Debugging flaky or failing tests
• Improving test coverage or maintainability
• Reviewing test code for best practices compliance

Do NOT Use This Skill When

• Writing end-to-end tests with Playwright/Cypress (different scope)
• The task is purely about implementation code, not tests

What This Skill Covers

This skill provides comprehensive guidance on:

1. Test Organization: File placement, naming conventions, grouping strategies
2. AAA Pattern: Arrange, Act, Assert structure for clarity
3. Parameterized Tests: Using it.each() for testing variations
4. Error Handling: Testing exceptions, edge cases, and fault injection
5. Assertions: Choosing strict assertions (toEqual, toStrictEqual, toThrow)
6. Test Doubles: Fakes, stubs, mocks, spies - when to use each
7. Async Testing: Promises, async/await, timers, and concurrent tests
8. Performance: Fast tests, avoiding expensive operations, cleanup patterns
9. Vitest-Specific Features: Coverage, watch mode, benchmarking, type testing, setup files
10. Snapshot Testing: When and how to use snapshots effectively

How to Use

This skill uses a progressive disclosure structure to minimize context usage:

1. Start with the Overview (AGENTS.md)

Read AGENTS.md for a concise overview of all rules with one-line summaries.

2. Load Specific Rules as Needed

When you identify a relevant optimization, load the corresponding reference file for detailed implementation guidance:

Core Patterns:

• organization.md
• aaa-pattern.md
• parameterized-tests.md
• error-handling.md
• assertions.md
• test-doubles.md

Advanced Topics:

• async-testing.md
• performance.md
• vitest-features.md
• snapshot-testing.md

3. Apply the Pattern

Each reference file contains:

• ❌ Incorrect examples showing the anti-pattern
• ✅ Correct examples showing the optimal implementation
• Explanations of why the pattern matters

Quick Example

This skill helps you transform unclear tests into clear, maintainable ones:

Before (unclear):

test('product test', () => {
  const p = new ProductService().add({name: 'Widget'});
  expect(p.status).toBe('pendingApproval');
});

After (optimized with this skill):

describe('ProductService', () => {
  describe('Add new product', () => {
    it('should have status "pending approval" when no price is specified', () => {
      // Arrange
      const productService = new ProductService();

      // Act
      const newProduct = productService.add({name: 'Widget'});

      // Assert
      expect(newProduct.status).toEqual('pendingApproval');
    });
  });
});

Key Principles

• Clarity over cleverness: Tests should be instantly understandable
• Flat structure: Avoid deep nesting in describe blocks
• One assertion per concept: Focus tests on single behaviors
• Strict assertions: Prefer toEqual over toBe, toStrictEqual when needed
• Minimal mocking: Use real implementations when practical
• Fast execution: Keep tests quick through efficient setup/teardown