Cobertura de código com o Bazel

O Bazel tem um subcomando coverage para gerar relatórios de cobertura de código em repositórios que podem ser testados com bazel coverage. Devido às idiossincrasias dos vários ecossistemas de linguagem, nem sempre é trivial fazer isso funcionar para um determinado projeto.

Esta página documenta o processo geral de criação e visualização de relatórios de cobertura e também apresenta algumas observações específicas de linguagem para idiomas cuja configuração é bem conhecida. É melhor ler primeiro a seção geral e depois os requisitos para um idioma específico. Consulte também a seção de execução remota, que exige algumas considerações adicionais.

Embora seja possível fazer muitas personalizações, este documento se concentra na produção e no consumo de relatórios lcov, que atualmente é a rota mais bem compatível.

Como criar um relatório de cobertura

Preparação

O fluxo de trabalho básico para criar relatórios de cobertura exige o seguinte:

• Um repositório básico com destinos de teste
• Uma cadeia de ferramentas com as ferramentas de cobertura de código específicas da linguagem instaladas
• Uma configuração de "instrumentação" correta

Os dois primeiros são específicos da linguagem e geralmente simples, mas o último pode ser mais difícil para projetos complexos.

Neste caso, "instrumentação" se refere às ferramentas de cobertura usadas para um destino específico. O Bazel permite ativar isso para um subconjunto específico de arquivos usando a flag --instrumentation_filter, que especifica um filtro para destinos testados com a instrumentação ativada. Para ativar a instrumentação de testes, é necessário usar a flag --instrument_test_targets.

Por padrão, o bazel tenta corresponder aos pacotes de destino e imprime o filtro relevante como uma mensagem INFO.

Cobertura de corrida

Para gerar um relatório de cobertura, use bazel coverage --combined_report=lcov [target]. Isso executa os testes para o destino, gerando relatórios de cobertura no formato lcov para cada arquivo.

Quando terminar, o bazel vai executar uma ação que coleta todos os arquivos de cobertura produzidos e os mescla em um só, que é criado em $(bazel info output_path)/_coverage/_coverage_report.dat.

Os relatórios de cobertura também são gerados se os testes falharem, mas isso não se estende aos testes reprovados. Somente os testes aprovados são informados.

Visualizar cobertura

O relatório de cobertura só é gerado no formato lcov não legível por humanos. Com isso, podemos usar o utilitário genhtml (parte do projeto lcov) para gerar um relatório que pode ser visualizado em um navegador da Web:

genhtml --branch-coverage --output genhtml "$(bazel info output_path)/_coverage/_coverage_report.dat"

O genhtml também lê o código-fonte para anotar a cobertura ausente nesses arquivos. Para que isso funcione, espera-se que genhtml seja executado na raiz do projeto do Bazel.

Para conferir o resultado, basta abrir o arquivo index.html produzido no diretório genhtml em qualquer navegador da Web.

Para mais ajuda e informações sobre a ferramenta genhtml ou o formato de cobertura lcov, consulte o projeto lcov.

Execução remota

A execução com testes remotos tem algumas ressalvas:

• A ação de combinação de relatórios ainda não pode ser executada remotamente. Isso acontece porque o Bazel não considera os arquivos de saída de cobertura como parte do gráfico dele (consulte este problema) e, portanto, não pode tratá-los corretamente como entradas para a ação de combinação. Para contornar isso, use --strategy=CoverageReport=local.
  • Observação: talvez seja necessário especificar algo como --strategy=CoverageReport=local,remote em vez disso, se o Bazel estiver configurado para tentar local,remote, devido à forma como o Bazel resolve as estratégias.
• --remote_download_minimal e flags semelhantes também não podem ser usadas como consequência do primeiro.
• No momento, o Bazel não cria informações de cobertura se os testes foram armazenados em cache anteriormente. Para contornar isso, --nocache_test_results pode ser definido especificamente para execuções de cobertura, embora isso, é claro, incorra em um custo alto em termos de tempos de teste.
• --experimental_split_coverage_postprocessing e --experimental_fetch_all_coverage_outputs
  • Normalmente, a cobertura é executada como parte da ação de teste. Portanto, por padrão, não recebemos toda a cobertura como saídas da execução remota. Essas flags substituem o padrão e obtêm os dados de cobertura. Consulte este problema para mais detalhes.

Configuração específica de idioma

Java

O Java funciona sem precisar de configuração com a configuração padrão. Os conjuntos de ferramentas do Bazel contêm tudo o que é necessário para a execução remota, incluindo o JUnit.

Python

Consulte os documentos de cobertura do rules_python para ver outras etapas necessárias para ativar o suporte à cobertura em Python.