Bazel incluye un subcomando coverage para generar informes de cobertura de código en repositorios que se pueden probar con bazel coverage. Debido a las idiosincrasias de los diversos ecosistemas de lenguaje, no siempre es trivial hacer que esto funcione para un proyecto determinado.
En esta página, se documenta el proceso general para crear y ver informes de cobertura, y también se incluyen algunas notas específicas de lenguaje para lenguajes cuya configuración es conocida. Lo mejor es leer primero la sección general y, luego, leer sobre los requisitos de un idioma específico. También ten en cuenta la sección de ejecución remota, que requiere algunas consideraciones adicionales.
Si bien es posible realizar muchas personalizaciones, en este documento, nos enfocamos en producir y consumir informes de lcov, que actualmente es la ruta más compatible.
Crea un informe de cobertura
Preparación
El flujo de trabajo básico para crear informes de cobertura requiere lo siguiente:
- Un repositorio básico con destinos de prueba
- Una cadena de herramientas con las herramientas de cobertura de código específicas del lenguaje instaladas
- Una configuración de “instrumentación” correcta
Los dos primeros son específicos del lenguaje y, en su mayoría, son sencillos. Sin embargo, el último puede ser más difícil para proyectos complejos.
En este caso, "instrumentación" hace referencia a las herramientas de cobertura que se usan para un objetivo específico. Bazel permite activar esta opción para un subconjunto específico de archivos con la marca --instrumentation_filter, que especifica un filtro para los destinos que se prueban con la instrumentación habilitada. Para habilitar la instrumentación para pruebas, se requiere la marca --instrument_test_targets.
De forma predeterminada, bazel intenta hacer coincidir los paquetes de destino y, luego, imprime el filtro relevante como un mensaje INFO.
Cobertura para correr
Para crear un informe de cobertura, usa bazel coverage
--combined_report=lcov
[target]. Esto ejecuta las pruebas para el destino y genera informes de cobertura en formato lcov para cada archivo.
Una vez que finaliza, bazel ejecuta una acción que recopila todos los archivos de cobertura producidos y los combina en uno, que luego se crea en $(bazel info
output_path)/_coverage/_coverage_report.dat.
Los informes de cobertura también se generan si las pruebas fallan. Sin embargo, ten en cuenta que esto no se extiende a las pruebas fallidas, solo se informan las pruebas aprobadas.
Cómo ver la cobertura
El informe de cobertura solo se muestra en el formato lcov, que no es legible por humanos. Desde esto, podemos usar la utilidad genhtml (parte del proyecto lcov) para producir un informe que se puede ver en un navegador web:
genhtml --output genhtml "$(bazel info output_path)/_coverage/_coverage_report.dat"
Ten en cuenta que genhtml también lee el código fuente para anotar la cobertura faltante en estos archivos. Para que esto funcione, se espera que genhtml se ejecute en la raíz del proyecto bazel.
Para ver el resultado, simplemente abre el archivo index.html que se produjo en el directorio genhtml en cualquier navegador web.
Para obtener más ayuda e información sobre la herramienta genhtml o el formato de cobertura lcov, consulta el proyecto lcov.
Ejecución remota
La ejecución con la ejecución de prueba remota actualmente tiene algunas advertencias:
- La acción de combinación de informes todavía no se puede ejecutar de forma remota. Esto se debe a que Bazel no considera los archivos de salida de cobertura como parte de su gráfico (consulta este problema) y, por lo tanto, no puede tratarlos correctamente como entradas para la acción de combinación. Para solucionar este problema, usa
--strategy=CoverageReport=local.- Nota: Es posible que, en su lugar, debas especificar algo como
--strategy=CoverageReport=local,remote, si Bazel está configurado para probarlocal,remote, debido a la forma en que Bazel resuelve estrategias.
- Nota: Es posible que, en su lugar, debas especificar algo como
- Tampoco se pueden usar
--remote_download_minimalni marcas similares como consecuencia de lo anterior. - Actualmente, Bazel no podrá crear información de cobertura si las pruebas
se almacenaron en caché anteriormente. Para solucionar esto, se puede configurar
--nocache_test_resultsespecíficamente para las ejecuciones de cobertura, aunque esto, por supuesto, genera un alto costo en términos de tiempos de prueba. --experimental_split_coverage_postprocessingy--experimental_fetch_all_coverage_outputs- Por lo general, la cobertura se ejecuta como parte de la acción de prueba, por lo que, de forma predeterminada, no recuperamos toda la cobertura como resultados de la ejecución remota. Estas marcas anulan la configuración predeterminada y obtienen los datos de cobertura. Consulta este problema para obtener más detalles.
Configuración específica del idioma
Java
Java debería funcionar de inmediato con la configuración predeterminada. Las cadenas de herramientas de Bazel también contienen todo lo necesario para la ejecución remota, incluido JUnit.
Python
Consulta la documentación de cobertura de rules_python para conocer los pasos adicionales necesarios para habilitar la compatibilidad con la cobertura en Python.