Coverage de testes no Node.js: meça com critério

Coverage de Testes no Node.js mede quais linhas, funções e caminhos do código foram executados durante a suíte. A cobertura ajuda a localizar áreas sem testes, mas não comprova que o comportamento foi validado corretamente.

Uma suíte pode alcançar 100% executando linhas sem verificar resultados importantes. Por isso, cobertura deve ser combinada com assertions, cenários negativos, testes de integração e análise de risco.

Neste guia, você aprenderá métricas, relatórios, limites, exclusões, CI e boas práticas com o test runner nativo.

Executando cobertura

node --test --experimental-test-coverage

O runtime executa os testes e apresenta métricas dos arquivos carregados.

Métricas principais

• linhas: linhas executadas;
• funções: funções chamadas;
• branches: caminhos de condições exercitados;
• statements: instruções executadas.

Branch coverage costuma revelar falhas que line coverage não mostra.

Exemplo de condição

export function calcularFrete(total, vip) {
  if (vip) return 0;
  if (total >= 200) return 0;
  return 20;
}

Um único teste pode executar várias linhas, mas você precisa cobrir cliente VIP, compra acima do limite e compra comum.

Cobertura não é qualidade

Este teste executa a função, mas não valida nada:

test('executa cálculo', () => {
  calcularFrete(100, false);
});

Prefira assertions claras:

assert.equal(calcularFrete(100, false), 20);

Metas por risco

Não use um número único como objetivo absoluto. Autenticação, cobrança e autorização exigem cenários mais rigorosos que arquivos de configuração trivial.

Threshold no CI

O pipeline pode falhar quando a cobertura cai abaixo de um limite definido pela equipe. O limite deve impedir regressão sem incentivar testes artificiais.

Cobertura incremental

Em sistemas legados, aumente gradualmente. Exigir 100% imediatamente leva a exclusões indiscriminadas ou testes frágeis.

Arquivos gerados

Código compilado, migrações geradas e bundles podem distorcer relatórios. Exclua apenas arquivos que realmente não devem ser testados e documente a razão.

Testes de erro

Caminhos de erro costumam ficar sem cobertura:

• timeout;
• resposta inválida;
• recurso inexistente;
• permissão negada;
• rollback;
• cancelamento.

Cobertura de integrações

Testes unitários cobrem lógica, mas não provam queries, serialização ou configuração. Use testes de integração para essas fronteiras.

Relatórios no CI

Armazene relatório como artefato e apresente resumo no pull request. Não publique caminhos internos ou código sensível em serviços externos sem autorização.

Source maps

Projetos TypeScript ou transpilados precisam de source maps corretos para associar cobertura ao código-fonte. Veja Source Maps no Node.js.

Testes concorrentes

Concorrência pode alterar quais módulos são carregados e dificultar diagnóstico. Mantenha os testes determinísticos e compare resultados em ambiente limpo.

Mutação

Mutation testing altera o código propositalmente para verificar se testes detectam a mudança. Ele oferece sinal complementar mais forte que porcentagem pura, embora seja mais caro.

Arquivos sem testes

Garanta que o relatório inclua arquivos relevantes mesmo quando nenhum teste os importa. Caso contrário, módulos esquecidos podem nem aparecer.

Revisão de pull request

Analise novas linhas sem cobertura, mas também observe se os testes exercitam requisitos. Um diff pequeno pode alterar um caminho crítico sem reduzir muito a porcentagem total.

Integração com node:test

Consulte Node Test Runner no Node.js para hooks, subtests, timeouts e execução no CI.

Erros comuns

• buscar 100% sem avaliar risco;
• executar sem assertions;
• excluir arquivos difíceis;
• ignorar branches;
• medir apenas testes unitários;
• não incluir arquivos não importados;
• comparar relatórios gerados em ambientes diferentes;
• deixar meta cair silenciosamente.

Checklist

• linhas e branches analisadas;
• assertions relevantes;
• caminhos negativos;
• threshold documentado;
• relatório no CI;
• source maps corretos;
• arquivos críticos incluídos;
• integração e contratos complementares.

Conclusão

Coverage de Testes no Node.js é um instrumento de diagnóstico, não um certificado de qualidade. Ela mostra onde a suíte passou, mas não se os requisitos foram verificados.

Use cobertura para impedir regressões e orientar revisão. Combine a métrica com testes de comportamento, integração e análise de riscos para obter confiança real.

Consulte a documentação oficial de cobertura do test runner e a referência do node:test.