{"canonical_url":"https://engineer.company/glossary/test-driven-development/","content_markdown":"# Test-driven development\n\n## What it is\n\nTest-driven development is a way of programming in which the test for a piece of\nbehaviour is written before the code that provides it, one small test at a time.\nKent Beck, who describes his own part in it as a rediscovery, calls it a\nprogramming workflow. In 2023, after finding that programmers did not agree on\nwhat the term meant, he set the workflow down in a short post titled Canon TDD,\nand he writes the abbreviation, TDD, almost everywhere in it.\n\nThe workflow has five steps:\n\n1. List the cases the change has to handle.\n2. Pick exactly one case from the list and write it as a concrete test that\n   runs.\n3. Make that test pass without breaking any earlier one, and put on the list\n   every new case the work brings to light.\n4. If the design of the implementation can be better, refactor it now; this\n   step is optional.\n5. Return to step 2 until nothing is left on the list.\n\nThe list is analysis of behaviour, not a design document: the basic case first,\nthen the variations, then the ways the change must not break what already works.\nThe test written in step 2 is a real automated test, with setup, an invocation\nand assertions, and it fails when it first runs, since the behaviour it\ndescribes is still to be written. Beck calls step 3 going from red to green,\nfrom a failing test to a passing one.\n\nIt is just as useful to know what the workflow is not. Writing every test before\nwriting any code is a frequent complaint about TDD, and Beck answers it\ndirectly: that is not TDD, and a critique of it is a critique of something else.\nHe is equally relaxed in the other direction. A team that works differently and\ngets good results is welcome to, and he says there is no gold star for following\nthe steps exactly.\n\n## Why it matters\n\nBeck states what the workflow is for. A programmer who changes the behaviour of\na system should end up with a system in which the change preserves existing\nbehaviour while satisfying the new requirements, the code is ready for the next\nchange, and the programmer and their colleagues feel confident about all three.\nBecause each test is written while its change is small and fresh, the safety net\ngrows at the same pace as the code instead of being promised for later.\n\nThe second reason is design. Beck separates two kinds of design decision: how a\npiece of behaviour is invoked, and how the system implements it. Writing the\ntest first forces the interface decisions, because the test has to call\nsomething and has to say what comes back. The implementation decisions wait for\nthe refactoring step, when passing tests protect them. A test that is awkward to\nwrite is early news that the interface will be awkward to use.\n\nThe third reason is the double check. The expected value in a test is worked out\nby a person from the requirement, and the code arrives at it a second way. When\nthe two agree, two independent routes have reached the same answer, and Beck\nsays that double checking is where much of TDD's value as a check comes from.\n\nThere is also a sense of when to stop. Beck's advice is to keep testing and\ncoding until fear about how the code behaves has turned into boredom. The habit\nis much older than the post. Beck places his rediscovery between 1994, when he\nwrote SUnit for a consulting client, and October 1995, when he demonstrated TDD\nto Ward Cunningham at the OOPSLA conference in Austin. His paper Simple\nSmalltalk Testing describes a simple testing framework for Smalltalk, and\nPython's unittest documentation still points to it as Beck's original paper on\nthe pattern that unittest shares.\n\n## What it looks like in practice\n\nTake a content check that should report banned buzzwords in a website's copy.\nThe work starts with the test list, written as plain notes:\n\n```text\n- a banned word is reported\n- a banned word with a capital letter is reported\n```\n\nStep 2 turns exactly one item into a test. The first item comes first for a reason: it gives the check a known banned word and asserts that the word is reported. The test fails until the check can find it. It goes in a file called `test_wording.py`, which\npytest collects because the name matches `test_*.py`:\n\n```python\nfrom wording import find_banned\n\n\ndef test_reports_a_banned_word():\n    assert find_banned(\"we leverage it\", {\"leverage\"}) == [\"leverage\"]\n```\n\nRunning `pytest -q` fails at once, because there is no `find_banned` to import.\nThat failure is the point: the test has been seen to fail, so a pass later on\nmeans something. The simplest code that makes it pass is enough for now, in\n`wording.py`:\n\n```python\ndef find_banned(text, banned):\n    return [word for word in text.split() if word in banned]\n```\n\nThe test passes. The next item becomes the next test:\n\n```python\ndef test_reports_a_capitalised_banned_word():\n    assert find_banned(\"Leverage it\", {\"leverage\"}) == [\"Leverage\"]\n```\n\nIt fails, and because pytest reports the intermediate values of an assertion,\nthe output shows an empty list where `[\"Leverage\"]` was expected. Comparing\n`word.lower()` instead of `word` makes it pass. While writing that change, the\nprogrammer notices that `text.split()` leaves punctuation attached, so\n\"leverage,\" with a comma would slip through. That goes on the list rather than\ninto the code, and becomes the third test:\n\n```python\ndef test_reports_a_banned_word_before_a_comma():\n    assert find_banned(\"Use it, leverage, win\", {\"leverage\"}) == [\"leverage\"]\n```\n\nIt fails, and one more line makes all three pass:\n\n```python\ndef find_banned(text, banned):\n    words = [word.strip(\".,;:!?\") for word in text.split()]\n    return [word for word in words if word.lower() in banned]\n```\n\nStep 4 is optional, and here there is little to improve: two lines, each with\none job. Every item on the list now has a passing test, so the work is done.\nEach expected value in the tests was written from the list item, never pasted\nfrom a run.\n\nThe order of that list was deliberate, and the site's own record shows why. A\n[project that wrote tests for its own checkers](/portfolio/wrote-tests-for-the-checkers-themselves/),\nwork carried out in August 2026, found that its custom checks, among them a\nspell check, a voice check and a figure-consistency check, had run green for\nmonths, and that a checker which has only ever seen clean input cannot be told\napart from one that reads nothing. The fix was to plant the defect each checker\nexists to find: the spell check is fed a deliberately misspelled word and the\ntest fails if the run comes back clean, the voice check is fed prose in the\nfirst person and must reject it, and the buzzword check is fed a banned word.\nTwo of the checkers turned out to read a narrower set of files than their\ndocumentation claimed. The page does not describe TDD, but its lesson is the one\nTDD builds in from the first step: a test is worth something only once it has\nbeen seen to fail.\n\n## Where it goes wrong\n\n**All the tests are written first.** Turning every item on the list into a test\nbefore any of them passes is the misreading Beck singles out. When the first\ntest forces a rethink, every speculative test needs rework, and a programmer on\nthe sixth test without a single pass, he writes, meets depression or boredom.\nWrite one test, make it pass, then pick the next. If a new test shows that the\nwork so far cannot handle a case, choose between carrying on and starting again;\nBeck's advice is to start again and take the cases in another order.\n\n**The test has no assertion.** A test that calls the code and checks nothing\nraises the coverage figure and proves nothing. Every test needs setup, an\ninvocation and an assertion, and Beck suggests trying, now and then, to write a\ntest backwards from its assertions.\n\n**The assertion is deleted.** When a test will not pass, deleting its assertion\nmakes it pretend to. Make it pass for real, or take the item back to the list\nand rethink the order.\n\n**Expected values are pasted from the output.** Running the code, copying what\nit returned and pasting that into the test turns a double check into a single\none: the test now confirms only that the code does what it did. Work the\nexpected value out from the requirement, by hand if necessary.\n\n**Refactoring while making it pass.** Changing structure and behaviour in the\nsame step is what Beck calls wearing two hats. Make it run, then make it right:\nreach green with the simplest change, and tidy up only once the tests pass.\n\n**Tidying too far, or abstracting too soon.** Tidying feels good, and it can\nfeel safer than facing the next test. Stop when the code is good enough for this\nsession, and leave two similar pieces of code alone until the pattern is clear.\nBeck's line on this is short: \"Duplication is a hint, not a command.\"\n\n**The tests know the implementation.** Tests that call private methods or check\nwhich calls the code made, rather than what it produced, break whenever the\ninternals change. Erik Kuefler's chapter on unit testing in _Software\nEngineering at Google_ calls them brittle tests: they fail on an unrelated\nchange that introduces no real bug. In TDD that is doubly costly, because the\nrefactoring step depends on tests that stay green while the internals move. Test\nthrough the public interface, check the resulting state rather than the\ninteractions, and name each test after the behaviour it checks.\n\n## Further reading\n\n- [Canon TDD](https://newsletter.kentbeck.com/p/canon-tdd)\n  — Kent Beck's own statement of the workflow, from 2023: the five steps, the\n  split between interface and implementation design, and the mistakes at each\n  step.\n- [Simple Smalltalk Testing: With Patterns](https://web.archive.org/web/20150315073817/http://www.xprogramming.com/testfram.htm)\n  — Beck's paper on a simple testing framework for Smalltalk, with its fixtures,\n  test cases and suites, in an archived copy.\n- [Unit Testing](https://abseil.io/resources/swe-book/html/ch12.html)\n  — Erik Kuefler's chapter of _Software Engineering at Google_ on tests that\n  survive refactoring, testing through public APIs and testing behaviours.\n- [Get Started](https://docs.pytest.org/en/stable/getting-started.html)\n  — pytest's introduction: installing it, a first failing test with its report,\n  and how test files are found.\n- [unittest: Unit testing framework](https://docs.python.org/3/library/unittest.html)\n  — the Python standard library's framework, which names Beck's paper as the\n  original description of the pattern it shares.\n\n\u003chttps://engineer.company/glossary/test-driven-development/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"The five steps of test-driven development, a worked pytest example from test list to green, and the mistakes Kent Beck warns against.","formats":{"gemtext":"https://engineer.company/glossary/test-driven-development/index.gmi","gopher":"https://engineer.company/glossary/test-driven-development/gophermap","html":"https://engineer.company/glossary/test-driven-development/","json":"https://engineer.company/glossary/test-driven-development/index.json","markdown":"https://engineer.company/glossary/test-driven-development/index.md","pdf":"https://engineer.company/glossary/test-driven-development/index.pdf"},"kind":"page","language":"en","title":"What is test-driven development?","url":"https://engineer.company/glossary/test-driven-development/","version":1}