Desenvolvimento Guiado por Testes

Visão Geral

Escreva um teste que falha antes de escrever o código que o faz passar. Para correções de bugs, reproduza o bug com um teste antes de tentar corrigi-lo. Testes são provas — "parece certo" não é feito. Uma base de código com bons testes é um superpoder para um agente de IA; uma base de código sem testes é um passivo.

Quando Usar

• Implementando qualquer nova lógica ou comportamento
• Corrigindo qualquer bug (o Padrão Prove-It)
• Modificando funcionalidade existente
• Adicionando tratamento de casos extremos
• Qualquer alteração que possa quebrar o comportamento existente

Quando NÃO usar: Mudanças puramente de configuração, atualizações de documentação ou mudanças de conteúdo estático que não tenham impacto comportamental.

Relacionado: Para mudanças baseadas em navegador, combine TDD com verificação em tempo de execução usando Chrome DevTools MCP — veja a seção Testes de Navegador abaixo.

Descubra a Stack Primeiro

O ciclo TDD é universal; os comandos não são. Antes de escrever o primeiro teste, descubra como este repositório testa e use seus comandos para cada etapa RED, GREEN e de verificação:

• Linguagem e sistema de build — package.json, pom.xml/build.gradle, pyproject.toml, go.mod, Cargo.toml, Gemfile, um Makefile
• Wrappers registrados — prefira ./gradlew, ./mvnw, make test, ou um script de repositório em vez de ferramentas instaladas globalmente
• Framework de teste e configuração — e como ele executa um único teste focado versus o conjunto completo
• Convenções existentes — onde os testes residem, como os arquivos são nomeados, quais padrões os testes vizinhos seguem
• Comandos documentados — README, CONTRIBUTING e fluxos de trabalho de CI mostram os comandos que realmente controlam as mesclagens

Execute o comando de teste focado do repositório durante o loop e seu comando de conjunto completo antes da conclusão. Nunca assuma um padrão como npm test — um projeto Gradle, Cargo ou pytest tem seu próprio equivalente.

Os exemplos abaixo usam TypeScript para ilustração; o fluxo de trabalho é idêntico em qualquer linguagem depois que você descobrir as ferramentas próprias do projeto.

O Ciclo TDD

    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

Etapa 1: RED — Escreva um Teste que Falha

Escreva o teste primeiro. Ele deve falhar. Um teste que passa imediatamente não prova nada.

// 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);
  });
});

Etapa 2: GREEN — Faça Passar

Escreva o código mínimo para fazer o teste passar. Não exagere na engenharia:

// 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;
}

Etapa 3: REFACTOR — Limpe

Com os testes verdes, melhore o código sem alterar o comportamento:

• Extraia lógica compartilhada
• Melhore a nomenclatura
• Remova duplicação
• Otimize se necessário

Execute os testes após cada etapa de refatoração para confirmar que nada quebrou.

O Padrão Prove-It (Correções de Bugs)

Quando um bug é relatado, não comece tentando corrigi-lo. Comece escrevendo um teste que o reproduza.

Bug report arrives
       │
       ▼
  Write a test that demonstrates the bug
       │
       ▼
  Test FAILS (confirming the bug exists)
       │
       ▼
  Implement the fix
       │
       ▼
  Test PASSES (proving the fix works)
       │
       ▼
  Run full test suite (no regressions)

Exemplo:

// Bug: "Completar uma tarefa não atualiza o timestamp completedAt"

// Etapa 1: Escreva o teste de reprodução (ele deve FALHAR)
it('define completedAt quando a tarefa é completada', 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);  // Isso falha → bug confirmado
});

// Etapa 2: Corrija o bug

…