rules_and_macros_overview.md

Rules and Macros

The rules and macros described below are used to define integration tests run against select versions of Bazel.

On this page:

• bazel_integration_test
• bazel_integration_tests
• default_test_runner

default_test_runner

load("@rules_bazel_integration_test//bazel_integration_test:defs.bzl", "default_test_runner")

default_test_runner(name, bazel_cmds)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
bazel_cmds	The Bazel commands to be executed by the test runner in the test workspace.	List of strings	optional	["info", "test //..."]

bazel_integration_test

load("@rules_bazel_integration_test//bazel_integration_test:defs.bzl", "bazel_integration_test")

bazel_integration_test(name, test_runner, bazel_version, bazel_binary, workspace_path,
                       workspace_files, tags, timeout, env, env_inherit, additional_env_inherit,
                       bazel_binaries, data, startup_options, **kwargs)

Macro that defines a set of targets for a single Bazel integration test.

This macro accepts an exectuable target as the test runner for the integration test. A test runner must support two flag-value pairs: --bazel and --workspace. The --bazel value specifies the Bazel binary to use in the integration test. The --workspace value specifies the path of the WORKSPACE file.

If your integration test only consists of executing Bazel commands, a default test runner is provided by the default_test_runner macro.

PARAMETERS

Name	Description	Default Value
name	name of the resulting py_test	none
test_runner	A Label for a test runner binary. (see description for details)	none
bazel_version	Optional. A string value representing the semantic version of Bazel to use for the integration test. If a version is not specified, then the bazel_binary must be specified.	None
bazel_binary	Optional. A Label for the Bazel binary to use for the execution of the integration test. Most users will not use this attribute. Use the bazel_version instead.	None
workspace_path	Optional. A string specifying the relative path to the child workspace. If not specified, then it is derived from the name.	None
workspace_files	Optional. A list of files for the child workspace. If not specified, then it is derived from the workspace_path.	None
tags	The Bazel tags to apply to the test declaration.	["exclusive", "manual"]
timeout	A valid Bazel timeout value. https://docs.bazel.build/versions/main/test-encyclopedia.html#role-of-the-test-runner	"long"
env	Optional. A dictionary of strings. Specifies additional environment variables to be passed to the test.	None
env_inherit	Optional. Override the env_inherit values passed to the test. Only do this if you understand what needs to be passed along. Most folks will want to use additional_env_inherit to pass additional env_inherit values.	["SUDO_ASKPASS", "HOME", "CC"]
additional_env_inherit	Optional. Specify additional env_inherit values that should be passed to the test.	[]
bazel_binaries	Optional for WORKSPACE loaded repositories. Required for repositories that enable bzlmod. The value for this parameter is loaded by adding load("@bazel_binaries//:defs.bzl", "bazel_binaries") to your build file.	None
data	Optional. A list of files to make present at test runtime.	None
startup_options	Optional. Flags that should be passed to Bazel as startup options using the BIT_STARTUP_OPTIONS environment variable.	""
kwargs	additional attributes like timeout and visibility	none

bazel_integration_tests

load("@rules_bazel_integration_test//bazel_integration_test:defs.bzl", "bazel_integration_tests")

bazel_integration_tests(name, test_runner, bazel_versions, workspace_path, workspace_files, tags,
                        timeout, env_inherit, additional_env_inherit, bazel_binaries, startup_options,
                        **kwargs)

Macro that defines a set Bazel integration tests each executed with a different version of Bazel.

PARAMETERS

Name	Description	Default Value
name	name of the resulting py_test	none
test_runner	A Label for a test runner binary.	none
bazel_versions	A list of string string values representing the semantic versions of Bazel to use for the integration tests.	[]
workspace_path	A string specifying the path to the child workspace. If not specified, then it is derived from the name.	None
workspace_files	Optional. A list of files for the child workspace. If not specified, then it is derived from the workspace_path.	None
tags	The Bazel tags to apply to the test declaration.	["exclusive", "manual"]
timeout	A valid Bazel timeout value. https://docs.bazel.build/versions/main/test-encyclopedia.html#role-of-the-test-runner	"long"
env_inherit	Optional. Override the env_inherit values passed to the test. Only do this if you understand what needs to be passed along. Most folks will want to use additional_env_inherit to pass additional env_inherit values.	["SUDO_ASKPASS", "HOME", "CC"]
additional_env_inherit	Optional. Specify additional env_inherit values that should be passed to the test.	[]
bazel_binaries	Optional for WORKSPACE loaded repositories. Required for repositories that enable bzlmod. The value for this parameter is loaded by adding load("@bazel_binaries//:defs.bzl", "bazel_binaries") to your build file.	None
startup_options	Optional. Flags that should be passed to Bazel as startup options using the BIT_STARTUP_OPTIONS environment variable.	""
kwargs	additional attributes like timeout and visibility	none