test-driven-development

Test-Driven Development

Prove a change with an honest red-green-refactor cycle: a failing test that detects the missing or broken behavior, then the smallest trustworthy change; quality-assurance owns the broader campaign and systematic-debugging owns failures not yet understood.

Workflow

1. Discover the harness: Read repository instructions, existing tests, task definitions, and nearby patterns; find the smallest command that exercises the target behavior.
2. State the contract: Name the production change that would make the test pass and a plausible regression that would make it fail.
3. RED: Write one minimal test for one observable behavior; run it and confirm it fails for the missing behavior, not for a syntax, fixture, environment, or setup error.
4. GREEN: Implement only enough production code to satisfy that test; run the focused test and read the full output.
5. Protect the neighborhood: Run the package or subsystem tests; fix production code when the new behavior breaks a valid existing contract and revisit the spec when contracts conflict.
6. REFACTOR: Improve names, structure, duplication, and types only while everything stays green; add no behavior.
7. Repeat: Take the next smallest behavior, edge case, or failure path through a new red cycle.
8. Prove the regression test: For a bug fix, temporarily reverse the fix when safe, confirm the test fails, then restore it and confirm green.
9. Gate the candidate: Run the full gate (mise run all); if the tree carries unrelated changes and the gate write-formats, run it in a temporary git worktree or fall back to mise run check and mise run test (see mise).
10. Report evidence: Give the red command and expected failure, the focused green command, the wider suite, the full gate, and any boundary still covered only manually or not at all.

Gotchas

• Never weaken an existing test: do not loosen a type, add a skip, or mock away the defect to manufacture green.
• Implementation came first: Never delete or overwrite user work because it preceded the test; preserve it, add a red-capable test, and disclose the sequence.
• Test-first does not fit: For a spike, generated code, or configuration-only change, say why and define another failing validation signal; do not call tests written afterward TDD.
• Test level: Fast unit or contract tests first; integration, property, concurrency, or browser tests only where the boundary demands them; characterize legacy behavior before changing it.
• Real collaborators: Prefer real parsers, databases, filesystems, and HTTP handlers at lightweight boundaries over mocks of the unit under test; fake only paid, destructive, slow, or unreliable systems behind a narrow owned interface.
• Readable failures: Keep fixtures readable and assertions on outcomes; a little duplicated setup beats hidden intent, and a failure should explain the broken contract without a debugger.