1---
2name: tdd
3description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
4---
5 
6# Test-Driven Development
7 
8## Philosophy
9 
10**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
11 
12**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
13 
14**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
15 
16See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
17 
18## Anti-Pattern: Horizontal Slices
19 
20**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" - treating RED as "write all tests" and GREEN as "write all code."
21 
22This produces **crap tests**:
23 
24- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
25- You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior
26- Tests become insensitive to real changes - they pass when behavior breaks, fail when behavior is fine
27- You outrun your headlights, committing to test structure before understanding the implementation
28 
29**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it.
30 
31```
32WRONG (horizontal):
33  RED:   test1, test2, test3, test4, test5
34  GREEN: impl1, impl2, impl3, impl4, impl5
35 
36RIGHT (vertical):
37  RED→GREEN: test1→impl1
38  RED→GREEN: test2→impl2
39  RED→GREEN: test3→impl3
40  ...
41```
42 
43## Workflow
44 
45### 1. Planning
46 
47Before writing any code:
48 
49- [ ] Confirm with user what interface changes are needed
50- [ ] Confirm with user which behaviors to test (prioritize)
51- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
52- [ ] Design interfaces for [testability](interface-design.md)
53- [ ] List the behaviors to test (not implementation steps)
54- [ ] Get user approval on the plan
55 
56Ask: "What should the public interface look like? Which behaviors are most important to test?"
57 
58**You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case.
59 
60### 2. Tracer Bullet
61 
62Write ONE test that confirms ONE thing about the system:
63 
64```
65RED:   Write test for first behavior → test fails
66GREEN: Write minimal code to pass → test passes
67```
68 
69This is your tracer bullet - proves the path works end-to-end.
70 
71### 3. Incremental Loop
72 
73For each remaining behavior:
74 
75```
76RED:   Write next test → fails
77GREEN: Minimal code to pass → passes
78```
79 
80Rules:
81 
82- One test at a time
83- Only enough code to pass current test
84- Don't anticipate future tests
85- Keep tests focused on observable behavior
86 
87### 4. Refactor
88 
89After all tests pass, look for [refactor candidates](refactoring.md):
90 
91- [ ] Extract duplication
92- [ ] Deepen modules (move complexity behind simple interfaces)
93- [ ] Apply SOLID principles where natural
94- [ ] Consider what new code reveals about existing code
95- [ ] Run tests after each refactor step
96 
97**Never refactor while RED.** Get to GREEN first.
98 
99## Checklist Per Cycle
100 
101```
102[ ] Test describes behavior, not implementation
103[ ] Test uses public interface only
104[ ] Test would survive internal refactor
105[ ] Code is minimal for this test
106[ ] No speculative features added
107```
108