tdd-best-practices

TDD Best Practices

Use this skill when the main question is how to drive implementation from tests, how to structure a test suite, or how to recover discipline in a codebase where tests were written after the fact.

Working Style

1. Write one failing test, then make it pass with the minimum code needed.
2. Refactor only when all tests are green.
3. Test behaviors, not implementations — the public API, not private methods.
4. Keep tests as simple as the production code they verify.
5. A test suite that is hard to change is as expensive as production code that is hard to change.

The Red-Green-Refactor Cycle

RED    → Write a failing test that describes the next behavior.
GREEN  → Write the minimum code to make it pass.
REFACTOR → Clean up both the code and the test — no new behavior.

The discipline is in the order. Never refactor on Red. On Green, add only the behavior demanded by the current failing test.

The 3 Laws (Uncle Bob)

1. You may not write production code unless you have a failing unit test.
2. You may not write more of a unit test than is sufficient to fail. An intentionally missing public API/type can be a valid first Red; unrelated compilation or setup failures are not.
3. You may not write more production code than is sufficient to make the currently failing test pass.

Design Workflow

1. Describe the behavior — what should the system do? Write the test name first.
2. Write a failing test — make it fail for the right reason (assertion, not setup error).
3. Make it pass — take the simplest path; you can clean up after.
4. Refactor — remove duplication, improve names, reduce complexity.
5. Repeat — the next test should be the smallest step forward.

Choosing Test Granularity

Level	Tests	Speed	Confidence
Unit	Single class/function in isolation	Milliseconds	Behavior of one unit
Integration	Multiple real collaborators	Seconds	Module boundaries work
Acceptance / E2E	Full system from user perspective	Minutes	Feature works end-to-end