test-driven-development

Test-Driven Development

Overview

Define acceptance and a behavior check before implementation. For bug fixes, reproduce the failure where reproduction is needed for diagnosis or regression defense; a user-supplied failure report is ground truth for the symptom, and prior failure evidence remains valid for an unchanged state. Show the reproduction (or the valid prior evidence) passes after the fix. Existing contract tests, isolated smoke probes and actual rendered UI checks can provide appropriate evidence; a permanent test must defend a plausible failure. State explicitly when reproduction is unavailable rather than claiming an unrun one.

The TDD Cycle

    RED                GREEN              REFACTOR
 Write a test    Write minimal code    Clean up the
 that fails  ──→  to make it pass  ──→  implementation  ──→  (repeat)
      │                  │                    │
      ▼                  ▼                    ▼
   Test FAILS        Test PASSES        Tests still PASS

Step 1: RED — Write a Failing Test

For a bug or new missing behavior, observe the check fail for the intended reason before the fix — freshly, or by reusing prior failure evidence valid for the unchanged state. A passing check can establish existing behavior, but cannot establish that it reproduced the reported bug; a user-supplied failure report is ground truth for the symptom. Do not manufacture failures in unrelated behavior.

Step 2: GREEN — Make It Pass

Write the smallest correct implementation of the full request, not just the subset exercised by the current test. Don't over-engineer or drop acceptance criteria.

GREEN is Two Claims: Targeted and Suite

A green run of the check you wrote (targeted green) is not the same claim as the project's checks passing on your final state (suite green). Both are evidence, at different scopes:

• Targeted green (always): the behavior check for this task passes after the change.
• Suite green (scaled to risk, per OPS §3): applicable existing checks pass on the final state. Run the affected suite(s) — not only your file — when the change touches shared code, public contracts or an exposed failure, or when a named concern requests it; a self-contained change with a scoped probe may not need the full project suite. Reuse valid prior evidence instead of rerunning when state, command and environment are unchanged.
• Reporting failures: name every failure you observed, including preexisting ones you did not cause. A red check watched scrolling past and left unmentioned is a report falsified by omission. Distinguish "caused by this change" from "present before" when you know, and say when you don't.