tdd

name	tdd
description	Test-driven development — write the test first, watch it fail, write minimal code to pass

Test-Driven Development

Write the failing test first. Then make it pass. Then clean up. Every time.

Quick Reference

Field	Value
Scope	Any code change: new feature, bug fix, refactor
Input	Feature request, bug report, or function signature to implement
Output	Test file(s) + implementation, all tests green, no dead code
Cycle	RED → GREEN → REFACTOR (never skip a phase)
Core rule	You MUST NOT write production code without a failing test
Mocks	Mock only external I/O (network, filesystem, third-party APIs). All internal code uses real implementations.

The Cycle

RED — Write a Failing Test

1. One behavior per test. If the name needs "and", split it.
2. Name describes expected behavior, not implementation.
3. Run the test. It MUST fail (not error). Confirm:
   • Failure message matches your expectation.
   • It fails because the feature is missing, not because of a typo or import error.
4. If the test passes immediately, you are testing existing behavior — rewrite the test.

// RED: test for a function that doesn't exist yet
test("parsePort returns number for valid port string", () => {
  expect(parsePort("8080")).toBe(8080);
});

// Run → FAIL: parsePort is not defined
// Good: fails because the function is missing.
//
// BAD fail: "Cannot find module './parser'"
// That's an error, not a test failure. Fix the import first.

GREEN — Minimal Code to Pass

1. Write the simplest code that makes the failing test pass.
2. You MUST NOT add features, refactor, or "improve" beyond what the test demands.
3. Run all tests. They MUST all pass with clean output.
4. If the new test fails, fix the code — not the test.

// GREEN: minimal implementation — nothing extra
function parsePort(value: string): number {
  return Number(value);
}

// Run → PASS. Stop here. Don't add validation yet —
// no test demands it.

REFACTOR — Clean Up (Green Tests Only)

1. Remove duplication, improve names, extract helpers.
2. Keep all tests green. You MUST NOT add behavior during refactor.
3. Limit refactor scope to code touched in this cycle. Time-box: if it takes more than a few minutes, defer to a separate cycle.

// After adding a second test for invalid input and making it green,
// you notice duplication between parsePort and parseHost.
// REFACTOR: extract shared parsing logic.

// BEFORE (duplication)
function parsePort(v: string): number { return Number(v); }
function parseHost(v: string): string { return v.trim().toLowerCase(); }

// AFTER (shared helper, both tests still green)
function sanitize(v: string): string { return v.trim(); }
function parsePort(v: string): number { return Number(sanitize(v)); }
function parseHost(v: string): string { return sanitize(v).toLowerCase(); }

Bug Fix Flow

Bug reported → Write failing test that reproduces it → GREEN → REFACTOR

// Bug: parsePort("  8080  ") returns NaN instead of 8080.
// RED: write a test that exposes the bug
test("parsePort trims whitespace", () => {
  expect(parsePort("  8080  ")).toBe(8080);
});
// Run → FAIL: Expected 8080, received NaN. Good — bug reproduced.

// GREEN: fix the implementation
function parsePort(v: string): number {
  return Number(v.trim()); // ← minimal fix
}
// Run → PASS. Bug fixed. Test prevents regression.

MUST DO / MUST NOT DO

MUST DO	MUST NOT DO
Run the test and watch it fail before writing code	Write production code before a failing test exists
Confirm failure is for the expected reason	Ignore why a test failed (typo ≠ missing feature)
Write the simplest passing implementation	Add unrequested features during GREEN
Keep all tests green during REFACTOR	Add new behavior during REFACTOR
Use real implementations for internal code	Mock internal modules to avoid setup effort
Write one assertion per behavior	Stuff multiple behaviors into one test
Test edge cases and error paths	Test only the happy path

When Stuck

Problem	Solution
Don't know how to test it	Write the API you wish existed. Write the assertion first.
Test too complicated	Interface too complicated. Simplify the design.
Must mock everything	Code too coupled. Introduce dependency injection.
Test setup is huge	Extract test helpers. Still complex? Simplify the production design.
Can't find test files / runner	Check package.json scripts, look for existing *.test.* or *.spec.* files, match the project's conventions.

Verification Checklist

• Every new function/method has a test
• Each test was watched failing before implementation
• Each failure was for the expected reason
• All tests pass with clean output
• Mocks limited to external I/O only
• Edge cases and error paths covered
• No dead code or unrequested features added