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 plus the suite for the module you changed. Confirm pass. Do not run the whole repo suite on every cycle — that belongs at the end of the task, scoped per verification-before-completion.

   Report every failure the run shows, including ones you did not cause. Scope bounds which command you run; it never bounds what you report. If the module suite goes red on a test your change did not touch, name that test in your report as a pre-existing failure. A red test you watched scroll past and did not mention is a report falsified by omission — and the next person to run the suite inherits it as your bug.

5. REFACTOR: Improve structure without changing behavior. Tests must stay green.

Repeat per behavior. Never skip VERIFY steps.

Test Infrastructure Check

Before writing the first test, verify the project has a test runner:

1. Check for test config: jest.config.*, vitest.config.*, pytest.ini, pyproject.toml [tool.pytest], go.mod, Cargo.toml, .rspec, phpunit.xml
2. Check for test script: npm test, yarn test, make test, or equivalent
3. If no test infrastructure exists:
   • Ask the user: "No test runner detected. Should I set up [recommended runner for this language/framework]?"
   • If yes: install and configure the minimal test runner. Write one smoke test to confirm it works.
   • If no: note that TDD requires a test runner and proceed only if the user provides an alternative.

Do not skip this step — a "failing test" that fails because the runner doesn't exist teaches nothing.

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

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.
• The suite covering the changed module passes (scope per verification-before-completion).
• Any failure in that run which this change did not cause is named explicitly in the report as pre-existing — never silently passed over.

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.