Desenvolvimento Guiado por Testes

O que você leva

• Mudança entregue com teste automatizado que falhou antes, passou depois e documenta o comportamento esperado.
• Menos regressão e retrabalho ao testar o comportamento antes de mexer no código de produção.
• Problema: Times implementam primeiro e testam depois, gerando cobertura frágil, falsos positivos, bugs recorrentes e baixa confiança para refatorar.
• Fluxo: Planejar

Exemplo de pedido pronto

Quero corrigir um bug em uma função que aceita e-mail vazio. Me conduza por TDD antes de alterar o código.

Esta é uma das skills que a gente deixa aberta pra leitura. O arquivo abaixo é exatamente o que quem tem o catálogo completo recebe — entrada, passos, revisão e formato de saída. Use no seu assistente e adapte ao seu contexto.

---
name: "desenvolvimento-guiado-por-testes"
description: "Conduz features, correções e refatorações pelo ciclo TDD: teste vermelho, implementação mínima, teste verde e refatoração segura."
domain: "ENG"
function_verb: "PLANEJAR"
difficulty: "configure"
cost_profile: "s"
---

# Desenvolvimento Guiado por Testes

Skill para guiar uma mudança de software usando TDD de forma prática: primeiro um teste que falha pelo motivo certo, depois o menor código possível para passar, por fim refatoração segura e checklist antes do PR. Use como parte do pacote de qualidade/merge; não é um produto avulso.

## Quando Usar

- Nova feature com regra de negócio clara ou comportamento observável.
- Correção de bug que precisa virar teste de regressão.
- Refatoração em código com risco de quebrar comportamento existente.
- PRs críticos em checkout, Pix, boleto, login, permissões, emissão fiscal ou dados pessoais.
- Pareamento entre dev, QA e tech lead para reduzir regressão antes do merge.

Não force TDD quando o trabalho é apenas investigação exploratória, spike descartável, ajuste visual trivial ou configuração ainda sem critério testável. Nesses casos, proponha primeiro caracterização, checklist manual ou decisão do tech lead.

## Resultado Esperado

Entrega com: teste automatizado criado antes da mudança, evidência de que ele ficou vermelho pelo motivo correto, implementação mínima, suíte relevante verde, refatoração sem alterar comportamento e checklist pronto para PR.

## Entradas Necessarias

Peça ou confirme antes de sugerir código:
- Objetivo: feature, bugfix, refatoração ou teste de regressão.
- Stack e framework: Node/TypeScript, Python, PHP/Laravel, Java/Spring etc.
- Comando de teste: `npm test`, `pnpm test`, `pytest`, `php artisan test`, `vendor/bin/phpunit`, `mvn test`, `gradle test`.
- Arquivos ou módulos envolvidos e convenções de pasta.
- Comportamento esperado, caso atual, edge cases e critérios de aceite.
- Restrições: não chamar serviço externo, não mudar contrato público, manter compatibilidade, não tocar em migração.
- Se há dados sensíveis, use somente dados sintéticos.

## Processo

1. **Entender o comportamento**: transforme a demanda em uma frase testável: "quando X, deve Y". Se estiver ambíguo, pergunte antes.
2. **Escolher o nível de teste**: prefira unidade para regra pura; integração para banco, fila, controller ou contrato; end-to-end só quando o fluxo completo for o risco real.
3. **Escrever o teste vermelho**: proponha o menor teste que falha. Nome claro, arrange-act-assert, fixture sintética e poucos mocks. O teste deve validar comportamento observável, não apenas se um mock foi chamado.
4. **Validar a falha correta**: rode ou peça para rodar o teste específico. Se falhar por import, setup, fixture ou ambiente, corrija o teste antes de mexer no código de produção. Se passar de primeira, o teste não prova a regressão; revise o cenário.
5. **Implementar o mínimo**: altere somente o necessário para o teste passar. Evite reescrever arquitetura, generalizar regra ou apagar código fora do escopo.
6. **Validar verde**: rode o teste específico e, se viável, a suíte relacionada. Comandos comuns: `npm test -- arquivo.test.ts`, `pnpm vitest`, `pytest caminho/test_x.py`, `php artisan test --filter NomeDoTeste`, `mvn test -Dtest=ClasseTest`.
7. **Refatorar com segurança**: melhore nomes, duplicação e estrutura apenas com testes verdes. Após cada refatoração relevante, rode novamente a suíte impactada.
8. **Fechar PR**: registre o comportamento coberto, evidência vermelho/verde, riscos restantes e pontos para revisão humana.

## Ferramentas E Artefatos

Softwares comuns: VS Code, GitHub, GitLab, Bitbucket, Jira, Linear, Docker, GitHub Actions, GitLab CI. Frameworks: Jest, Vitest, Mocha, pytest, unittest, PHPUnit, Pest, JUnit, Maven, Gradle. Artefatos: arquivo de teste, fixture sintética, teste unitário, teste de integração, diff, relatório de execução, checklist de TDD e descrição de PR.

## Exemplo Brasileiro

Caso: API de cadastro aceita CPF inválido.

Fluxo esperado:
1. Criar teste com CPF fictício e inválido, por exemplo `12345678900`, esperando erro de validação.
2. Rodar só o teste novo e confirmar que falha porque a API aceitou o CPF, não por erro de setup.
3. Implementar validação mínima ou corrigir regra existente.
4. Rodar teste específico e testes de cadastro.
5. Abrir PR informando: "adicionado teste de regressão para CPF inválido; antes retornava 201, agora retorna 422".

Outros bons casos: webhook Pix idempotente que não pode duplicar pedido; cálculo de desconto no checkout; boleto vencido; campos obrigatórios para NFS-e. Em todos, use dados fictícios e não chame produção.

## Criterios De Qualidade

- O teste vem antes do código de produção.
- A falha vermelha é explicada e corresponde ao bug/comportamento esperado.
- O teste valida comportamento real, não só implementação interna ou mock.
- A implementação é mínima e limitada ao escopo.
- Comandos são adaptados à stack ou o agente pede confirmação.
- Não usa CPF, CNPJ, e-mail, telefone, token, chave Pix ou dados bancários reais.
- Inclui checklist final: vermelho confirmado, verde confirmado, refatoração feita ou dispensada, riscos e próximos testes.

## Cuidados, LGPD E Escalacao Humana

- Não copie dados reais de clientes, logs sensíveis, credenciais ou tokens para fixtures, snapshots ou mensagens de erro.
- Use dados sintéticos para CPF/CNPJ, e-mail, telefone, pedido, Pix, boleto e contas bancárias.
- Peça confirmação antes de apagar código, reestruturar pastas, alterar contrato público ou mudar teste de integração que chama serviço externo.
- Escale para tech lead/responsável quando afetar pagamento, fiscal, autenticação, autorização, segurança, LGPD ou regra regulatória.
- Não prometa certeza de ausência de bugs. Use linguagem de triagem, cobertura, evidência e revisão.
- Se o código já foi implementado, não finja TDD. Proponha teste de caracterização, teste de regressão ou reinício autorizado do ciclo.

## Smoke Test

Prompt: "Quero corrigir um bug em uma função que aceita e-mail vazio. Me conduza por TDD antes de alterar o código."

Resposta deve: pedir stack/comando se faltarem; propor teste vermelho para e-mail vazio; explicar a falha esperada; impedir alteração direta do código; sugerir implementação mínima só depois; finalizar com checklist vermelho/verde/refatoração/PR.