react-tdd

# React Test-Driven Development (TDD)

## Overview

Write the test first. Watch it fail. Write minimal code to pass.

**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.

**Violating the letter of the rules is violating the spirit of the rules.**

## Quick Reference

| Step | Action | Verify |
|------|--------|--------|
| RED | Write one failing test | Fails for expected reason (missing component/function, not typo) |
| GREEN | Write minimal code to pass | This test + all others pass |
| REFACTOR | Clean up, no new behavior | All tests still green |
| Commit | After each green cycle | `git commit` with passing tests |
| Mock rule | Mock API boundaries only (MSW) | Zustand stores, domain logic, React components are real |
| Naming | `it('should [behavior] when [condition]')` | Behavioral, no `CanSet*` |
| Assertions | Max 3 per test | Use `it.each`/`describe.each` for parameterized cases |

## When to Use

**Always:** New features, bug fixes, refactoring, behavior changes.

**Exceptions (ask your human partner):** Throwaway prototypes, generated code, configuration files.

Thinking "skip TDD just this once"? Stop. That's rationalization.

## The Iron Laws

```
1. NO IMPLEMENTATION CODE WITHOUT A FAILING TEST FIRST
2. NEVER add test-only methods/props to production components
3. MOCK BOUNDARY RULE (see below)
4. COMMIT after each green cycle
```

Write code before the test? Delete it. Start over.

**No exceptions:**
- Don't keep it as "reference"
- Don't `git stash` it "for domain knowledge"
- Don't "adapt" it while writing tests
- Don't look at it
- Delete means delete — `git checkout .` or `rm`, not stash

### Mock Boundary Rule

**Mock API boundaries with MSW. NEVER mock domain logic or React internals.**

**OK to mock (MSW):** HTTP endpoints (`http.get`, `http.post`), WebSocket connections, external service APIs.

**OK to mock (vi.mock):** `window.location`, `navigator.*`, timers (`vi.useFakeTimers`), `IntersectionObs