Desenvolvimento Orientado por Testes (TDD)
Idioma de Saída
Por padrão, use chinês simplificado para se comunicar com o usuário e para escrever a estratégia de teste, descrições de teste e resumo da implementação. Quando o usuário especificar explicitamente outro idioma ou a documentação existente tiver uma convenção diferente, siga essa convenção; código, comandos, nomes de produtos e citações que devam permanecer no original não devem ser traduzidos à força.
Filosofia
Princípio central: Os testes devem verificar o comportamento por meio de interfaces públicas, não de detalhes de implementação. O código pode mudar completamente; os testes não deveriam.
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 parece 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.
Testes ruins são acoplados à implementação. Eles simulam colaboradores internos, testam métodos privados ou verificam por meios externos (como consultar um banco de dados diretamente em vez de usar a interface). O sinal de alerta: seu teste quebra 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.
Antipadrão: Fatias Horizontais
NÃO escreva todos os testes primeiro, depois toda a implementação. Isso é "fatia horizontal" – tratar VERMELHO como "escrever todos os testes" e VERDE como "escrever todo o código".
Isso produz testes de baixa qualidade:
- Testes escritos em lote testam um comportamento imaginado, não real
- Você acaba testando a forma das coisas (estruturas de dados, assinaturas de funções) em vez do comportamento voltado ao usuário
- Os testes se tornam insensíveis a mudanças reais – passam quando o comportamento quebra, falham quando o comportamento está correto
- Você ultrapassa seus faróis, comprometendo-se com uma estrutura de teste antes de entender a implementação
Abordagem correta: Fatias verticais por meio de balas traçadoras. 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 importa e como verificá-lo.
ERRADO (horizontal):
VERMELHO: test1, test2, test3, test4, test5
VERDE: impl1, impl2, impl3, impl4, impl5
CERTO (vertical):
VERMELHO→VERDE: test1→impl1
VERMELHO→VERDE: test2→impl2
VERMELHO→VERDE: test3→impl3
...
Fluxo de Trabalho
1. Planejamento
Ao explorar a base de código, leia o arquivo CONTEXT.md (se existir) para que os nomes dos testes e o vocabulário da interface correspondam ao 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 mudanças na interface são necessárias
- Confirme com o usuário quais comportamentos testar (priorize)
- Identifique oportunidades para módulos profundos usando princípios de design de base de código quando os limites da interface não estiverem claros. Não invoque outra skill automaticamente a menos que o usuário peça explicitamente.
- Liste os comportamentos a testar (não etapas de implementação)
- Obtenha aprovação do usuário sobre o 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. Bala Traçadora
Escreva UM teste que confirme UMA coisa sobre o sistema:
VERMELHO: Escreva o teste para o primeiro comportamento → teste falha
VERDE: Escreva o código mínimo para passar → teste passa
Esta é sua bala traçadora – prova que o caminho funciona de ponta a ponta.
3. Loop Incremental
Para cada comportamento restante:
VERMELHO: Escreva o próximo teste → falha
VERDE: Código mínimo para passar → passa
Regras:
- Um teste de cada vez
- Apenas código suficiente para passar no teste atual
- Não antecipe testes futuros
- Mantenha os testes focados no comportamento observável
4. Refatoração
Após todos os testes passarem, procure por candidatos a refatoração:
- Extraia duplicação
- Aprofunde módulos (mova complexidade para trás de interfaces simples)
- Aplique 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. Alcance o VERDE primeiro.
Lista de Verificação por Ciclo
[ ] O teste descreve comportamento, não implementação
[ ] O teste usa apenas a interface pública
[ ] O teste sobreviveria a uma refatoração interna
[ ] O código é mínimo para este teste
[ ] Nenhum recurso especulativo adicionado