O Bazel apresenta 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 para um determinado projeto.
Nesta página, documentamos o processo geral de criação e visualização de relatórios de cobertura, além de algumas observações específicas para idiomas com configuração bem conhecida. Recomendamos ler primeiro a seção geral e, em seguida, os requisitos de uma linguagem específica. Observe também a seção de execução remota, que requer algumas considerações adicionais.
Embora seja possível muitas personalizações, este documento se concentra na
produção e consumo de relatórios lcov
, que atualmente é a
rota mais aceita.
Como criar um relatório de cobertura
Preparação
O fluxo de trabalho básico para criar relatórios de cobertura requer o seguinte:
- Um repositório básico com destinos de teste.
- Um conjunto 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, na maioria das vezes, diretas. No entanto, a segunda pode ser mais difícil para projetos complexos.
Nesse caso, "instrumentação" se refere às ferramentas de cobertura usadas
para um destino específico. O Bazel permite ativar esse recurso 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 para testes, a flag
--instrument_test_targets
é obrigatória.
Por padrão, o Bazel tenta corresponder os pacotes de destino e mostra 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 serão gerados se os testes falharem. No entanto, isso não se estende aos testes com falha. Apenas testes aprovados são informados.
Visualização da cobertura
O relatório de cobertura é gerado apenas no formato lcov
não legível. A partir disso, podemos usar o utilitário genhtml
, que faz 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"
Observe que 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 Bazel.
Para ver 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 (link em inglês).
Execução remota
Atualmente, a execução de testes remotos tem algumas ressalvas:
- Ainda não é possível executar remotamente a ação de combinação de relatórios. 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
contornar isso, use
--strategy=CoverageReport=local
.- Observação: pode ser necessário especificar algo como
--strategy=CoverageReport=local,remote
, se o Bazel estiver configurado para testarlocal,remote
, devido à forma como ele 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.- Atualmente, o Bazel não vai 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, obviamente, isso gera um custo alto em termos de tempo 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 recuperamos toda a cobertura como saídas da execução remota. Essas sinalizações substituem o padrão e coletam os dados de cobertura. Confira mais detalhes neste problema.
Configuração específica do idioma
Java
O Java deve funcionar imediatamente com a configuração padrão. Os conjuntos de ferramentas do bazel contêm tudo também para a execução remota, incluindo JUnit.
Python
Consulte os documentos de cobertura rules_python
para conhecer outras etapas necessárias para ativar o suporte à cobertura no Python.