Test-Driven Development

Quando Usar

Use quando este fluxo de trabalho corresponder à solicitação do usuário: Use esta habilidade para seu fluxo de trabalho documentado.

Fonte: mattpocock/skills (MIT).

Filosofia

Princípio central: Testes devem verificar o comportamento através de interfaces públicas, não de detalhes de implementação. O código pode mudar completamente; os testes não devem.

Bons testes são do tipo integração: eles exercitam caminhos de código reais através de APIs públicas. Eles descrevem o que o sistema faz, não como ele faz. Um bom teste soa como uma especificação - "o usuário pode finalizar a compra com um carrinho válido" informa exatamente qual capacidade existe. Esses testes sobrevivem a refatorações porque não se importam com a estrutura interna.

Maus testes estão acoplados à implementação. Eles simulam colaboradores internos, testam métodos privados ou verificam através de meios externos (como consultar um banco de dados diretamente em vez de usar a interface). O sinal de alerta: seu teste falha quando você refatora, mas o comportamento não mudou. Se você renomear uma função interna e os testes falharem, esses testes estavam testando a implementação, não o comportamento.

Veja tests.md para exemplos e mocking.md para diretrizes de simulação.

Anti-Padrão: Fatias Horizontais

NÃO escreva todos os testes primeiro, depois toda a implementação. Isso é "fatiamento horizontal" - tratar VERMELHO como "escrever todos os testes" e VERDE como "escrever todo o código".

Isso produz testes de má qualidade:

• Testes escritos em massa testam comportamento imaginado, não comportamento real
• Você acaba testando a forma das coisas (estruturas de dados, assinaturas de funções) em vez do comportamento voltado para o usuário
• Testes se tornam insensíveis a mudanças reais - eles passam quando o comportamento falha, falham quando o comportamento está bom
• Você corre mais rápido do que seus faróis, comprometendo-se com a estrutura de teste antes de entender a implementação

Abordagem correta: Fatias verticais via "tracer bullets". Um teste → uma implementação → repita. Cada teste responde ao que você aprendeu no ciclo anterior. Como você acabou de escrever o código, sabe exatamente qual comportamento é importante e como verificá-lo.

WRONG (horizontal):
  RED:   test1, test2, test3, test4, test5
  GREEN: impl1, impl2, impl3, impl4, impl5

RIGHT (vertical):
  RED→GREEN: test1→impl1
  RED→GREEN: test2→impl2
  RED→GREEN: test3→impl3
  ...

Fluxo de Trabalho

1. Planejamento

Ao explorar a base de código, leia CONTEXT.md (se existir) para que os nomes dos testes e o vocabulário da interface correspondam à linguagem de domínio do projeto, e respeite os ADRs na área que você está tocando.

Antes de escrever qualquer código:

• Confirme com o usuário quais alterações na interface são necessárias
• Confirme com o usuário quais comportamentos testar (priorize)
• Identifique oportunidades para módulos profundos (interface pequena, implementação profunda) — execute a habilidade /codebase-design para o vocabulário e as verificações de testabilidade
• Liste os comportamentos a serem testados (não os passos de implementação)
• Obtenha a aprovação do usuário no plano

Pergunte: "Como deve ser a interface pública? Quais comportamentos são mais importantes de testar?"

Você não pode testar tudo. Confirme com o usuário exatamente quais comportamentos são mais importantes. Concentre o esforço de teste em caminhos críticos e lógica complexa, não em todos os casos de borda possíveis.

2. Tracer Bullet

Escreva UM teste que confirme UMA coisa sobre o sistema:

RED:   Write test for first behavior → test fails
GREEN: Write minimal code to pass → test passes

Este é o seu "tracer bullet" - prova que o caminho funciona de ponta a ponta.

3. Loop Incremental

Para cada comportamento restante:

RED:   Write next test → fails
GREEN: Minimal code to pass → passes

Regras:

• Um teste por vez
• Apenas código suficiente para passar no teste atual
• Não antecipe testes futuros
• Mantenha os testes focados no comportamento observável

4. Refatorar

Após todos os testes passarem, procure por candidatos à refatoração:

• Extrair duplicação
• Aprofundar módulos (mover complexidade para trás de interfaces simples)
• Aplicar princípios SOLID onde for natural
• Considere o que o novo código revela sobre o código existente
• Execute os testes após cada etapa de refatoração

Nunca refatore enquanto estiver VERMELHO. Chegue ao VERDE primeiro.

Checklist Por Ciclo

[ ] Test describes behavior, not implementation
[ ] Test uses public interface only
[ ] Test would survive internal refactor
[ ] Code is minimal for this test
[ ] No speculative features added

Limitações

• Requer a ferramenta upstream, conta, chave de API ou configuração local quando o fluxo de trabalho nomeia um.

…