/tdd

name: tdd
description: Use before implementation when behavior can be verified by automated tests and regression coverage has clear value. For bugs with an unknown root cause, use systematic-debugging first, then return for red-green. Follow red-green-refactor—write a failing test first, add only enough code to pass it, then refactor. Do not trigger for documentation, configuration, copy-only, or styling changes with no testable behavior.
license: MIT

Hard rule: **write no implementation code without a test that failed first.** Did you just write the implementation in this turn without delivering it? Remove it and restart from the test—do not keep it as a "reference" or look at it while adding tests. **But never delete the user's existing code or someone else's workspace changes**: when working with an existing implementation, add tests that record and protect its current behavior before making the smallest change.

Excuses to stop as soon as they appear

| What you tell yourself | Reality | |---|---| | "Write the implementation first and add tests later." | Tests written afterward to match the implementation only prove that "the code does what it does," not that it is correct. | | "Keep this as a reference; do not really remove it." | The time is already spent; it is a sunk cost. If you keep it, you will shape the tests around it. Remove it (only if you wrote it this turn; never delete the user's existing code). | | "It is too simple to be worth testing." | "Simple" means an assumption you have not stated, which is exactly where failures happen. |

Red → Green → Refactor

1. **Red**: write the smallest failing test for one behavior. Give it a name that says what it tests, and test real code rather than mocks (use mocks only when unavoidable). 2. **Verify red (you must run it)**: watch it **fail**, specifically **because the behavior is not implemented yet**—not because of a typo, bad import, or syntax error.

• It passes immediately = you are testing behavior that already exists. The test has no value; rewrite it.
• The program errors instead of failing an assertion = fix the error and rerun until it "fails correctly."

3. **Green**: write the **minimum code needed to make it pass**. Do not slip in features that are not needed yet or change anything else. 4. **Verify green (you must run it)**: the test passes, every other test still passes, and the output is clean (no errors or warnings). If it fails, change the code, not the test. 5. **Refactor**: only after everything is green—remove duplication, improve names, extract functions. Keep the suite green throughout and add no new behavior. 6. For the next behavior, return to red.

Bugs also follow red-green

Write a failing test that **reproduces the bug** before fixing it. This test proves the fix and guards against recurrence. (See systematic-debugging for finding the root cause.)

A small example (adding email format validation)

1. **Red**: first assert that `is_valid_email("a@b.com")` is true and `is_valid_email("nope")` is false. The function does not exist yet; run the test and see it fail because the function is undefined, not because of a typo. 2. **Green**: write the smallest implementation (one regular expression) that makes both assertions pass. Do not add support for a pile of edge cases. 3. **Refactor**: extract constants or rename things only after everything is green; keep it green throughout.

These are design warnings, not testing difficulties

• A test is hard to write = the interface is hard to use. Simplify the interface.
• Everything requires a mock = coupling is too tight. Decouple it (dependency injection).
• Setup is huge = extract helpers; if it remains complex, simplify the design.