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 → passes

3. Incremental Loop

For each remaining behavior:

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

One 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.json for test script; 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