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.