tdd

``` ████████╗██████╗ ██████╗ ╚══██╔══╝██╔══██╗██╔══██╗ ██║ ██║ ██║██║ ██║ ██║ ██║ ██║██║ ██║ ██║ ██████╔╝██████╔╝ ╚═╝ ╚═════╝ ╚═════╝ ``` # Test-Driven Development The discipline that makes every other quality claim trustworthy. Skipping it feels faster and is the most expensive habit in software. ## The Iron Law **No production code without a failing test first.** If *you* wrote production code this session before its test and it isn't committed yet: **delete it.** Not comment it out, not keep it as "reference," not glance at it while writing the test — delete it, then re-derive it test-first. This applies to **your own uncommitted work**, never the repo's existing code. To put *pre-existing, untested* code under test, do **not** delete it — first write a **characterization test** that pins its current observable behavior (even behavior you suspect is wrong), get it green, and only then change it. Why this is non-negotiable: tests written *after* code ask "what does this code do?" and tend to enshrine whatever you happened to write, bugs included. Tests written *first* ask "what *should* this do?" — the only question that catches the gap. **For a bug, the law is identical:** the first RED is a test that *reproduces the bug* and fails for the bug's reason; GREEN is the fix. No fix before that test exists (use `forge:debug` to find the cause if it isn't obvious). ## Watch it fail After writing the test, **run it and watch it fail** before implementing. If you didn't see RED, you don't know the test actually exercises the behavior — a test that passes against no implementation is testing nothing. Confirm it fails **on the assertion you intended**, with the expected-vs-actual you predicted — not on an import error, typo, or fixture/collection error. A test that fails for the wrong reason hasn't been watched fail. ## One slice at a time (no horizontal batching) One failing test → the minimum implementation to make it pass → repeat. Do **not** write all the tests and then all the code. Bulk-writing tests verifies *imagined* behavior and tends to test the *shape* of the code rather than what it does. Tracer bullets, not layers. ## Refactor only on green Never refactor while a test is RED — you won't know whether the refactor or the unfinished feature broke it. Get to GREEN, then improve with the safety net in place. During a refactor you may **not** change a test assertion or add new behavior; the tests stay green and unchanged. If a test has to change, you're not refactoring — go back to RED. ## Test behavior, not internals Assert observable, external behavior. Renaming a private function, splitting a class, or reorganizing internals should **not** break a test. If it does, that test was coupled to structure and was wrong. **Mock only at trust boundaries** — network, clock, filesystem, external services. Asserting that a mock *was called N times* is testing internals (forbidden) unless that call **is** the observable behavior. Prefer real collaborators over mocks for in-process code. ## Forbidden rationalizations (and the honest rebuttal) | You'll think… | The truth | |---|---| | "This is too simple to test." | Simple code breaks too, and the test is then trivial to write. Write it. | | "I'll add tests after." | Tests-after enshrine bugs (see Iron Law). After rarely comes. | | "I already manually verified it." | Manual checks don't run in CI and don't catch regressions tomorrow. | | "It's the spirit that matters, not the ritual." | The ritual *is* the spirit. The order (fail → pass) is what creates the guarantee. | ## Exit After a coherent chunk: `forge:review` (quality), then `forge:verify` (proof) before any "done." For bugs, start from `forge:debug` to get a reproducing test first.