synaptiai/tdd-patterns

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:

| Framework | Correct | Wrong | |-----------|---------|-------| | Vitest | vitest run | vitest (watch) | | Jest | CI=true jest or jest --watchAll=false | jest (watch) | | Pytest | pytest | — | | RSpec | rspec | guard (watch) |

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

| Scenario | TDD? | Notes | |----------|------|-------| | New feature | Always | Define behavior before implementing | | Bug fix | Always | Write reproducing test first | | Refactor | Existing tests | Ensure tests pass before AND after | | Prototype/spike | Optional | But write tests before merging | | Config changes | No | Unless behavior changes |

Process Enforcement

Check settings.json → testing.tddMode:

| Mode | Default? | Behavior | |------|----------|----------| | enforce | Yes | Block implementation without a failing test. No exceptions. The RED phase must produce a failing test before any production code is written. | | suggest | No (opt-in) | Recommend TDD. Allow override with explicit user decision. | | off | No (opt-in) | No TDD guidance. Tests still run in verification. |

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

| Excuse | Response | |--------|----------| | "Skip TDD just this once" | Delete the code. Start over. The cycle is the discipline. | | "This is too simple to test" | Simple code, simple test. Write it in 30 seconds. | | "I'll write tests after" | You won't. And if you do, they'll test what you wrote, not what you should have written. | | "Tests slow me down" | Tests slow you down NOW. Bugs slow you down FOREVER. | | "The test passes on first try" | That's a red flag. It should have failed first. Check: is it testing the right thing? |

Stop Conditions

| Trigger | Action | |---------|--------| | Test passes immediately on first write | Test is suspect. Verify it fails when you break the code intentionally. | | >3 tests needed for one function | Function may be doing too much. Consider splitting. | | Mocking >2 dependencies | Design smell. Refactor to reduce coupling. | | Test is harder to write than the code | Step back. Either the interface is wrong or the test is testing implementation. |