test-driven-development

name	test-driven-development
description	Use when implementing any new feature, fixing a bug, or refactoring existing code. Enforces red-green-refactor discipline throughout.

Test-Driven Development

Core Rule

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.

Write the test. Watch it fail for the right reason. Write the minimum code to make it pass. Refactor. Repeat.

This is not a guideline. If code exists before its test, delete the code and start over.

The Cycle

RED — Write a failing test

1. Write the smallest test that demonstrates the missing behavior.
2. Run it. Confirm it fails — and fails for the right reason (the feature doesn't exist, not a setup error, not a typo in the test).
3. Do not proceed until you have a legitimate red state.

GREEN — Write the minimum code to pass

1. Write only the code needed to make the test pass. Nothing more.
2. Resist the urge to build the "real" implementation — that's what refactor is for.
3. Run the test. Confirm it passes.
4. Run the full suite. Confirm nothing else broke.

REFACTOR — Clean up

1. Improve the implementation without changing behavior.
2. Tests must stay green throughout. If a test goes red, the refactor broke something.
3. Remove duplication. Clarify intent. Do not add new behavior here.

Repeat for the next behavior.

Hard Rules

• Watching the test fail is mandatory. A test written after the code proves nothing — it will pass immediately regardless of whether it's testing the right thing.
• Any code written before its test must be deleted and rewritten after a failing test exists. "I'll use it as a reference while I write the test" is rationalization.
• "I'll add tests after" is not TDD. It is writing code twice, in the wrong order.
• Manual testing does not substitute for an automated test suite.

What Makes a Good Test

• Minimal — tests one behavior, not a whole workflow
• Named clearly — the name describes the expected behavior, readable as a sentence
• Tests behavior — not implementation details or internal state
• Uses real inputs — prefer real values over mocks where the real thing is practical

Common Rationalizations to Reject

Rationalization	Response
"This code is too simple to need a test"	Simple code has simple tests. Write it.
"I'll add tests once the API stabilizes"	The tests help stabilize the API. Write them first.
"There's no time for TDD right now"	TDD is faster than debugging untested code later.
"It's already written, I'll just test it now"	Delete it. Rewrite it after the test.
"I need to see it working before I can write a test"	Write the test for how it should work. That's the point.