O Bazel inclui um subcomando coverage
para produzir 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 esse trabalho 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 produzir 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 é gerado apenas no formato lcov
não legível. 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 --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 a 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_minimal
e 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_results
pode ser definido especificamente para execuções de cobertura, mas isso, é claro, gera 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. Por isso, por padrão, não recebemos toda a cobertura 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.