blob: cf7c2faf02af3b6c6266bd8e3c5e979cbe3dd80e [file] [view]
:::{default-domain} bzl
:::
# 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 registering toolchains.
For Bzlmod, use {obj}`python.toolchain`:
```starlark
python.toolchain(
"@python3_14_toolchains//:all",
configure_coverage_tool = True,
)
```
For WORKSPACE configuration, use {obj}`python_register_toolchains`:
```starlark
python_register_toolchains(
register_coverage_tool = True,
)
```
:::{note}
This will implicitly add the version of `coverage` bundled with `rules_python`
to the dependencies of {obj}`py_test` rules when `bazel coverage` is run. If a
target already transitively depends on a different version of `coverage`, then
the behavior is undefined -- it is undefined which version comes first in the
import path. If you find yourself in this situation, then set the
{flag}`--coverage` flag to the same `coverage` (see {ref}`coverage-from-pypi`).
:::
:::{note}
The bundled `coverage` wheel set covers CPython 3.9 through 3.14 (with
freethreaded variants for 3.13+), and not every platform within that range.
When the interpreter that `bazel coverage` actually selects has no bundled
wheel, `configure_coverage_tool = True` produces no coverage tool and
`bazel coverage` emits empty lcov data unless `coverage` is provided via
{flag}`--coverage` (see {ref}`coverage-from-pypi`) or manually configured
(see below).
{obj}`py_runtime` warns when this happens. The warning is emitted during
analysis, for the runtime toolchain resolution selected and only when coverage
is being collected, so it does not fire for the many platforms toolchains are
registered for but a given build never uses.
:::
## Manually configuring coverage
To manually configure coverage support, you'll need to set the
{attr}`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:
```starlark
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`.
(coverage-from-pypi)=
## Using `coverage` from PyPI
To use the version of `coverage` that is locked in your requirements instead of
the one bundled with `rules_python`, add it to your requirements and set the
{flag}`--coverage` flag to the `coverage` package in your {obj}`pip.parse` hub:
```
# .bazelrc
coverage --@rules_python//python/config_settings:coverage=@pypi//coverage
```
The Python toolchains don't need to be configured. The target is added to the
dependencies of the `py_test` and `py_binary` targets when coverage is
collected, and it isn't fetched for regular builds.
### Using a `.coveragerc` and plugins
To configure `coverage`, wrap it in a `py_library` together with any plugins and
the `.coveragerc` file, and set the {flag}`--coverage` flag to it:
```starlark
py_library(
name = "coverage",
data = [".coveragerc"],
deps = [
"@pypi//coverage",
"@pypi//coverage_conditional_plugin",
],
)
```
```
# .bazelrc
coverage --@rules_python//python/config_settings:coverage=//:coverage
```
The `.coveragerc` files in the runfiles of the target are merged in order:
options that are lists (e.g. `omit`, `exclude_also` or `plugins`) are combined
and the other options are overridden. The options that Bazel needs, such as
`relative_files`, `source` and `branch`, are always set by `rules_python`.
### Using a different `coverage` for some tests
The {flag}`--coverage` flag can be set for a single target with the
{attr}`py_test.config_settings` attribute:
```starlark
py_test(
name = "strict_test",
srcs = ["strict_test.py"],
config_settings = {
"@rules_python//python/config_settings:coverage": (
"//tools:coverage_strict"
),
},
)
```
:::{note}
This builds the test and its dependencies in a separate configuration.
:::
:::{versionadded} VERSION_NEXT_FEATURE
:::