Vitest Standard

This skill provides opinionated, production-tested guidance for high-integrity unit testing with Vitest. It emphasizes behavior-driven design, strictly isolated tests, and the TDD lifecycle.

Golden Rules (Mandatory)

1. Test Behavior, Not Implementation — Assert what the code _does_, not how it _looks_ internally.
2. Strict Isolation — NO shared state between tests. Create new instances in beforeEach.
3. Clean Mocks — Use vi.clearAllMocks() in beforeEach to prevent call history leaks.
4. No Magic Numbers — Use descriptive variables for expected values.
5. AAA Pattern — Every test must follow Arrange-Act-Assert.
6. Async/Await — Always await promises; use rejects.toThrow() for error paths.
7. Deterministic Tests — No dependence on system time, environment variables, or randomness (mock them).
8. Meaningful Names — Use it('should [action] when [condition]') or Given-When-Then.
9. Mock at Boundaries — Mock external APIs, databases, and third-party SDKs; test your own logic.
10. Red-Green-Refactor — Prefer writing tests before code to drive API design.
11. Security — Use fake/mock credentials in all tests — never real API keys, tokens, or passwords. Load sensitive test config from .env.test.local (gitignored).

Core Patterns

AAA (Arrange-Act-Assert)

it('should calculate total price', () => {
  // Arrange: Setup data and environment
  const cart = new ShoppingCart()
  cart.addItem({ price: 10, quantity: 2 })

  // Act: Execute the method being tested
  const total = cart.getTotal()

  // Assert: Verify the outcome
  expect(total).toBe(20)
})

Mocking Example

import { vi, it, expect } from 'vitest'

it('mocks dependencies', () => {
  const mockFn = vi.fn().mockReturnValue(42)
  expect(mockFn()).toBe(42)
  expect(mockFn).toHaveBeenCalledOnce()
})

Quick Reference: Assertions

See [assertions.md](references/assertions.md) for a full list of Vitest assertions (toBe, toEqual, toThrow, etc.). This reference is auto-loaded only when writing test assertions.

Specialized References (Load On-Demand)

Example: TDD Calculator

See tdd-calculator.ts for the Red-Green-Refactor workflow.