TDD Workflow

Test-Driven Development is non-negotiable for new features and bug fixes. Tests come first. The workflow has three phases. Do not skip phases.

The cycle

┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│ 1. RED       │───▶│ 2. GREEN     │───▶│ 3. REFACTOR  │
│ Failing test │    │ Min code     │    │ Clean both   │
└──────────────┘    └──────────────┘    └──────────────┘
        ▲                                        │
        └────────────────────────────────────────┘

Phase 1 — RED

1. Write the smallest possible test that captures the next slice of behaviour.
2. Run it. It must fail, and fail for the right reason (the assertion, not a syntax error).
3. The failure message must point at the missing behaviour. If it says "ReferenceError: foo is not defined", you wrote the test before the function signature exists — that's fine, as long as that's the point of this test.

What "smallest" means:

• One assertion (or a small handful asserting the same fact).
• One scenario.
• One named test like returns_zero_for_empty_input or rejects_emails_without_domain.

Phase 2 — GREEN

1. Write the minimum code that makes the test pass.
2. Hardcoded values are allowed at this phase. return 0; is a valid GREEN if the only test asserts zero.
3. Don't generalize ahead of the tests. Triangulation comes from adding more tests, not from speculative branches.
4. Run all tests, not just the new one. Old tests still pass = no regression.

Phase 3 — REFACTOR

1. With every test green, restructure for clarity and remove duplication.
2. Acceptable refactors at this stage:
   • Extract method / parameter / variable.
   • Replace conditional with polymorphism.
   • Inline a too-thin abstraction.
   • Rename for accuracy.
3. Run all tests after every change. Green stays green.
4. Stop when the code reads cleanly. Don't over-design.

Rules

• No production code without a failing test that demands it. Period.
• One reason to fail per test. If a test could fail for two unrelated reasons, split it.
• Tests describe behaviour, not implementation. processes_payment_when_card_is_valid, not calls_StripeClient_charge_method.
• Fast tests first. Unit < integration < end-to-end. Run unit on every save; the slower tiers in CI.
• Coverage target is a floor, not a ceiling. 80% line coverage is the minimum, but coverage measures what code ran, not whether the behaviour is right.

What good test names look like

✓ calculates total including tax for domestic orders
✓ throws InvalidEmailError when domain is missing
✓ returns empty array when search has no matches
✓ rolls back transaction when downstream service times out

A reader who has never seen the code should be able to understand the spec from the test names alone.

Anti-patterns to flag

• Test written after the code ("but it passes!"). The test never failed, so it doesn't prove anything.
• Mocks of internals. Mock the boundary (database, HTTP), not your own classes.
• Test that does nothing if a precondition fails. Use a precondition assertion or skip, not a silent early return.
• Sleeping in tests. Use fake timers or polling with timeout.
• Snapshot tests for logic. Snapshots are for output that's expected to be stable and visually compared — not behavioural correctness.
• describe blocks deeper than 2 levels. That's a code smell — split the class under test.

When you find a bug

1. Write a failing test that reproduces the bug. Do not fix the code yet.
2. Confirm the test fails with the same symptom users see.
3. Fix the bug. The test goes green.
4. Now refactor if needed.

The test you write becomes a regression net forever.