Test driven dev

Test-Driven Development

Philosophy

Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.

A good test is integration-style: it exercises real code paths through public APIs and reads like a specification — "user can checkout with valid cart" names a capability. It survives refactors because it doesn't care about internal structure.

A bad test is coupled to implementation: it mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database directly instead of using the interface). The tell is a test that breaks when you rename an internal function while behavior is unchanged — it was testing structure.

See tests.md for examples, mocking.md for mocking guidelines, evals.md for grading model behavior, test-assets.md for generating multimodal fixtures, and mcp-testing.md for MCP server tests.

Anti-Pattern: Horizontal Slices

DO NOT write all tests first, then all implementation — RED as "write test1…test5", GREEN as "write impl1…impl5". Tests written in bulk test imagined behavior: they pin the shape of things (data structures, signatures) rather than user-facing behavior, so they pass when behavior breaks and fail when it's fine. You commit to test structure before you understand the implementation.

Correct approach: vertical slices via tracer bullets — test1→impl1, then test2→impl2, and so on. Each test responds to what the last cycle taught you. Because you just wrote the code, you know which behavior matters and how to verify it.

Workflow

1. Planning

Before writing any code:

• State the interface shape — what the public API will look like
• List the behaviors to test, prioritized (not implementation steps)
• Shape the interface for depth and testability — small interface, deep implementation, dependencies passed in (deep-modules.md)
• For each new public interface: design it twice — sketch one genuinely different shape (a few lines, no implementation) and say why the winner wins; first ideas are rarely best and the comparison costs one message
• Draft the interface comment before the implementation — the contract a caller must know (inputs, invariants, units, error modes); if it comes out long or hedged, fix the interface, not the wording
• Where the contract allows, define errors out of existence — pick semantics that make the special case a non-event (delete-absent is a no-op, out-of-range clamps) instead of adding an error path every caller must know
• If the slice touches web UI, the tracer-bullet test is a Playwright CUJ (real browser, real flow) — not a component unit test
• If the slice touches user-facing UI, invoke ui-taste before styling — it applies the visual rules and reads the locked style from the SPEC's Product surfaces section (the to-mockups picks /to-spec restated)
• If a test needs a multimodal fixture (image, audio, video, rich text), see test-assets.md — it generates the stand-in into test-assets/ and routes load-bearing / user-dependent checks to the human
• If the slice's acceptance criteria depend on model behavior (an LLM call, an agent loop), the red test is an eval case graded against a threshold — see evals.md; the deterministic seams around the model still get normal tests

State the plan inline (interface, top behaviors, what's out of scope) and proceed. Ask only if a scope question would change the slice — the upstream issue is the contract; don't relitigate it.

You can't test everything. Focus testing effort on critical paths and complex logic, not every possible edge case.

2. Tracer Bullet

Write ONE test that confirms ONE thing about the system:

RED:   Write test for first behavior → test fails
GREEN: Write minimal code to pass → test passes

This is your tracer bullet - proves the path works end-to-end.

3. Incremental Loop

For each remaining behavior:

RED:   Write next test → fails
GREEN: Minimal code to pass → passes

Rules:

• One test at a time
• Only enough code to pass current test
• Don't anticipate future tests
• Keep tests focused on observable behavior

4. Refactor

After all tests pass, look for refactor candidates:

• Extract duplication
• Deepen modules (move complexity behind simple interfaces)
• Apply SOLID principles where natural
• Consider what new code reveals about existing code
• Two hats: refactor steps land as refactor-only commits — no behavior change mixed in
• Comment pass: new public surface carries its interface comment; delete any comment that restates the code
• Run tests after each refactor step

Never refactor while RED. Get to GREEN first.

Bugs found along the way

You will notice things that are broken and not yours. What happens next depends only on where the bug is.

Where	What to do
Inside this slice	Fix it here, now, with a test. Don't file anything. Filing an issue for something already open in front of you turns five minutes of work into a backlog entry, a review, and a second context load
Outside this slice	Leave it. Report it in your final message — what you saw, where, and how you'd confirm it. Don't open an issue and don't fix it. Whoever is holding the whole backlog decides; from inside one slice you can't see whether the next slice already deletes that code
Breaks a shipped journey or loses data	Stop and ask the user, immediately. Don't hold it, don't file it, don't fix it unprompted

Working under /run-wave, the middle row's reports are collected and decided in the between-wave review — the one place a human sees the whole backlog at once. Working standalone, they go to the user in your summary. Either way the judgment happens with the whole picture in view, not from inside one slice.

Pre-existing dead code follows the same shape: mention it, don't delete it (AGENTS.md §3).

Checklist Per Cycle

[ ] Test describes behavior, not implementation
[ ] Test uses public interface only
[ ] Test would survive internal refactor
[ ] Test sets up state via the same call shape production uses (no shortcut helpers)
[ ] For regression tests: stash the fix and confirm the test fails with the actual production symptom
[ ] Every external dependency the code calls has at least one failure-mode test
[ ] Tests that hit paid / external services skip on environmental failure, fail only on code regression
[ ] Model behavior is graded by an evalset on a pinned model against a threshold — never a single-run assert
[ ] For UI behavior: the test drives the rendered page in Playwright, not a mocked component tree
[ ] Code is minimal for this test
[ ] No speculative features added
[ ] New public interface has an interface comment (contract, invariants, error modes — no internals)
[ ] Names reuse CONTEXT.md vocabulary and existing molds; no name promises what the code doesn't do
[ ] Refactor steps landed in refactor-only commits

See tests.md for production-path coverage, stash-and-fail, external-dependency failure modes, and environmental skip rules.