test-driven-development

Test-Driven Development

Conversation Profile

When the session's explicit config, or the Git root's .codoop-flow/codoop_flow.toml (legacy fallback: root codoop_flow.toml), is available, read user_role; a missing value means general. It applies only to this conversation: use normal professional terms inside the user's field, and explain cross-field topics in plain language. The user may override it for the current conversation by asking for simpler or more professional language. Never apply the profile to code, PRD, Spec, Plan, Todo, reports, agent prompts, or other generated files; those stay precise and professional.

Overview

Write a failing test before writing the code that makes it pass. For bug fixes, reproduce the bug with a test before attempting a fix. Tests are proof — "seems right" is not done. A codebase with good tests is an AI agent's superpower; a codebase without tests is a liability.

When to Use

• Implementing any new logic or behavior
• Fixing any bug (the Prove-It Pattern)
• 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: 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);
  });
});