test-driven-development

Test-Driven Development

When to Use

• Implementing any new logic or behavior
• Fixing any bug (write a regression test first)
• Modifying existing functionality
• Adding edge case handling
• Any change that could break existing behavior

When NOT to use: Pure configuration changes, documentation updates, or static content changes that have no behavioral impact.

Related: For browser-based changes, combine TDD with runtime verification using Chrome DevTools MCP — see the Browser Testing section below.

The TDD Cycle

    RED                GREEN              REFACTOR
 Write a test    Write minimal code    Clean up the
 that fails  ──→  to make it pass  ──→  implementation  ──→  (repeat)
      │                  │                    │
      ▼                  ▼                    ▼
   Test FAILS        Test PASSES         Tests still PASS

Step 1: RED — Write a Failing Test

Write the test first. It must fail. A test that passes immediately proves nothing. RED also requires observing the test fail on its assertion, for the reason you expect — not merely that the test errors.

A test that fails only because a symbol/import is missing or the code doesn't compile is a weak RED: the assertion never ran, so it proves nothing about the behavior. Strong RED = the code exists and compiles, and the assertion fails because the behavior is wrong.

// Weak RED: fails only because createTask doesn't exist yet — the assertion never ran.
// Strong RED: this temporary stub compiles and reaches the assertion, but returns
// deliberately wrong behavior. GREEN replaces the stub with the real behavior.
class TaskService {
  async createTask(input: { title: string }) {
    return {
      id: 'stub',
      title: input.title,
      status: 'not-implemented',
      createdAt: new Date(0),
    };
  }
}

const taskService = new TaskService();

describe('TaskService', () => {
  it('creates a task with title and default status', async () => {
    const task = await taskService.createTask({ title: 'Buy groceries' });

    expect(task.id).toBeDefined();
    expect(task.title).toBe('Buy groceries');
    expect(task.status).toBe('pending');
    expect(task.createdAt).toBeInstanceOf(Date);
  });
});