py_test.md

Re-implementations of py_binary and py_test

Choosing the Python version

The python_version attribute must refer to a python toolchain version which has been registered in the WORKSPACE or MODULE.bazel file.

When using WORKSPACE, this may look like this:

load("@rules_python//python:repositories.bzl", "py_repositories", "python_register_toolchains")

python_register_toolchains(
    name = "python_toolchain_3_8",
    python_version = "3.8.12",
    # setting set_python_version_constraint makes it so that only matches py_* rule  
    # which has this exact version set in the `python_version` attribute.
    set_python_version_constraint = True,
)

# It's important to register the default toolchain last it will match any py_* target. 
python_register_toolchains(
    name = "python_toolchain",
    python_version = "3.9",
)

Configuring for MODULE.bazel may look like this:

python = use_extension("@rules_python//python/extensions:python.bzl", "python")
python.toolchain(python_version = "3.8.12", is_default = False)
python.toolchain(python_version = "3.9", is_default = True)

py_test_rule

py_test_rule(name, data, deps, env, env_inherit, imports, interpreter_options, main,
             package_collisions, python_version, resolutions, srcs)

Run a Python program under Bazel. Most users should use the py_test macro instead of loading this directly.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
data	Runtime dependencies of the program. The transitive closure of the data dependencies will be available in the .runfiles folder for this binary/test. The program may optionally use the Runfiles lookup library to locate the data files, see https://pypi.org/project/bazel-runfiles/.	List of labels	optional	[]
deps	Targets that produce Python code, commonly py_library rules.	List of labels	optional	[]
env	Environment variables to set when running the binary.	Dictionary: String -> String	optional	{}
env_inherit	Specifies additional environment variables to inherit from the external environment when the test is executed by bazel test.	List of strings	optional	[]
imports	List of import directories to be added to the PYTHONPATH.	List of strings	optional	[]
interpreter_options	Additional options to pass to the Python interpreter in addition to -B and -I passed by rules_py	List of strings	optional	[]
main	Script to execute with the Python interpreter.	Label	required
package_collisions	The action that should be taken when a symlink collision is encountered when creating the venv. A collision can occour when multiple packages providing the same file are installed into the venv. The possible values are: * "error": When conflicting symlinks are found, an error is reported and venv creation halts. * "warning": When conflicting symlinks are found, an warning is reported, however venv creation continues. * "ignore": When conflicting symlinks are found, no message is reported and venv creation continues.	String	optional	"error"
python_version	Whether to build this target and its transitive deps for a specific python version.	String	optional	""
resolutions	Satisfy a virtual_dep with a mapping from external package name to the label of an installed package that provides it. See virtual dependencies.	Dictionary: Label -> String	optional	{}
srcs	Python source files.	List of labels	optional	[]

py_pytest_main

py_pytest_main(name, py_library, deps, data, testonly, kwargs)

py_pytest_main wraps the template rendering target and the final py_library.

PARAMETERS

Name	Description	Default Value
name	The name of the runable target that updates the test entry file.	none
py_library	Use this attribute to override the default py_library rule.	<unknown object com.google.devtools.build.skydoc.fakebuildapi.FakeStarlarkRuleFunctionsApi$RuleDefinitionIdentifier>
deps	A list containing the pytest library target, e.g., @pypi_pytest//:pkg.	[]
data	A list of data dependencies to pass to the py_library target.	[]
testonly	A boolean indicating if the py_library target is testonly.	True
kwargs	The extra arguments passed to the template rendering target.	none

py_test

py_test(name, main, srcs, kwargs)

Identical to py_binary, but produces a target that can be used with bazel test.

PARAMETERS

Name	Description	Default Value
name	-	none
main	-	None
srcs	-	[]
kwargs	-	none