# Test-first — Claude Code rules

## Philosophy

- Write the test before the change when fixing a regression. Reproduce the bug, watch it fail, then make it pass.
- For new features, write the smallest end-to-end test that demonstrates the feature works. Iterate inward from there.

## Layering

- **Unit** tests cover pure functions / single classes. No I/O, no clock, no network. Fast (<10ms).
- **Integration** tests cover the seam between code we own and code we don't (DB, queue, HTTP).
- **End-to-end** tests cover real user flows. Few of them, but they run against the real stack.

## Test names

- Describe behaviour, not implementation. `it("rejects expired tokens")` ✅ not `it("calls verifyJwt")` ❌.
- One assertion per behaviour. Multiple assertions are OK only when they describe the **same** behaviour.

## What not to mock

- Don't mock code we own. If a function is hard to test without mocking, restructure it.
- Don't mock the database for integration tests — use a real test database (docker compose, transactional rollback per test).

## Snapshots

- Snapshots are for stable, semantic outputs (rendered components, SQL). Don't snapshot deep JSON with timestamps / IDs.
- Review snapshot diffs in PR — never blindly accept.

## Coverage

- Coverage is a smell detector, not a goal. 100% coverage with bad assertions ships bugs.