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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jmstar85
• Source: jmstar85/oh-my-githubcopilot
• License: MIT
• Homepage: https://www.linkedin.com/in/minsungjung/

Install and usage instructions live in the source repository linked above.