TDD: red → green → refactor

1 · The TDD loop essential

You've almost certainly lived the other way round. You write a chunk of code, it looks right, and only then do you tack on a test — usually one that pokes at whatever the code already happens to do. It passes. You feel safe. But that test never had a chance to fail, so you never proved it actually checks anything: it's a test written to agree with the code, not to challenge it. Weeks later a refactor quietly breaks the behaviour, the test still passes because it was always toothless, and the bug ships. Test-Driven Development flips the order precisely to kill that failure mode.

The mental model is a heartbeat — a tiny three-beat rhythm you repeat dozens of times an hour: Red, Green, Refactor. Think of it like a builder who lays a single guide-string before laying each row of bricks. You don't build the whole wall and then check if it's straight; you set the string (the test), lay one row to meet it (the code), then step back and tidy the mortar (the refactor) — every single row.

• Red — write a test for behaviour that does not exist yet and watch it fail. The failure is not a mistake, it's the point: a test that fails first has proven it can detect the wrong answer.
• Green — write the least code that makes it pass. Not the elegant version, not the general version — the dumbest thing that turns the bar green. Cleverness comes later.
• Refactor — now, and only now, improve the code (rename, de-duplicate, extract). The green test is your safety net: if you break something, it goes red instantly.

Why this precise order, and not "code then test"? Because writing the test first forces you to answer one question before you're emotionally invested in an implementation: what does "done" actually mean? The failing test is an executable specification. It also guarantees the test has teeth — you have literally watched it fail — which the after-the-fact test never gives you. The most common beginner mistake is skipping the Red step ("I'm sure it fails") and writing the assertion after the code; do that and you've thrown away the one guarantee TDD exists to give you. The second most common mistake is over-building in the Green step — writing the whole feature before a test asks for it — which quietly drags you back to code-first with extra steps.

2 · TDD in action (runs, step by step) intermediate

The loop sounds tidy on a diagram; the doubt hits the moment you try it. "Write a failing test first" feels backwards, even wasteful — how do you test a function you haven't written? So most people abandon it on the first hard problem and go back to coding. The cure is to watch it work on something with a genuine twist, where the design is not obvious up front. Converting Roman numerals to integers is perfect: it looks trivial until IV shows up and breaks your first instinct.

Here's the naive mental model everyone starts with: "add up the value of each letter." III → 1+1+1 = 3. Great. Then you write the test roman_to_int("IV") == 4 and run it — and your add-everything code returns 6 (5 + 1). Red. That failing test just did something a spec document never could: it forced a design decision. You can't make it green without discovering the real rule — a smaller symbol placed before a larger one is subtracted, not added. TDD didn't just verify the code; it dragged the correct algorithm out of you, one failing case at a time.

That is the deeper claim of this section: the test is not checking the design, the test is driving the design. Working outside-in — from the behaviour you want back toward the code that produces it — you become the first user of your own function. You feel its awkward edges before anyone else does. The disciplined rhythm is: add exactly one new failing assertion (III, then the tricky IV, then a big multi-symbol MCMXCIV), make it green with the minimum change, repeat. Each red bar names precisely the next piece of behaviour the code is missing.

The lab below collapses that whole sequence into one finished, runnable script so you can see the destination — but read it bottom-first. The assert lines are the tests that came first; the function above them is what those tests pulled into existence. The common mistake here is writing all the asserts at once and then all the code at once: that's not TDD, it's just testing-after wearing a costume. The value is in the small laps, where every step is guarded before the next begins.

Build roman_to_int test-first. Each block adds a failing case then the code to pass it — here shown as one runnable script proving the final result.

tdd_roman.pyVALUES = {"I":1,"V":5,"X":10,"L":50,"C":100,"D":500,"M":1000}
def roman_to_int(s):
    total, prev = 0, 0
    for ch in reversed(s):
        val = VALUES[ch]
        total += val if val >= prev else -val   # subtract when smaller than prev
        prev = val
    return total

# the tests that DROVE this design, now all green:
assert roman_to_int("III") == 3
assert roman_to_int("IV") == 4          # the case that forced the subtract logic
assert roman_to_int("MCMXCIV") == 1994
print("TDD complete: all cases green")

TDD complete: all cases green

3 · TDD as design pressure advanced

Here's a scene from every codebase. You sit down to write a test for one function, and before you can assert anything you have to build a database connection, stub out a payment gateway, fake three environment variables, and construct a 40-line object just to reach the one line you actually care about. You mutter "testing is so much work" and either write a shallow test or skip it. That frustration is real — but the lesson almost everyone draws from it is exactly backwards. The problem is not the test. The pain is a message about the design.

Think of a test as a customer trying to use your function through the front door. If the customer needs a 40-step ritual to place a simple order, you don't blame the customer — you fix the shop. A function that's hard to test is hard to use; the test is just the first honest attempt to use it in isolation, and it's reporting back that the function does too much or depends on too much. When you write the test first, you get that report before you've written a single line of implementation to fall in love with — which is why TDD is a design tool, not merely a safety net.

What does the pain actually point at? Almost always one of two smells. Either the unit has too many responsibilities (it parses and validates and formats and saves, so no test can isolate one behaviour), or it has too many hard dependencies baked in (it reaches out and constructs its own database or clock, so you can't substitute a fake). The fix for the first is to split it into small, single-purpose functions; the fix for the second is to inject the dependency — pass it in as an argument so a test can hand over a stand-in. Both moves make the unit smaller, purer, and — not coincidentally — easier to reason about for the next human who reads it.

So the discipline is: when a test feels awkward, stop and listen instead of pushing through. The awkwardness is design feedback arriving at the cheapest possible moment — before the shape has hardened into the codebase and a dozen callers depend on it. The mistake is to grit your teeth and write the elaborate scaffolding anyway; every line of that scaffolding is the test telling you to refactor, and you're paying to ignore it. Let the difficulty of the test drive the split (this is where TDD hands you straight over to the single-responsibility principle in SD3).

Writing the test first makes you the first user of your API. If the test is awkward to write, the design is wrong — TDD surfaces that immediately, nudging toward small, injectable units.

4 · Professional — always TDD a bug fix professional

Every engineer knows this sick feeling. A bug comes in, you find the offending line, you change it, it looks fixed, you ship. Three weeks later the same bug is back — a well-meaning refactor, a merge, or a "cleanup" quietly undid your fix, and nothing caught it because there was no test standing guard. You fix it again. This is the most demoralising loop in software: fixing the same thing twice. Bug-fix-first TDD is the single cheapest habit that ends it, and it's the one place even TDD skeptics agree the practice is non-negotiable.

The rule is one sentence: reproduce the bug with a failing test before you touch the code. Think of it like a crime scene — before you clean anything up, you photograph exactly what went wrong. Write a test that asserts the correct behaviour for the exact input that broke, and run it. It goes red. That red bar is proof of two things at once: the bug is real (you've reproduced it, not just imagined it), and your test can actually detect it. Only then do you write the fix and watch it turn green.

Why does the order matter so much for bug fixes specifically? Because a bug is, by definition, a case your existing tests missed — so the bug itself is handing you the precise test that was absent. Skip the red step and you fall into the classic trap: you write the fix, then write a test, and the test passes on the first run. But you never saw it fail, so you have no evidence it's testing the bug rather than something adjacent. Worse, a subtle fix can be wrong in a way that a hastily-written after-test also gets wrong. The failing-first test is the only version that proves your fix addresses the reported behaviour.

And here's the compounding payoff: once green, that test never leaves. It becomes a permanent regression guard — a tiny, self-documenting record that says "this specific thing broke once, and here's the proof it can't break again." Do this for every bug and your test suite slowly turns into an accumulated history of every mistake your system has ever made and survived. That's why leads make it a team rule regardless of how they feel about TDD for new features: it's the highest-reliability-per-keystroke move in the whole discipline.

The one place TDD is nearly always right: reproduce the bug with a failing test first, then fix. Now it can never silently return.

bugfix.pydef parse_range(s):
    # bug: didn't handle a single number like "5"
    if "-" in s:
        a, b = s.split("-"); return list(range(int(a), int(b)+1))
    return [int(s)]                     # <- the fix, driven by the test below

# RED (reproduces the reported bug), now GREEN after the fix:
assert parse_range("1-3") == [1, 2, 3]
assert parse_range("5") == [5]          # the previously-broken case
print("bug reproduced by a test, then fixed -> permanent regression guard")

bug reproduced by a test, then fixed -> permanent regression guard

5 · Tech-lead — when to mandate TDD tech-lead

TDD converts people, and converts get zealous. Someone reads the first four sections, feels the click, and declares that all code must be written test-first, forever, no exceptions. Then they try to TDD an exploratory data spike where they don't yet know what the answer looks like, or a bit of throwaway UI glue, and the tests become guesswork they rewrite five times an hour. The team's velocity tanks, morale sours, and someone concludes "TDD doesn't work" — when the real failure was applying one tool to every job. A tech-lead's value here is refusing both extremes: neither dogma nor abandonment, but a written policy the team can apply without re-litigating it every standup.

The judgement rests on a simple question: does the code have a knowable spec before you write it? TDD needs a target to aim the failing test at. Where the target is crisp, test-first is a gift; where you're still discovering the target, test-first is friction. That splits the world into a few clear buckets:

• Bug fixes — always TDD. Non-negotiable, for every reason in §4. The spec is the bug report itself.
• Well-specified, logic-heavy features — TDD pays. Clear rules plus real branching (a pricing engine, a parser, a permissions check) is exactly where the failing tests both design and protect the code.
• Spikes and prototypes — skip it. When the goal is to learn what to build, testing a design you're about to throw away is wasted motion. The honest move: spike to learn, then delete the spike and rebuild it test-first for real.
• Clear-but-trivial or pure-UI glue — tests-after is fine. A one-line passthrough doesn't need a test written first; a light test afterward is enough.

The point of codifying this — as the runnable policy function below does — is that it removes the argument from the individual and puts it in the process. When "should I TDD this?" has a written answer, a junior engineer isn't guessing and a reviewer isn't imposing a personal preference; the team just applies the rule. The mistake a new lead makes is leaving the policy implicit ("we do TDD here") and then being surprised when everyone interprets it differently. Make it explicit, make it defensible, and let it flex where the work genuinely calls for exploration.

A lead is pragmatic: mandate TDD where it pays (clear rules, non-trivial logic, all bug fixes), relax it for spikes/UI. Codify it so the team knows the expectation.

tdd_policy.pydef should_tdd(kind, clarity, logic_complexity):   # clarity/complexity 1-5
    if kind == "bugfix": return True                # always
    if kind in ("spike", "prototype"): return False
    return clarity >= 3 and logic_complexity >= 3   # clear + non-trivial

for case in [("bugfix",1,1), ("feature",4,4), ("feature",4,1), ("spike",5,5)]:
    print(case, "->", "TDD" if should_tdd(*case) else "skip")

('bugfix', 1, 1) -> TDD
('feature', 4, 4) -> TDD
('feature', 4, 1) -> skip
('spike', 5, 5) -> skip

import unittest

def fizzbuzz(n):
    # GREEN: simplest thing that passes
    if n % 15 == 0: return "FizzBuzz"
    if n % 3 == 0:  return "Fizz"
    if n % 5 == 0:  return "Buzz"
    return str(n)

class TestFizzBuzz(unittest.TestCase):
    def test_cases(self):
        self.assertEqual(fizzbuzz(1), "1")
        self.assertEqual(fizzbuzz(3), "Fizz")
        self.assertEqual(fizzbuzz(5), "Buzz")
        self.assertEqual(fizzbuzz(15), "FizzBuzz")

if __name__ == "__main__":
    unittest.main(verbosity=2)     # RED before impl; GREEN after

import unittest

def roman(n):
    table = [(1000,"M"),(900,"CM"),(500,"D"),(400,"CD"),(100,"C"),
             (90,"XC"),(50,"L"),(40,"XL"),(10,"X"),(9,"IX"),
             (5,"V"),(4,"IV"),(1,"I")]
    out = []
    for value, sym in table:
        while n >= value:
            out.append(sym); n -= value
    return "".join(out)

class TestRoman(unittest.TestCase):
    def test_one(self):        self.assertEqual(roman(1), "I")     # step 1
    def test_four(self):       self.assertEqual(roman(4), "IV")    # step 2
    def test_fourteen(self):   self.assertEqual(roman(14), "XIV")  # step 3
    def test_1994(self):       self.assertEqual(roman(1994), "MCMXCIV")

if __name__ == "__main__":
    unittest.main(verbosity=2)     # 4 tests OK

import unittest

# PAINFUL: parse + validate + format in one function forces a big, brittle test.
# EASIER after splitting into small pure functions:
def parse(line): return dict(zip(("name", "age"), line.split(",")))
def valid(rec):  return rec["age"].isdigit() and int(rec["age"]) >= 0
def fmt(rec):    return f"{rec['name']} ({rec['age']})"

class TestPipeline(unittest.TestCase):
    def test_parse(self):  self.assertEqual(parse("ada,42"), {"name":"ada","age":"42"})
    def test_valid(self):  self.assertTrue(valid({"name":"ada","age":"42"}))
    def test_format(self): self.assertEqual(fmt({"name":"ada","age":"42"}), "ada (42)")

if __name__ == "__main__":
    unittest.main(verbosity=2)     # each piece tested in isolation, trivially

import unittest

# Bug report: last item dropped from pagination.
def page(items, size):
    # BUGGY: range(0, len, size) with a wrong stop drops the tail
    # FIXED version below:
    return [items[i:i+size] for i in range(0, len(items), size)]

class TestPage(unittest.TestCase):
    def test_regression_last_item_kept(self):
        # This test reproduces the reported bug first.
        self.assertEqual(page([1,2,3,4,5], 2), [[1,2],[3,4],[5]])
    def test_exact_multiple(self):
        self.assertEqual(page([1,2,3,4], 2), [[1,2],[3,4]])

if __name__ == "__main__":
    unittest.main(verbosity=2)     # regression test now guards the fix

def tdd_recommended(context):
    # context: dict of booleans about the work
    if context.get("bug_fix"):
        return True, "always TDD a bug fix (regression test first)"
    if context.get("exploratory_spike"):
        return False, "spike to learn, then delete or re-do test-first"
    if context.get("well_specified") and context.get("logic_heavy"):
        return True, "clear spec + branching logic -> TDD pays off"
    return False, "prefer tests-after here; keep them though"

print(tdd_recommended({"bug_fix": True}))
# (True, 'always TDD a bug fix (regression test first)')
print(tdd_recommended({"exploratory_spike": True}))
# (False, 'spike to learn, then delete or re-do test-first')
print(tdd_recommended({"well_specified": True, "logic_heavy": True}))
# (True, 'clear spec + branching logic -> TDD pays off')

# .github/workflows/tests.yml   (needs GitHub Actions)
name: tests
on:
  pull_request:
  push:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install
        run: pip install -e . pytest
      - name: Run tests (fails the PR if any test is red)
        run: pytest -q
      # Convention enforced in review: a bug-fix PR must add a test that
      # fails on the parent commit. The green suite here is the gate.

Knowledge check check yourself