test-driven-development

Test-Driven Development

Write failing tests first. Then write minimal code to pass.

Iron Law

No production code before a failing test proves the behavior is missing.

If code was written first, delete it and restart from a test. No exceptions.

This is the hardest rule to follow and the most important. Every rationalization to skip it leads to untested behavior that breaks later.

Cycle

1. RED: Write one small failing test for one behavior.
2. VERIFY RED: Run the test. Confirm it fails for the expected reason (not a syntax error or import issue).
3. GREEN: Write the minimum production code to make the test pass. Nothing more.
4. VERIFY GREEN: Run the target test and relevant broader tests. Confirm pass.
5. REFACTOR: Improve structure without changing behavior. Tests must stay green.

Repeat per behavior. Never skip VERIFY steps.

Right vs Wrong

Wrong — code first:

1. Write the handler function
2. Write tests to verify it works
3. All tests pass on first run ← this means the tests prove nothing

Right — test first:

1. Write test: POST /users returns 201 with valid body
2. Run test → FAILS (handler doesn't exist yet) ← good
3. Write minimal handler to return 201
4. Run test → PASSES ← test proved the behavior was missing, now it works
5. Refactor handler if needed, tests stay green

Rationalization Table — Do Not Skip Tests

Temptation	Why it fails
"This is too simple to test"	Simple code has the longest lifespan. It will be changed by someone who doesn't know the intent.
"I'll write tests after"	After never comes. And tests written after pass immediately, proving nothing.
"I'm just refactoring, no new behavior"	If behavior doesn't change, existing tests must stay green. Run them.
"Tests slow me down"	Tests save you from debugging sessions that take 10x longer.
"The type system catches this"	Types catch shape errors, not logic errors. Test the logic.
"I need to see the shape of the code first"	Spike in a scratch file. Then delete it and TDD the real implementation.

Test Quality Rules

• One behavior per test.
• Clear behavior-oriented test names (e.g., test_expired_token_returns_401).
• Prefer real behavior checks over mock-only assertions.
• Cover edge and error paths for changed behavior.
• A test that has never been seen failing is not a test — it's a wish.

Anti-Patterns

• Writing tests after implementation.
• Adding multiple features before rerunning tests.
• Accepting passing tests that never failed first.
• Fixing bugs without a regression test.
• Testing mock behavior instead of real behavior.

Completion Checklist

• Every changed behavior has a test.
• Each new test was observed failing before implementation.
• Changed tests pass.
• Relevant suite passes.

Advanced Test Strategy

For complex, high-risk, or hard-to-test behavior, go beyond basic unit tests while still following RED-GREEN-REFACTOR:

• Integration tests: Test real interactions between components (database, API, filesystem). Prefer real dependencies over mocks.
• E2E tests: For user-facing flows, verify the full path from input to output.
• Property-based tests: When behavior has invariants (e.g., "sort output is always ordered"), generate random inputs to find edge cases.
• Performance tests: When latency or throughput matters, add benchmarks with clear thresholds.
• Flaky test diagnosis: If a test passes/fails inconsistently, treat it as a bug — find the race condition, timing dependency, or shared state causing it.
• Coverage strategy: Focus coverage on behavior boundaries and error paths, not line counts. 80% meaningful coverage beats 100% trivial coverage.

Choose appropriate frameworks and libraries for the current stack. Write tests that are fast, deterministic, and maintainable.

Related

• Use systematic-debugging to find root cause before writing the fix test.
• Use verification-before-completion before success claims.
• Read testing-anti-patterns.md when introducing heavy mocking.