:::{default-domain} bzl :::
{obj}pytest_test runs pytest tests with pytest-bazel, a pytest runner that follows the Bazel test encyclopedia. It writes its own main that runs pytest on the srcs, so there is no main to maintain, and creates a test per Python version with python_versions.
pytest_test depends on @pypi//pytest and @pypi//pytest_bazel by default. Add pytest and pytest-bazel>=1.0 to the requirements that {obj}pip.parse reads for the {ref}unified @pypi hub <unified-pypi-hub>, or pass other targets with the pytest and pytest_bazel arguments.
load("@rules_python//python:pytest_test.bzl", "pytest_test") pytest_test( name = "lib_test", srcs = ["lib_test.py"], deps = [":lib"], ) pytest_test( name = "lib_all_test", srcs = ["lib_test.py"], # A `lib_all_py3.13_test` and a `lib_all_py3.14_test` in a test suite # named `lib_all_test`. python_versions = ["3.13", "3.14"], deps = [":lib"], )
pytest-randomly is optional. Pass pytest_randomly = "@pypi//pytest_randomly" to run the tests in a random order, which pytest-bazel seeds from --runs_per_test, so that each run uses a different order that can be reproduced.
To use pytest-bazel with a plain {obj}py_test, call it from the main:
import pytest_bazel if __name__ == "__main__": pytest_bazel.main()
The pytest-bazel docs show each feature with the output of an example. The main ones are:
| Bazel | pytest-bazel | Docs |
|---|---|---|
--test_filter | Selects tests by their exact names, e.g. TestClass.test_fn, a path or a pytest node id, or several of them separated by commas. A filter with spaces is a -k expression. | Test filter |
shard_count | Splits the tests into balanced shards, no pytest-shard needed. | Sharding |
--runs_per_test, --test_env=TEST_RANDOM_SEED=... | Seeds pytest-randomly, or random.seed without it. | Runs per test |
--test_runner_fail_fast | Stops at the first failure. | Fail fast |
| Test timeouts | Prints the stacks of all threads, and of the pytest-xdist workers, when Bazel stops the test. | Timeout, xdist |
bazel-testlogs | Writes the JUnit XML with the output of failed tests, keeps the tmp_path of failed tests in test.outputs and writes the warnings to test.warnings. | JUnit XML, Keep failed tmp_path, Warnings |
TEST_TMPDIR | Points TMPDIR and pytest's tmp_path at it, so tests do not write outside the sandbox. | Temporary directories |
bazel run | Debug a test with bazel run //pkg:test -- --pdb, as bazel test gives tests no terminal. | Debugging |
Paths in tracebacks and warnings are relative to the workspace root, so editors can open them, see Editors.
pytest reads its config file, e.g. pytest.ini or pyproject.toml, from the runfiles: add it to the data of the test. pytest-bazel also uses the config file in the Bazel package of the test or in its parents, see Config from package.
Pass pytest flags with args or --test_arg, e.g. bazel test //pkg:test --test_arg=-vv.
The behaviours of pytest-bazel that changed in 1.0 can be turned off with an env var set to 0, in the env of a test or for all tests with --test_env:
pytest_test( name = "lib_test", srcs = ["lib_test.py"], env = {"PYTEST_BAZEL_EXACT_TEST_FILTER": "0"}, )
See the flags for the list.