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

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

Common TDD Pitfalls

See Also

• @test-engineer — test strategy, framework detection, coverage gap analysis
• /ultraqa — QA cycling: test, verify, fix, repeat
• /verify — evidence-based completion verification