Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 18 additions & 14 deletions docs/coverage.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
:::{default-domain} bzl
:::

# Setting up coverage

As of Bazel 6, the Python toolchains and bootstrap logic supports providing
Expand All @@ -11,7 +14,7 @@ when configuring toolchains.
Enabling the coverage support bundled with `rules_python` just requires setting an
argument when registering toolchains.

For Bzlmod:
For Bzlmod, use {obj}`python.toolchain`:

```starlark
python.toolchain(
Expand All @@ -20,7 +23,7 @@ python.toolchain(
)
```

For WORKSPACE configuration:
For WORKSPACE configuration, use {obj}`python_register_toolchains`:

```starlark
python_register_toolchains(
Expand All @@ -29,12 +32,12 @@ python_register_toolchains(
```

:::{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 the 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).
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 you'll need to
manually configure coverage (see below).
:::

:::{note}
Expand All @@ -45,18 +48,19 @@ wheel, `configure_coverage_tool = True` produces no coverage tool and
`bazel coverage` emits empty lcov data; manually configure coverage (see
below) instead.

`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
{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
`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:
{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(
Expand Down
Loading