TDD Red-Green-Refactor Loop

# TDD Red-Green-Refactor Loop Drive every change through a failing test. Production code written before a red test is speculation; delete it and start over. ## The loop 1. **Red.** Write one test that describes the next small behavior. Run it. Confirm it fails for the *right reason* — an assertion failure, not an import error or typo. If it fails with `ModuleNotFoundError` or a syntax error, fix the harness first; that failure tells you nothing about behavior. 2. **Green.** Write the smallest amount of production code that makes the test pass. Hardcoding a return value is legal here — the next test will force generalization. Run the whole relevant suite, not just the new test. 3. **Refactor.** With everything green, remove duplication you just introduced: extract the constant, collapse the copy-pasted branch, rename the variable that no longer describes its contents. Run the suite after every refactoring move. Do not add behavior in this step. 4. Repeat until the acceptance criteria are covered. ## Rules - One assertion concept per test. If a test name needs the word "and", split it. - Never write a second failing test while the first is still red. One red test at a time. - If you cannot make a test pass within ~3 attempts, the step is too big. Delete the test, write a smaller one that covers a fraction of the behavior, and climb up. - Test names state behavior, not implementation: `returns_empty_list_when_no_matches`, not `test_filter_function`. - Test through the public interface. If you need to reach into private state to assert, the design is telling you a collaborator wants to be extracted. - Commit at green, never at red. A green commit after each loop keeps `git bisect` useful. ## Sizing the first test - Start with the degenerate case (empty input, zero items, simplest valid call), not the interesting one. It forces the signature and wiring into existence with almost no logic. - For a bugfix, the first test *is* the bug report: reproduce the reported failure as an assertion, watch it go red, then fix. - For code with awkward dependencies (clock, network, randomness), the first red test will force you to inject them. Good — that pressure is the design feedback TDD exists to provide. ## When to stop Stop adding tests when: - Every requirement in the task maps to at least one test. - Edge cases that can actually occur are covered: empty input, boundary values, duplicate entries, the error path. - You are about to test the framework, the standard library, or a mock talking to another mock. Don't. ## Checklist before declaring done - [ ] Every new test was observed failing before it passed. - [ ] Full suite green, not just the new file. - [ ] No production code lacks a test that would fail if it were deleted. - [ ] Refactor step actually ran — scan the diff for copy-paste you left behind. - [ ] No `skip`, `only`, or commented-out tests in the diff.