TDD Patterns

Domain skill for test-driven development: Red-Green-Refactor cycle, test quality, and runner discipline.

Iron Law

IF YOU DIDN'T WATCH THE TEST FAIL, YOU DON'T KNOW IF IT TESTS THE RIGHT THING.

A test that has never failed might pass for the wrong reason. The RED phase exists to prove the test is valid.

Red-Green-Refactor Cycle

For each feature or fix, track the TDD cycle with tasks:

TaskCreate("RED: Write failing test for {behavior}", "Minimal test describing desired behavior. MUST fail on first run.")
TaskCreate("GREEN: Implement {behavior}", "Simplest code to make the test pass. No cleverness.")
TaskCreate("REFACTOR: Clean up {behavior}", "Improve quality. All tests must still pass after each step.")

RED: Write a Failing Test

TaskUpdate(RED task, status: "in_progress")

1. Write the minimal test that describes the desired behavior
2. Run it — it MUST fail
3. Verify it fails for the right reason (not a syntax error, not wrong import)

TaskUpdate(RED task, status: "completed")

GREEN: Make It Pass

TaskUpdate(GREEN task, status: "in_progress")

1. Write the simplest code that makes the test pass
2. No cleverness. No optimization. No "while I'm here" improvements.
3. Run the test — it MUST pass now

TaskUpdate(GREEN task, status: "completed")

REFACTOR: Clean Up

TaskUpdate(REFACTOR task, status: "in_progress")

1. Improve code quality (naming, structure, duplication)
2. Run ALL tests after each refactor step — they must still pass
3. No new functionality during refactor — that's a new RED phase

TaskUpdate(REFACTOR task, status: "completed") Use TaskList to confirm the full cycle completed before moving to the next behavior.

The cycle is non-negotiable. RED → GREEN → REFACTOR. Always in this order.

Test Runner Discipline

Always use `run` mode, never `watch` mode:

Watch mode leaves orphan processes. Verify cleanup:

pgrep -f "vitest|jest|pytest" && echo "ORPHAN PROCESS — kill it"

Test Quality Standards

One Behavior Per Test

# GOOD: Each test verifies one thing
test "returns empty array when no items match"
test "returns matching items sorted by relevance"

# BAD: Multiple behaviors in one test
test "search works correctly"  # What does "correctly" mean?

Descriptive Names

Test names should read as specifications:

• "creates user with valid email"
• "rejects duplicate usernames"
• "returns 404 when resource not found"

Real Code Over Mocks

• Mock ONLY at external boundaries (APIs, databases, file system)
• Never mock the code under test
• Never mock internal collaborators unless they have side effects
• If you need many mocks, the design needs improvement

No Testing Implementation Details

• Test behavior (what), not implementation (how)
• Don't assert on internal state, private methods, or call counts
• If refactoring breaks tests but not behavior, the tests are wrong

When TDD Applies

Process Enforcement

Check settings.json → testing.tddMode:

Opt-out mechanism

enforce is the default because skipping the RED phase is the #1 source of tests that pass for the wrong reason. Teams that need the old suggest behavior can opt out:

{
  "testing": {
    "tddMode": "suggest",
    "tddModeOptOut": true
  }
}

Set testing.tddModeOptOut to true in settings.json to switch tddMode back to suggest. When tddModeOptOut is false (the default), tddMode must remain enforce. This two-field design ensures the opt-out is an explicit, auditable decision rather than a silent default change.

Coverage Targets

Aim for meaningful coverage, not vanity metrics:

• 80%+ for branches, functions, lines, statements
• 100% for critical paths (auth, payments, data mutations)
• 0% is acceptable for generated code, config files, type definitions

Rationalization Prevention

Stop Conditions