:::{default-domain} bzl :::

Testing with pytest

{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.

Setup

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()

What pytest-bazel does

The pytest-bazel docs show each feature with the output of an example. The main ones are:

Bazelpytest-bazelDocs
--test_filterSelects 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_countSplits 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_fastStops at the first failure.Fail fast
Test timeoutsPrints the stacks of all threads, and of the pytest-xdist workers, when Bazel stops the test.Timeout, xdist
bazel-testlogsWrites 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_TMPDIRPoints TMPDIR and pytest's tmp_path at it, so tests do not write outside the sandbox.Temporary directories
bazel runDebug 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.

Configuration

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.