tdd

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

1. Identify the smallest next behavior to implement
2. Write a test that describes that behavior as a named it() / test() / def test_
3. Run the test — it MUST FAIL. If it passes, the test is wrong.
4. 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

1. Write the MINIMUM code to make the test pass
2. Do not add extra logic, default parameters, or "nice-to-haves"
3. 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

1. Look at the code — can it be cleaner without changing behavior?
2. Apply simplification patterns (see /ai-slop-cleaner and /coding-standards)
3. 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