TDD — Test-Driven Development
THE IRON LAW: Write the failing test FIRST. Always.
The Red-Green-Refactor Cycle
RED → Write a failing test for the NEXT behavior
GREEN → Write ONLY enough code to make it pass (no extras)
REFACTOR → Clean up code quality (tests must stay green after every change)
REPEAT
Step-by-Step Protocol
1. RED Phase
- Identify the smallest next behavior to implement
- Write a test that describes that behavior as a named
it()/test()/def test_ - Run the test — it MUST FAIL. If it passes, the test is wrong.
- Confirm the failure message is the RIGHT failure (not a syntax error)
// Example: RED — test fails because function doesn't exist yet
it('returns an empty array for an empty input', () => {
const result = parseItems([]);
expect(result).toEqual([]); // FAILS: parseItems is not defined
});
2. GREEN Phase
- Write the MINIMUM code to make the test pass
- Do not add extra logic, default parameters, or "nice-to-haves"
- Run ALL tests — the new test must pass; existing tests must not break
// Example: GREEN — just enough to pass
function parseItems(input: string[]): string[] {
return []; // only enough for the current test
}
3. REFACTOR Phase
- Look at the code — can it be cleaner without changing behavior?
- Apply simplification patterns (see
/ai-slop-cleanerand/coding-standards) - Run tests after EVERY change. If tests break, undo immediately.
TDD Gate — When to Stop
| Situation | Action |
|---|---|
| Code written before test | STOP. Delete production code. Write test first. |
| Test passes on first run (no prior code) | The test is wrong — fix it to fail first. |
| Multiple behaviors in one test | STOP. One test, one behavior. |
| Skipping refactor to go faster | Go back. Clean up before next feature. |
Naming Tests as Specifications
Tests are executable documentation. Name them as complete sentences:
// BAD
it('test1', ...)
it('works with empty', ...)
// GOOD
it('returns empty array when input is empty', ...)
it('throws ValidationError when email is missing @', ...)
it('sends exactly one email when user registers', ...)
Framework Quick Reference
| Framework | Failing assertion | Run single test |
|---|---|---|
| Vitest | expect(x).toBe(y) | npx vitest run -t "test name" |
| Jest | expect(x).toBe(y) | npx jest -t "test name" |
| pytest | assert x == y | pytest -k "test_name" |
| cargo test | assert_eq!(x, y) | cargo test test_name |
| go test | t.Errorf(...) | go test -run TestName |
Common TDD Pitfalls
| Pitfall | Fix |
|---|---|
| Testing implementation details | Test behavior (outputs), not internals (private methods) |
| One test for 10 behaviors | Split into atomic test cases |
| Mock everything (over-mocking) | Mock at system boundaries only (DB, HTTP, filesystem) |
| No triangulation | Write 2-3 tests that force the correct implementation to emerge |
| Untriangulated constants | return 42 passes one test — add a second test to force real logic |
See Also
@test-engineer— test strategy, framework detection, coverage gap analysis/ultraqa— QA cycling: test, verify, fix, repeat/verify— evidence-based completion verification