Test Driven Development

Test-Driven Development (TDD)

Overview

Write the test first. Watch it fail. Write minimal code to pass. Then tidy.

Core principle: If you didn't watch the test fail, you don't know if it tests the right thing.

Announce at start: "I'm using the test-driven-development skill to drive this change test-first."

This skill is language-agnostic. The discipline below holds in every language; concrete framework, runner, and idiom examples live in references/languages/ — load the one matching your project.

Prerequisites

• A working test runner for your stack (see the matching references/languages/<lang>.md)
• Ability to run a single test and watch its output
• For mocks/test doubles, read references/testing-anti-patterns.md first

When to Use

Always:

• New features
• Bug fixes
• Refactoring
• Behavior changes

Exceptions (ask your human partner first):

• Throwaway prototypes (then throw them away and restart with TDD)
• Generated code
• Pure configuration changes

Thinking "skip TDD just this once"? Stop. That's rationalization.

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Wrote code before the test? Delete it. Start over.

No exceptions: don't keep it as "reference", don't "adapt" it while writing the test, don't even look at it. Delete means delete. Implement fresh from the test.

Workflow

Phase 1: Build a Test List (Canon TDD)

Before writing any test, list the behaviors you need to cover — the basic case plus every variant you can think of ("what if the input is empty? what if the service times out? what if the key is missing?").

• This is behavioral analysis, not implementation design.
• Keep the list visible. Add to it whenever you discover a new case mid-cycle.
• Turn exactly one item into a concrete test at a time — never convert the whole list up front (reworking speculative tests when an early decision changes is wasted effort).

Phase 2: Red-Green-Refactor — one list item at a time

pick one item  →  RED  →  verify red  →  GREEN  →  verify green  →  REFACTOR  →  back to the list

Run tests in the quietest mode that still surfaces failures. Verbose pass logs burn context you don't need — quiet runners stay silent on green and print full detail on red, so you keep the failures without the noise. Switch to verbose (-v / -s / --nocapture) only when isolating one test's output. Per-language quiet flags are in each references/languages/<lang>.md.

RED — write one failing test

One behavior, a name that describes that behavior (e.g. shouldRetryThreeTimesThenSucceed, not test1), real code over mocks. Work backwards from the assertion. See your language file for concrete framework syntax.

Verify RED — watch it fail (MANDATORY, never skip)

Run the single test. Confirm:

• It fails, not errors (no typos/missing imports)
• It fails for the expected reason — the behavior is missing, not the setup is broken

Test passes already? You're testing existing behavior. Fix the test.

GREEN — minimal code to pass

Write the simplest code that makes this test (and all previous tests) pass. No speculative APIs, no extra options, no "while I'm here" cleanup. YAGNI.

Verify GREEN — watch it pass (MANDATORY)

Run the test. Confirm it passes, all previous tests still pass, and output is pristine (no warnings/errors). Test fails? Fix the code, not the test.

REFACTOR — only on green

Remove duplication, improve names, extract helpers. Keep every test green. Don't add behavior here — that's the next RED.

Then mark the item done and return to the list. Repeat until the list is empty.

Phase 3: Tidy First — separate structural from behavioral changes

Kent Beck's distinction. Every change is one of two kinds — never mix them in one commit:

• When you need both, make the structural change first, on green.
• Validate a structural change didn't alter behavior by running the tests before and after — they stay green throughout.
• If a change is a tangle of both, untangle it (or redo it) into a structural step then a behavioral step.

Phase 4: Commit Discipline

Commit only when:

• All tests pass and all compiler/linter warnings are resolved
• The change is a single logical unit
• The commit message states whether it is structural or behavioral

Prefer small, frequent commits over large, infrequent ones. (For this repo's commit format, the git-commit skill applies — structural vs behavioral maps cleanly onto its refactor: vs feat:/fix: types.)

Why Test-First (Not Test-After)

Tests written after code pass immediately — and passing immediately proves nothing: they may test the wrong thing, test the implementation instead of behavior, or miss the edge case you forgot. You never saw them catch anything.

Test-after answers "what does this do?" Test-first answers "what should this do?" — and forces edge-case discovery before you implement. 30 minutes of tests-after gives you coverage but loses the proof the test works.