Ele 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.
Nesta página, documentamos o processo geral de criação e visualização de relatórios de cobertura, além de apresentar algumas observações específicas para idiomas com configuração bem conhecida. Para facilitar a leitura, leia primeiro a seção geral e, em seguida, leia sobre os requisitos de uma linguagem específica. Observe também a seção de execução remota, que requer algumas considerações adicionais.
Embora muitas opções de personalização sejam possíveis, 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
Os dois primeiros são específicos de linguagem e, na maioria das vezes, diretos, mas o segundo pode ser mais difícil para projetos complexos.
Nesse caso, "instrumentação" se refere às ferramentas de cobertura que são
usadas para um objetivo 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 sinalização
--instrument_test_targets
é necessária.
Por padrão, o Bazel tenta fazer a correspondência dos 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 só, 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 os testes aprovados são informados.
Visualização da cobertura
O relatório de cobertura é gerado apenas no formato lcov
não legível. Assim, 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 --output genhtml "$(bazel info output_path)/_coverage/_coverage_report.dat"
Observe que o genhtml
também lê o código-fonte para anotar a cobertura
faltante nesses arquivos. Para que isso funcione, espera-se que
genhtml
seja executado na raiz do projeto do 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 (links em inglês).
Execução remota
No momento, a execução com a execução de teste remoto 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 tentarlocal,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 do primeiro.- No momento, o Bazel não cria informações de cobertura se os testes
já foram armazenados em cache. Para contornar isso,
--nocache_test_results
pode ser definido especificamente para execuções de cobertura, embora isso tenha um alto custo 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. 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. Veja este problema para saber mais.
Configuração específica da linguagem
Java
O Java deve funcionar pronto para uso 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 as etapas adicionais necessárias para ativar o suporte à cobertura no Python.