Testes Unitários e de Integração Automatizados
Nesta página
Automatizar a Escrita de Testes
Os testes são a primeira coisa que se corta quando o tempo aperta, mas são a dívida técnica mais cara a pagar mais tarde. O Codex altera esta equação: gerar cobertura total para um módulo passa de uma tarde de trabalho para alguns minutos. No entanto, deve pedir mais do que apenas «escrever testes», uma instrução que gera apenas alguns casos nominais — verdes, tranquilizadores e inúteis.
Gerar Testes Unitários
A principal alavanca é definir você mesmo os casos limite. Você conhece o seu domínio de negócio; o agente não sabe que um desconto superior a 100% ocorre apenas uma vez por trimestre nos seus dados.
"Generate unit tests for src/lib/pricing.ts.
Use Vitest. Cover all edge cases: negative price,
discount > 100%, invalid currency, zero quantity."
O Codex analisa o código-fonte, identifica as funções exportadas, compreende a sua lógica e produz depois um conjunto de testes que cobre tanto os caminhos normais como os casos que citou.
// src/lib/pricing.test.ts
import { describe, it, expect } from "vitest";
import { calculatePrice, applyDiscount, formatPrice } from "./pricing";
describe("calculatePrice", () => {
it("calculates total price for a positive quantity", () => {
expect(calculatePrice(10, 3)).toBe(30);
});
it("returns 0 for a quantity of zero", () => {
expect(calculatePrice(10, 0)).toBe(0);
});
it("throws an error for a negative price", () => {
expect(() => calculatePrice(-5, 1)).toThrow("Invalid price");
});
});
describe("applyDiscount", () => {
it("applies a standard discount", () => {
expect(applyDiscount(100, 20)).toBe(80);
});
it("rejects a discount greater than 100%", () => {
expect(() => applyDiscount(100, 150)).toThrow();
});
});
Um detalhe merece inspeção: a mensagem de erro esperada, «Invalid price», foi extraída da implementação real, não foi inventada. Esta é a assinatura de um teste escrito a partir do código e não de um modelo, sendo a primeira coisa a verificar ao rever um conjunto de testes gerado.
Gerar Testes de Integração
Para uma rota de API ou um serviço que acede à base de dados, precisa de fornecer mais contexto, especialmente sobre o que deve ser simulado (mock).
"Generate integration tests for src/api/routes/orders.ts.
Use supertest for HTTP requests. Mock the Stripe
service with vi.mock. Test scenarios: order creation,
order with non-existent product, failed payment."
O Codex distingue claramente entre os dois níveis de teste: configura os mocks apropriados, gere a configuração e limpeza da base de dados de teste e simula serviços externos. Nomear explicitamente o Stripe e o supertest impede que ele invente uma infraestrutura paralela à que a sua equipa já utiliza.
Cobrir um Projeto Inteiro
Num projeto estruturalmente carente de testes, uma tarefa global é mais eficaz do que uma série de pedidos ficheiro por ficheiro.
"Analyze all .ts files in src/lib/ and src/services/.
For each file without a corresponding .test.ts file,
generate unit tests. Aim for branch coverage > 80%."
O Codex processa então os ficheiros um a um, adaptando os testes a cada módulo; conte com vários minutos de execução para um conjunto completo. Execute esta tarefa numa pasta de cada vez, em vez de em todo o diretório src/: além desse limite, o pull request torna-se demasiado grande para ser revisto, e um conjunto de testes aprovado sem leitura não protege ninguém.
Melhorar Testes Existentes
O Codex não cria apenas; pode também diagnosticar um conjunto de testes que tranquiliza sem proteger.
"Analyze tests in src/__tests__/. Identify:
- Tests that check only one path (happy path)
- Vague assertions (toBeTruthy instead of toBe)
- Tests that share mutable state
Fix these issues."
Estes três sintomas explicam a maioria dos conjuntos de testes «verdes» que deixam passar erros. O terceiro é o mais insidioso: testes que partilham estado mutável passam enquanto forem executados na ordem habitual, e começam a falhar aleatoriamente no dia em que ativa a paralelização.
Testes por Tipo de Componente
O tipo de teste a solicitar depende diretamente da natureza do código, e a instrução muda em conformidade.
| Tipo de Código | Tipo de Teste | Instrução para o Codex |
|---|---|---|
| Função utilitária | Unitário | «Testar todas as entradas e saídas possíveis» |
| Rota de API | Integração | «Testar com supertest, simular serviços externos» |
| Componente React | Renderização | «Testar renderização e interações com Testing Library» |
| Serviço com BD | Integração | «Usar uma BD de teste, reiniciar entre cada teste» |
Configurar AGENTS.md para Testes
Em vez de repetir estas escolhas para cada tarefa, escreva-as uma vez por todas numa secção dedicada do AGENTS.md.
## Tests
- Framework: Vitest
- Command: `npm run test`
- Coverage: `npm run test:coverage`
- Convention: .test.ts files next to source code
- Mocks: use vi.mock(), no manual mocks
- Assertions: prefer toBe/toEqual over toBeTruthy/toBeFalsy
- Each test must be independent (no shared state)
Com estas sete linhas, o Codex aplica as suas convenções a todos os testes que gera, mesmo quando um programador apressado formula o seu pedido em três palavras. Esta é a forma mais económica de tornar a qualidade dos seus testes independente da qualidade das instruções.
Pontos-chave
- O Codex gera testes adaptados ao seu código, não testes genéricos
- Especifique os casos limite que deseja cobrir nas suas instruções
- O Codex distingue entre testes unitários e de integração
- Utilize o AGENTS.md para definir as suas convenções de teste
- O Codex pode melhorar testes existentes, não apenas criar novos