Setting up coverage

As of Bazel 6, the Python toolchains and bootstrap logic supports providing coverage information using the coverage library.

As of rules_python version 0.18.1, builtin coverage support can be enabled when configuring toolchains.

Enabling rules_python coverage support

Enabling the coverage support bundled with rules_python just requires setting an argument when registerting toolchains.

For Bzlmod:

python.toolchain(
    "@python3_9_toolchains//:all",
    configure_coverage_tool = True,
)

For WORKSPACE configuration:

python_register_toolchains(
   register_coverage_tool = True,
)

:::{note} This will implicitly add the version of coverage bundled with rules_python to the dependencies of py_test rules when bazel coverage is run. If a target already transitively depends on a different version of coverage, then behavior is undefined -- it is undefined which version comes first in the import path. If you find yourself in this situation, then you'll need to manually configure coverage (see below). :::

Manually configuring coverage

To manually configure coverage support, you'll need to set the py_runtime.coverage_tool attribute. This attribute is a target that specifies the coverage entry point file and, optionally, client libraries that are added to py_test targets. Typically, this would be a filegroup that looked like:

filegroup(
  name = "coverage",
  srcs = ["coverage_main.py"],
  data = ["coverage_lib1.py", ...]
)

Using filegroup isn't required, nor are including client libraries. The important behaviors of the target are:

• It provides a single output file OR it provides an executable output; this output is treated as the coverage entry point.
• If it provides runfiles, then runfiles.files are included into py_test.