Test-Driven Development (TDD) Skill

Test-Driven Development (TDD)

Write the test first. Watch it fail. Write minimal code to pass.

If you wrote implementation code before the test, discard it and start fresh from the test.

The Cycle: Red → Green → Refactor

RED — Write Failing Test

Write one minimal test showing what should happen.

Good:

test("retries failed operations 3 times", async () => {
  let attempts = 0;
  const operation = () => {
    attempts++;
    if (attempts < 3) throw new Error("fail");
    return "success";
  };

  const result = await retryOperation(operation);

  expect(result).toBe("success");
  expect(attempts).toBe(3);
});

Clear name, tests real behavior, one thing.

Bad:

test("retry works", async () => {
  const mock = jest
    .fn()
    .mockRejectedValueOnce(new Error())
    .mockRejectedValueOnce(new Error())
    .mockResolvedValueOnce("success");
  await retryOperation(mock);
  expect(mock).toHaveBeenCalledTimes(3);
});

Vague name, tests mock not code.

Requirements:

One behavior per test
Clear name describing behavior
Real code (mocks only if unavoidable)

Verify RED — Run and Confirm Failure

npm test path/to/test.test.ts

Confirm:

Test fails (not errors from typos)
Failure is because the feature is missing
If test passes immediately: you're testing existing behavior — fix the test

GREEN — Minimal Code

Write the simplest code to pass the test. Nothing more.

Good:

async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
  for (let i = 0; i < 3; i++) {
    try {
      return await fn();
    } catch (e) {
      if (i === 2) throw e;
    }
  }
  throw new Error("unreachable");
}

Bad:

async function retryOperation<T>(
  fn: () => Promise<T>,
  options?: {
    maxRetries?: number;
    backoff?: "linear" | "exponential";
    onRetry?: (attempt: number) => void;
  }
): Promise<T> { /* YAGNI */ }

Don't add features, refactor other code, or "improve" beyond the test.

Verify GREEN — Run and Confirm Pass

npm test path/to/test.test.ts

Confirm: test passes, other tests still pass, output clean.

If test fails: fix code, not test. If other tests fail: fix now.

REFACTOR — Clean Up (Green Only)

Remove duplication, improve names, extract helpers. Keep tests green.

Repeat

Next failing test for next behavior.

Why Test-First Matters

Tests written after code pass immediately — proving nothing. You never see them catch the bug they're supposed to catch. Test-first forces you to see the failure, proving the test actually validates behavior.

Tests-after are biased by your implementation: you test what you built, not what's required. Tests-first force edge case discovery before implementing.

If the test is hard to write, the design is telling you something — the interface is too complex.

Good Tests

| Quality | Good | Bad | |---------|------|-----| | Minimal | One thing per test | test('validates email and domain and whitespace') | | Clear | Name describes behavior | test('test1') | | Shows intent | Demonstrates desired API | Obscures what code should do | | Real code | Tests actual behavior | Tests mock behavior |

When Stuck

| Problem | Solution | |---------|----------| | Don't know how to test | Write wished-for API. Write assertion first. | | Test too complicated | Design too complicated. Simplify interface. | | Must mock everything | Code too coupled. Use dependency injection. | | Test setup huge | Extract helpers. Still complex? Simplify design. |

Bug Fix Example

Bug: Empty email accepted

RED:

test("rejects empty email", async () => {
  const result = await submitForm({ email: "" });
  expect(result.error).toBe("Email required");
});

Verify RED: FAIL: expected 'Email required', got undefined

GREEN:

function submitForm(data: FormData) {
  if (!data.email?.trim()) {
    return { error: "Email required" };
  }
  // ...
}

Verify GREEN: PASS

REFACTOR: Extract validation for multiple fields if needed.

Verification Checklist

Before marking work complete:

[ ] Every new function has a test
[ ] Watched each test fail before implementing
[ ] Each test failed for expected reason (feature missing, not typo)
[ ] Wrote minimal code to pass each test
[ ] All tests pass, output clean
[ ] Tests use real code (mocks only if unavoidable)
[ ] Edge cases and errors covered

Integration

testing-anti-patterns — reviewing existing test quality
systematic-debugging — write failing test reproducing bug
verification-before-completion — verify tests pass before claiming done

Agent Skills: Test-Driven Development (TDD)

Install this agent skill to your local

Skill Files