Test-Driven Development

Test-Driven Development (TDD)

The Fundamental Rule

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.

This is non-negotiable. Code written before tests must be deleted and rewritten with tests first.

Why TDD Matters

Testing after implementation provides false confidence:

• Tests pass immediately (proves nothing)
• No verification that tests catch regressions
• Untested edge cases slip through

TDD ensures every line of production code is proven necessary by a failing test.

The RED-GREEN-REFACTOR Cycle

1. RED - Write a Failing Test

// Write the test FIRST
describe('calculateTotal', () => {
  it('should sum items with tax', () => {
    const items = [{ price: 100 }, { price: 50 }];
    const result = calculateTotal(items, 0.08);
    expect(result).toBe(162); // 150 + 12 tax
  });
});

Run the test. It MUST fail. If it passes, you're testing existing code (wrong).

2. Verify RED

Confirm failure is for the right reason:

• ✅ "calculateTotal is not defined" - Correct, function doesn't exist
• ❌ "SyntaxError in test file" - Fix test, not production code

3. GREEN - Minimal Implementation

Write the simplest code that makes the test pass:

function calculateTotal(items: Item[], taxRate: number): number {
  const subtotal = items.reduce((sum, item) => sum + item.price, 0);
  return subtotal + (subtotal * taxRate);
}

4. Verify GREEN

• All tests pass
• No regressions introduced
• Coverage increased

5. REFACTOR

Improve code quality while keeping tests green:

• Extract functions
• Rename for clarity
• Remove duplication
• Improve performance

Common Rationalizations (Reject All)

Red Flags - Stop Immediately

• Writing code before tests
• Tests passing on first run
• Any "just this once" rationalization
• Skipping the verify steps

FrankX Application

For Next.js Components

// 1. RED - Write test first
describe('EmailSignup', () => {
  it('should show error for invalid email', async () => {
    render(<EmailSignup />);
    await userEvent.type(screen.getByRole('textbox'), 'invalid');
    await userEvent.click(screen.getByRole('button'));
    expect(screen.getByText(/invalid email/i)).toBeInTheDocument();
  });
});

// 2. GREEN - Implement component
// 3. REFACTOR - Clean up

For API Routes

// 1. RED
describe('POST /api/subscribe', () => {
  it('should return 400 for invalid email', async () => {
    const response = await POST({ json: () => ({ email: 'bad' }) });
    expect(response.status).toBe(400);
  });
});

// 2. GREEN - Implement route
// 3. REFACTOR

Test File Organization

project/
├── app/
│   └── api/
│       └── subscribe/
│           └── route.ts
├── tests/
│   ├── unit/           # Fast, isolated tests
│   │   └── api/
│   │       └── subscribe.test.ts
│   ├── integration/    # Cross-component tests
│   └── e2e/           # Playwright tests
│       └── subscribe.spec.ts

Commands

# Run tests in watch mode
npm test -- --watch

# Run specific test file
npm test -- api/subscribe.test.ts

# Run with coverage
npm test -- --coverage

When to Use This Skill

• Writing any new feature
• Fixing bugs (write failing test FIRST)
• Refactoring (ensure tests exist)
• Code reviews (verify TDD was followed)

Related Skills

• systematic-debugging - When tests reveal bugs
• webapp-testing - For Playwright e2e tests
• implementation-planning - Plans include TDD steps