Cobertura de código con Bazel

Informa un problema Ver código fuente

Bazel cuenta con un subcomando coverage para producir 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 a fin de crear y ver informes de cobertura y, además, se incluyen algunas notas específicas del lenguaje para lenguajes cuya configuración es conocida. Se recomienda leer primero la sección general y, luego, leer los requisitos para un lenguaje específico. Ten en cuenta también la sección de ejecución remota, que requiere algunas consideraciones adicionales.

Si bien se puede personalizar mucho, este documento se centra en producir y consumir informes lcov, que actualmente es la ruta más compatible.

Crea un informe de cobertura

Preparation

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 "instrumentación" correcta

Las dos primeras son específicas para cada lenguaje y, en su mayoría, sencillas, pero la última puede ser más difícil en proyectos complejos.

En este caso, “instrumentación” se refiere a las herramientas de cobertura que se usan para un destino específico. Bazel permite activar esta función en un subconjunto específico de archivos mediante la marca --instrumentation_filter, que especifica un filtro para los destinos que se prueban con la instrumentación habilitada. A fin de 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 generar un informe de cobertura, usa bazel coverage --combined_report=lcov [target]. Esto ejecuta las pruebas del destino y genera informes de cobertura en el formato lcov para cada archivo.

Una vez terminado, 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 producen si las pruebas fallan, aunque ten en cuenta que esto no se extiende a las pruebas con errores, solo se informan las pruebas aprobadas.

Visualiza la cobertura

El informe de cobertura solo se muestra en el formato lcov no legible. A partir de esto, podemos usar la utilidad genhtml (que forma parte del proyecto lcov) para producir un informe que se puede ver en un navegador web:

genhtml --branch-coverage --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 de Bazel.

Para ver el resultado, simplemente abre el archivo index.html producido en el directorio genhtml de cualquier navegador web.

Para obtener más información y ayuda sobre la herramienta de genhtml, o el formato de cobertura lcov, consulta el proyecto de lcov.

Ejecución remota

Actualmente, la ejecución de pruebas remotas tiene algunas advertencias:

  • La acción de combinación de informes aún 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 esto, usa --strategy=CoverageReport=local.
    • Nota: Es posible que debas especificar algo como --strategy=CoverageReport=local,remote si Bazel está configurado para probar local,remote, debido a la forma en que Bazel resuelve las estrategias.
  • --remote_download_minimal y marcas similares tampoco se pueden usar como consecuencia de lo anterior.
  • Por el momento, Bazel no podrá crear información de cobertura si las pruebas se almacenaron en caché con anterioridad. A fin de solucionar esto, --nocache_test_results se puede configurar específicamente para ejecuciones de cobertura, aunque, por supuesto, esto genera un gran costo en términos de tiempos de prueba.
  • --experimental_split_coverage_postprocessing y --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 obtenemos toda la cobertura como resultado de la ejecución remota. Estas marcas anulan el valor predeterminado y obtienen los datos de cobertura. Consulta este problema para obtener más detalles.

Configuración específica del lenguaje

Java

Java debería funcionar de forma predeterminada con la configuración predeterminada. Las cadenas de herramientas de Bazel contienen todo lo necesario para la ejecución remota, incluida JUnit.

Python

Consulta los documentos de cobertura de rules_python si quieres conocer los pasos adicionales necesarios para habilitar la compatibilidad con la cobertura en Python.