Tdd

TDD — Test-Driven Development

Write tests first. The tests define the contract; the code fulfills it.

Core principle: Tests are not a safety net for code. Tests are the specification. Code is the implementation of the spec.

When to Use

• Writing any non-trivial function or module
• Fixing a bug (Prove-It Pattern)
• Defining the behavior of a new API or interface
• Verifying test quality with mutation testing

When NOT to Use

• End-to-end browser automation (use e2e-testing skill)
• Integration tests hitting real databases (use e2e-testing skill)
• Exploratory spikes (write the spike, then delete and TDD the real implementation)

RED-GREEN-REFACTOR

The canonical cycle. Do not skip or combine steps.

RED — Write a Failing Test

// Write the test FIRST. It must fail (RED).
it('returns null when user not found', async () => {
  const repo = new InMemoryUserRepository([]);
  const result = await repo.findById('nonexistent-id');
  expect(result).toBeNull();
});

Verify it fails for the RIGHT reason — the failure message should indicate the feature is missing, not a syntax error or import problem.

GREEN — Write Minimum Code to Pass

// Write the MINIMUM code to make the test pass.
// Not the correct code — the minimum code.
async findById(id: string): Promise<User | null> {
  return this.users.find(u => u.id === id) ?? null;
}

If you wrote code before writing the test: delete it. Start over. There are no exceptions.

REFACTOR — Improve Structure (Tests Still Green)

// Clean up now that the behavior is locked in by tests.
// Tests run after every change. If they go red: revert the refactor.
async findById(id: UserId): Promise<User | null> {
  return this.users.find(u => u.id === id) ?? null;
}

The Prove-It Pattern (Bug Fixes)

Every bug fix starts with a test that reproduces the bug:

1. Write a test that demonstrates the bug (it must fail — RED)
2. Verify the test fails for the right reason (bug, not test error)
3. Fix the code (GREEN)
4. Verify the test passes
5. Run full test suite — no regressions

NEVER fix a bug without a test first.
If you "fix" it without a test, the bug will return.

Test Pyramid

Most tests should be unit tests. E2E tests are expensive and brittle — use sparingly for critical paths only.

Mocks vs Stubs vs Fakes

// Stub: fixed return value
const emailService = { send: jest.fn().mockResolvedValue(undefined) };

// Mock: verifies the call happened
expect(emailService.send).toHaveBeenCalledWith(
  'user@example.com',
  'Task created'
);

// Fake: realistic in-memory implementation
class InMemoryTaskRepository implements TaskRepository {
  private tasks: Task[] = [];
  async save(task: Task) { this.tasks.push(task); }
  async findById(id: string) { return this.tasks.find(t => t.id === id) ?? null; }
}

Rule — Mock at Boundaries Only:

Mock at the boundary of your system. Never mock your own domain objects.

Test Structure (AAA Pattern)

Test naming: [unit] should [behavior] when [condition] Examples: createUser should throw when email is duplicate, calculateTax should return 0 when subtotal is 0

it('calculateTax should return 8.00 when subtotal is 100 and rate is 8%', () => {
  // Arrange
  const subtotal = 100.00;
  const taxRate = 0.08;

  // Act
  const tax = calculateTax(subtotal, taxRate);

  // Assert
  expect(tax).toBeCloseTo(8.00, 2);
});

Each test: one behavior, one assertion cluster. If the test name contains "and", split it.

Test Coverage Requirements

Coverage is a floor, not a goal. 90% coverage with weak tests is worse than 70% with strong tests.

Mutation Testing

Verify that your tests actually catch bugs:

# Install and run stryker (JavaScript)
npx stryker run

# Or jest-mutating
npx jest-mutating --testPathPattern="src/domain/**"

Mutation score: % of inserted bugs caught by tests. Target >70%.

If a mutant survives (test didn't catch the bug), either:

1. Add a test case that would fail with the mutant
2. Accept the gap (not all code paths need testing)

Common Mistakes

Verification Checklist

• Tests written BEFORE production code (RED seen for each test)
• Each test: one behavior, descriptive name (does X when Y)
• Happy path, empty/null, boundary, and error cases covered
• Fakes used for repositories; mocks only for verified side effects
• AAA structure in each test (Arrange, Act, Assert)
• No test depends on another test (order-independent)
• Mutation score >70% for business logic
• Bug fixes include a reproducing test (Prove-It Pattern)
• Full test suite green after refactor step