Test-Driven Development
Tests verify behavior through public interfaces, not implementation details. See principles.md for testing philosophy and mocking guidelines.
DO NOT write all tests first, then all implementation. Each cycle: one test → minimal code to pass → next test. See examples.md for demonstrations.
Workflow
1. Planning
- Ask user: "What should the public interface look like? Which behaviors are most important to test?"
- Identify opportunities for deep modules (small interface, deep implementation)
- Design interfaces for testability
- List behaviors to test (prioritize critical paths — you can't test everything)
- Get user approval before writing code
2. Tracer Bullet
RED: Write first test → fails
GREEN: Minimal code to pass → passes3. Incremental Loop
For each remaining behavior:
RED: Write next test → fails
GREEN: Minimal code to pass → passesOne test at a time. Minimal code to pass. No refactoring while RED.
Checklist (each cycle)
- Test describes behavior, not implementation
- Test uses public interface only
- Test would survive internal refactor
- Code is minimal for this test
- No speculative features added
4. Refactor
Once all tests GREEN, look for refactor candidates:
- Extract duplication
- Deepen modules (move complexity behind simple interfaces)
- Run tests after each refactor step
Never refactor while RED.
Anti-Rationalization
| Excuse | Rebuttal |
|---|---|
| "This is too small for TDD" | Small functions have edge cases too. A 1-min test prevents a 30-min debug. |
| "I'll write tests after" | That's not TDD. Tests written after miss the design feedback loop. |
| "The test is obvious, skip RED" | If it's obvious, writing it takes 10 seconds. Skip nothing. |
| "I need to refactor first" | Never refactor while RED. Get to GREEN, then refactor. |
| "Mocking is too complex here" | Complexity in mocking signals a design problem. Simplify the interface. |
| "I'll batch these 3 tests" | One test at a time. Batching hides which change broke what. |
Error Handling
- If test runner not found → check
package.jsonfortestscript; ask user which runner to use - If tests go RED after refactor → revert immediately and re-attempt in smaller steps
- If a test cannot be made GREEN with minimal code → revisit the interface design with the user