Melhores Práticas de Teste

Regras que mantêm as suítes de teste da API Node rápidas, confiáveis e focadas no comportamento observável.

Como Usar Esta Lista

• Aplique ao adicionar o primeiro teste a um novo serviço.
• Revise durante PRs que adicionam mocks ou infraestrutura de integração.
• Aplique via CI (requer npm test, job de integração separado).

A - Design de Teste

• Teste o comportamento, não a implementação privada. Afirme o status HTTP, o JSON retornado e os efeitos colaterais - não a ordem de chamada interna.
• Siga a pirâmide: muitas unidades, menos integrações, raras E2E. A maioria dos testes conclui em milissegundos.
• Nomeie testes como especificações. retorna 409 quando a fatura já está paga é melhor que teste1.
• Um foco principal de asserção por teste. Múltiplas asserções OK ao verificar um resultado de comportamento.
• Casos orientados por tabela para variações de entrada. Cubra casos extremos sem testes de copiar e colar.

B - Estrutura de HTTP e Aplicativo

• Exporte createApp() sem auto-listen. Supertest e Fastify inject precisam de aplicativos em processo.
• Cubra caminhos de erro: manipuladores 400, 401, 404, 409, 500. Suítes apenas de caminho feliz perdem regressões.
• Use Supertest ou Fastify inject, não portas aleatórias. Evite EADDRINUSE e CI instável.
• Não acesse URLs de produção em testes. Apenas staging ou em processo.
• Congele o tempo ao testar a lógica de TTL/expiração. vi.setSystemTime ou interface de clock injetada.

C - Dados e Isolamento

• Isole o banco de dados por job ou suíte de CI. Testcontainers ou schema dedicado; nunca compartilhe o banco de dados de desenvolvimento.
• Trunque ou reverta entre testes de integração. Evite falhas dependentes da ordem.
• Use factories/builders para entidades de teste. Configuração legível sem 50 linhas de fixtures inline.
• Alimente dados mínimos por teste. Grandes fixtures compartilhados escondem qual campo causou a falha.
• Execute migrações no banco de dados de teste como no de produção. Capture diferenças de SQL cedo.

D - Ferramentas e CI

• Entrada única npm test; divida unidade vs integração quando necessário. test:integration pode exigir Docker.
• Prefira node:test ou Vitest para código novo; planeje a saída do Jest em brownfield. Evite três runners.
• Execute testes em cada PR após typecheck e lint. Ordem de falha rápida no pipeline.
• Não mescle testes instáveis. Quarentena com ticket do proprietário e expiração, ou corrija imediatamente.
• Testes de contrato para dependências HTTP entre serviços. Pact ou diff de schema antes do deploy.

E - Carga e Lançamento

• k6/Artillery smoke no staging antes de lançamentos importantes. Limiares p95 e de taxa de erro definidos.
• Teste de carga em caminhos de escrita com estratégia de limpeza. Prefixo idempotente ou tenant dedicado.
• Meça a cobertura; não adore 100%. Módulos de domínio críticos visados; código gerado excluído.
• Teste o middleware de autenticação com tokens realistas. Não auth desabilitado em teste globalmente, a menos que seja uma unidade isolada.
• Documente como executar testes de integração localmente. Pré-requisito Docker no README.

FAQs

Relacionados

• Noções Básicas de Teste - introdução à pirâmide
• Supertest e Integração HTTP - HTTP em processo
• Testcontainers - Postgres/Redis real

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.