Test Guard

Você está revisando código de teste gerado ou alterado antes que ele seja enviado. Aplique as regras abaixo após a primeira passagem de escrita de testes e antes que os testes sejam apresentados, commitados ou mesclados. Seja um revisor perspicaz, não pedante: sinalize o que desperdiça esforço de manutenção ou esconde bugs reais, ignore preferências cosméticas.

Essas regras existem porque os agentes de codificação geram testes em excesso. As falhas comuns: testes unitários com muitos mocks que afirmam detalhes de implementação, corpos de teste quase duplicados que diferem por um valor e testes que reconfirmam o framework em vez da lógica do projeto. Cada um parece produtivo em um diff e custa manutenção para sempre.

Quando Usar

Use esta habilidade ao revisar código de teste gerado ou alterado antes que ele seja enviado. Ative-a reativamente após um agente escrever, editar, gerar ou refatorar testes — testes unitários, testes de integração, testes e2e ou testes de snapshot em qualquer framework.

Quando esta habilidade é ativada

• Um agente de codificação acabou de escrever novas funções de teste ou arquivos de teste, em qualquer idioma
• Você está editando testes existentes
• Você está revisando um diff que contém alterações de teste
• O usuário pede para você escrever, adicionar ou revisar testes

Adapte-se ao projeto primeiro

Essas regras são universais, mas sua aplicação não é. Antes de revisar:

1. Verifique as instruções do agente do projeto (CLAUDE.md, AGENTS.md) e a documentação de testes. Regras de teste específicas do projeto prevalecem sobre esta habilidade quando entram em conflito.
2. Identifique a stack de testes e, em seguida, leia a referência correspondente para padrões concretos:
   • Python / pytest → references/pytest.md
   • PHP / PHPUnit / Pest / WordPress → references/phpunit.md
   • JavaScript / TypeScript / Jest / Vitest → references/jest.md
3. Se o projeto chama APIs LLM, usa frameworks de agente ou configura observabilidade/telemetria, leia também references/llm-app-testing.md — ele adiciona três regras específicas para aplicações LLM.
4. Mapeie os limites do sistema do projeto: chamadas de rede, bancos de dados, sistema de arquivos, relógio e aleatoriedade, SDKs de terceiros, APIs LLM. Fixtures e helpers de teste existentes geralmente revelam onde o projeto já traça essas linhas.

O que fazer

1. Leia o código de teste: o diff, o novo arquivo ou a seção que está sendo modificada.
2. Verifique cada teste em relação às regras abaixo.
3. Relate violações de forma concisa: número da regra, local, por que viola, sugestão de correção.
4. Se o usuário invocar explicitamente esta habilidade antes da escrita de testes, aplique as regras enquanto escreve — não escreva violações e depois as sinalize.

Ao escrever novos testes, pergunte para cada teste: "Que bug específico este teste captura que nenhum outro teste nesta suíte captura?" Se você não conseguir responder claramente, não o escreva.

As Nove Regras

Regra 1: Teste o comportamento, não a implementação

Teste o que o código faz da perspectiva do chamador. Afirme valores de retorno e efeitos colaterais observáveis. Nunca afirme que um helper interno foi chamado com argumentos específicos — esse teste falha em cada refatoração enquanto não captura nada.

Padrão de violação: afirmar que um mock de uma função interna foi chamado, onde essa função não é um limite do sistema. Correção: afirme o valor de retorno ou a mudança de estado que o chamador observa.

Regra 2: Todo mock deve ser justificado

Mock apenas em limites do sistema: chamadas de rede e HTTP, APIs LLM, bancos de dados, I/O de sistema de arquivos em arquivos externos, relógio e aleatoriedade, SDKs de terceiros. Nunca mock classes internas ou funções helper para isolar uma "unidade" — as emendas que você cria escondem os bugs de integração que valem a pena capturar.

Ao mockar um limite, afirme o que o chamador faz com a resposta, não que o mock recebeu argumentos específicos.

Regra 3: Um cenário por teste, orientado a dados para variantes

Se dois ou mais testes compartilham configuração idêntica e diferem apenas em valores de entrada/saída, mescle-os em um teste orientado a dados (@pytest.mark.parametrize, PHPUnit #[DataProvider], Jest test.each).

Quando testes separados SÃO corretos: configuração diferente, asserções diferentes, configurações de mock diferentes ou cenários genuinamente diferentes que por acaso exercitam a mesma função.

Regra 4: Todo teste deve justificar sua existência

Pergunte: "Que bug este teste captura que nenhum outro teste captura?" Exclua testes que apenas capturam erros de digitação, verificam valores padrão de classes de dados ou testam lógica trivial de passagem.

…