test-driven-development

Test-Driven Development

Enforce the RED-GREEN-REFACTOR cycle for all implementation work. Tests define the design. Code satisfies the tests. Refactoring improves the design without changing behavior.

Iron Law

TESTS FIRST, ALWAYS

Write the failing test before the production code. No exceptions. If you catch yourself writing production code without a failing test, stop immediately, delete the production code, write the test, watch it fail, then write the minimum code to make it pass. The test IS the specification.

---

The Cycle

Affected tests: the tests that cover the changed files, selected by the runner's related-test option (Jest's --findRelatedTests, Vitest's related) or, where the runner has none, the package or path that owns them. Every "run the tests" step below means the affected tests; the full suite belongs to Validate.

Step 1: RED — Write a Failing Test

Write a test that describes the behavior you want. Run it. Watch it fail. The failure message IS your specification.

Describe what the code SHOULD do, not how it does it.
One behavior per test. One assertion per test (ideally).
Name tests as sentences: "returns error when email is invalid"

Checkpoint: The test MUST fail before proceeding. A test that passes immediately proves nothing.

Step 2: GREEN — Write Minimum Code to Pass

Write the simplest production code that makes the failing test pass. No more, no less.

Hardcode first if that's simplest. Generalize when the next test forces it.
Don't write code "you'll need later." Write code the test demands NOW.
Don't optimize. Don't refactor. Don't clean up. Just pass the test.

Checkpoint: All affected tests pass. If any test fails, fix it before moving on.

Step 3: REFACTOR — Improve Without Changing Behavior

Now clean up: extract helpers, rename, simplify, apply DRY. Tests stay green throughout.

Run the affected tests after every refactoring step.
If a test breaks during refactor, undo immediately — you changed behavior.