---
name: vitest-standard
description: |
  Comprehensive unit testing expertise covering Vitest, test-driven 
  development (TDD), mocking strategies, and production-grade best practices. 
  Activates ONLY for unit testing scope (unit tests, integration tests, Vitest, TDD, Red-Green-Refactor, mocking, 
  stubbing, spying, test coverage, and test architecture in TypeScript/Node projects). NOT for E2E testing (use Playwright).
  If the user asks to "write tests" without specifying the type, you MUST ask "Unit, E2E, or both?" before proceeding.
---

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

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

```typescript
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)

| Scenario                     | Reference File                                              |
| :--------------------------- | :---------------------------------------------------------- |
| **Mocking & Doubles**        | [mocking.md](references/mocking.md)                         |
| **Async & Error Handling**   | [async-and-errors.md](references/async-and-errors.md)       |
| **Coverage & Configuration** | [coverage-and-config.md](references/coverage-and-config.md) |
| **TDD Cycle**                | [tdd-patterns.md](references/tdd-patterns.md)               |

## Example: TDD Calculator

See [tdd-calculator.ts](examples/tdd-calculator.ts) for the Red-Green-Refactor workflow.
