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 notas específicas para idiomas com configuração conhecida. É melhor ler primeiro a seção geral e depois ler sobre os requisitos de um idioma específico. Observe também a seção de execução remota, que requer algumas considerações adicionais.
Embora seja possível fazer muitas personalizações, este documento se concentra em
produzir e consumir relatórios lcov, que é atualmente a
rota mais bem aceita.
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
As duas primeiras são específicas da linguagem e bastante diretas, mas a última pode ser mais difícil para projetos complexos.
"Instrumentação", neste caso, se refere às ferramentas de cobertura que são
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 que são testados com a
instrumentação ativada. Para ativar a instrumentação para testes, a flag
--instrument_test_targets
é necessária.
Por padrão, o Bazel tenta corresponder aos pacotes de destino e imprime o
filtro relevante como uma mensagem INFO.
Cobertura em execução
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.
Depois de concluído, o Bazel executa uma ação que coleta todos os arquivos de cobertura
produzidos e os mescla em um, que é finalmente
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 aplica a testes reprovados. Apenas testes aprovados são informados.
Como conferir a cobertura
O relatório de cobertura só é gerado no formato lcov, que não é legível por humanos. Com isso, podemos usar o utilitário genhtml (parte do projeto
lcov) para produzir 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, é esperado 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
No momento, a execução com execução de teste remota tem algumas ressalvas:
- A ação de combinação de relatórios ainda não pode ser executada remotamente. Isso ocorre
porque o Bazel não considera os arquivos de saída de cobertura como parte do
gráfico (consulte este problema) e, portanto, não pode
tratá-los corretamente como entradas para a ação de combinação. Para
resolver isso, use
--strategy=CoverageReport=local.- Observação: pode ser necessário especificar algo como
--strategy=CoverageReport=local,remote, se o Bazel estiver configurado para tentarlocal,remote, devido à forma como o Bazel resolve estratégias.
- Observação: pode ser necessário especificar algo como
--remote_download_minimale sinalizações semelhantes também não podem ser usadas como consequência da primeira.- No momento, o Bazel não vai conseguir criar informações de cobertura se os testes
tiverem sido armazenados em cache anteriormente. Para contornar esse problema,
--nocache_test_resultspode ser definido especificamente para execuções de cobertura, mas isso gera um custo alto em termos de tempos de teste. --experimental_split_coverage_postprocessinge--experimental_fetch_all_coverage_outputs- Normalmente, a cobertura é executada como parte da ação de teste. Por padrão, não recebemos toda a cobertura de volta como saídas da execução remota. Essas flags substituem o padrão e recebem os dados de cobertura. Consulte este problema para mais detalhes.
Configuração específica do idioma
Java
O Java deve funcionar com a configuração padrão. Os conjuntos de ferramentas do Bazel contêm tudo o que é necessário para execução remota, incluindo o JUnit.
Python
Consulte as documentações de cobertura rules_python
para conferir outras etapas necessárias para ativar o suporte à cobertura no Python.