test-driven-development

Test-driven development

The loop

1. Red — write one test that fails for the right reason. Run it. A test that passes immediately

is testing nothing; a test that errors instead of failing is testing the wrong thing.

1. Green — the smallest change that makes it pass. Ugly is fine here.
2. Refactor — clean up with the test green. If it goes red, you changed behavior, not structure.

Never skip step 1. Writing the test after the code produces a test shaped to the implementation,

which is the one shape that cannot catch the implementation being wrong.

What to test

Test behavior at the boundary a caller actually depends on. For each unit ask: if this broke

silently, who notices and how? If the answer is nobody, delete the code rather than test it.

• Test: branching logic, boundary conditions, error paths, anything with a past bug, contracts

between modules.

• Do not test: getters, framework behavior, private helpers reachable only through a public path

already covered, exact wording of log lines.

Bugs

Every bug gets a failing test before the fix, reproducing it at the smallest scope that shows it.

That test is the proof the bug existed and the guard that it stays fixed. A fix without one is a

claim.

Rules

• One behavior per test. A test asserting five things tells you almost nothing when it fails.
• The test name states the behavior, not the method: rejects_expired_token, not test_auth.
• Never weaken an assertion to get green. If a test is inconvenient, the design is telling you

something.

• Never mock what you own — mock the network and the clock, not your own modules. Mocking your own

code tests the mock.

Never

• Write the test after the code and call it test-driven. You will test what you built rather than what was required.
• Skip watching the test fail. A test that has never failed proves nothing.
• Delete or skip a failing test to unblock a release. Fix it, or revert what broke it.
• Treat a coverage number as the goal. It counts lines executed, not behavior pinned down.

Return contract

Report the tests added, what each pins down, what is deliberately untested and why, and the actual

command you ran with its output. "Tests pass" without the command output is not a result.