O Bazel tem 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 idiomas, nem sempre
é trivial esse trabalho em 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 uma configuração conhecida. É melhor ler primeiro a seção geral e, em seguida, ler 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 fazer muitas personalizações, este documento se concentra na
produção e no consumo de relatórios lcov
, que atualmente é a
rota mais 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
- Um conjunto 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, principalmente, o mais simples, mas o último pode ser mais difícil para projetos complexos.
Nesse caso, "instrumentação" se refere às ferramentas de cobertura que são
usadas para um destino específico. O Bazel permite ativar esse recurso para um subconjunto específico de arquivos usando a sinalização --instrumentation_filter
, que especifica um filtro para destinos testados com a instrumentação ativada. Para ativar a instrumentação para testes, a
sinalização --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 gera 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, que é criado em $(bazel info
output_path)/_coverage/_coverage_report.dat
.
Os relatórios de cobertura também são produzidos se os testes falharem. No entanto, isso não se estende aos testes com falha. Somente os testes aprovados são informados.
Como visualizar a cobertura
O relatório de cobertura é gerado somente no formato lcov
não legível. A partir disso, 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"
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
No momento, a execução com teste remoto 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: talvez seja necessário especificar algo como
--strategy=CoverageReport=local,remote
, se o Bazel estiver configurado para testarlocal,remote
, devido à forma como o Bazel resolve estratégias.
- Observação: talvez seja 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 criar informações de cobertura se os testes tiverem sido armazenados em cache anteriormente. Para contornar isso,
o
--nocache_test_results
pode ser definido especificamente para execuções de cobertura, mas obviamente gera um alto custo 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 e, por padrão, não recebemos toda a cobertura de volta como saídas da execução remota por padrão. Essas sinalizações substituem o padrão e recebem os dados de cobertura. Para ver mais detalhes, consulte este problema.
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 a execução remota, incluindo o JUnit.
Python
Consulte os documentos de cobertura de rules_python
para ver outras etapas necessárias para ativar o suporte de cobertura em Python.