Test-Driven Development

Write a failing test before writing the code that makes it pass. Tests are proof — "seems right" is not done.

When to Use

• Implementing any new logic or behavior
• Fixing any bug (the Prove-It Pattern)
• Modifying existing functionality
• Adding edge case handling

When NOT to use: Pure configuration changes, documentation updates, or static content changes.

The TDD Cycle

    RED                GREEN              REFACTOR
 Write a test    Write minimal code    Clean up the
 that fails  ──→  to make it pass  ──→  implementation

Step 1: RED — Write a Failing Test

// RED: This test fails because createTask doesn't exist yet
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);
  });
});

Step 2: GREEN — Make It Pass

// GREEN: Minimal implementation
export async function createTask(input: { title: string }): Promise<Task> {
  const task = {
    id: generateId(),
    title: input.title,
    status: 'pending' as const,
    createdAt: new Date(),
  };
  await db.tasks.insert(task);
  return task;
}

Step 3: REFACTOR — Clean Up

With tests green, improve the code without changing behavior:

• Extract shared logic
• Improve naming
• Remove duplication
• Optimize if necessary

The Prove-It Pattern (Bug Fixes)

When a bug is reported, do not start by trying to fix it. Start by writing a test that reproduces it.

// Step 1: Write the reproduction test (it should FAIL)
it('sets completedAt when task is completed', async () => {
  const task = await taskService.createTask({ title: 'Test' });
  const completed = await taskService.completeTask(task.id);

  expect(completed.status).toBe('completed');
  expect(completed.completedAt).toBeInstanceOf(Date);  // This fails → bug confirmed
});

// Step 2: Fix the bug
export async function completeTask(id: string): Promise<Task> {
  return db.tasks.update(id, {
    status: 'completed',
    completedAt: new Date(),  // This was missing
  });
}

// Step 3: Test passes → bug fixed, regression guarded

The Test Pyramid

Invest testing effort according to the pyramid:

          ╱╲
         ╱  ╲         E2E Tests (~5%)
        ╱    ╲        Full user flows, real browser
       ╱──────╲
      ╱        ╲      Integration Tests (~15%)
     ╱          ╲     Component interactions, API boundaries
    ╱────────────╲
   ╱              ╲   Unit Tests (~80%)
  ╱                ╲  Pure logic, isolated, milliseconds each
 ╱──────────────────╲

Test Sizes

| Size | Constraints | Speed | Example | |------|------------|-------|---------| | Small | Single process, no I/O, no network | Milliseconds | Pure function tests | | Medium | Multi-process OK, localhost only | Seconds | API tests with test DB | | Large | Multi-machine OK, external services | Minutes | E2E tests |

Writing Good Tests

Test State, Not Interactions

// Good: Tests what the function does (state-based)
it('returns tasks sorted by creation date', async () => {
  const tasks = await listTasks({ sortBy: 'createdAt', sortOrder: 'desc' });
  expect(tasks[0].createdAt.getTime())
    .toBeGreaterThan(tasks[1].createdAt.getTime());
});

// Bad: Tests how the function works internally
it('calls db.query with ORDER BY created_at DESC', async () => {
  await listTasks({ sortBy: 'createdAt', sortOrder: 'desc' });
  expect(db.query).toHaveBeenCalledWith(
    expect.stringContaining('ORDER BY created_at DESC')
  );
});

DAMP Over DRY in Tests

In tests, DAMP (Descriptive And Meaningful Phrases) is better than DRY. Each test should tell a complete story.

// DAMP: Each test is self-contained and readable
it('rejects tasks with empty titles', () => {
  const input = { title: '', assignee: 'user-1' };
  expect(() => createTask(input)).toThrow('Title is required');
});

it('trims whitespace from titles', () => {
  const input = { title: '  Buy groceries  ', assignee: 'user-1' };
  const task = createTask(input);
  expect(task.title).toBe('Buy groceries');
});

Prefer Real Implementations Over Mocks

Preference order (most to least preferred):
1. Real implementation  → Highest confidence
2. Fake                 → In-memory version
3. Stub                 → Returns canned data
4. Mock (interaction)   → Verifies method calls — use sparingly

Use Arrange-Act-Assert Pattern

it('marks overdue tasks when deadline has passed', () => {
  // Arrange: Set up the test scenario
  const task = createTask({
    title: 'Test',
    deadline: new Date('2025-01-01'),
  });

  // Act: Perform the action being tested
  const result = checkOverdue(task, new Date('2025-01-02'));

  // Assert: Verify the outcome
  expect(result.isOverdue).toBe(true);
});

Test Anti-Patterns to Avoid

| Anti-Pattern | Problem | Fix | |---|---|---| | Testing implementation details | Tests break when refactoring | Test inputs and outputs | | Flaky tests | Erode trust in the suite | Use deterministic assertions | | Testing framework code | Wastes time | Only test YOUR code | | Snapshot abuse | Large snapshots nobody reviews | Use sparingly and review | | No test isolation | Tests fail together | Each test sets up its own state | | Mocking everything | Tests pass but production breaks | Prefer real implementations |

Verification

After completing any implementation:

• [ ] Every new behavior has a corresponding test
• [ ] All tests pass: npm test
• [ ] Bug fixes include a reproduction test
• [ ] Test names describe the behavior being verified
• [ ] No tests were skipped or disabled
• [ ] Coverage hasn't decreased (if tracked)