unittest
Unit testing support.
Unlike most Skylib files, this exports four modules:
unittest
contains functions to declare and define unit tests for ordinary Starlark functions;analysistest
contains functions to declare and define tests for analysis phase behavior of a rule, such as a given target's providers or registered actions;loadingtest
contains functions to declare and define tests for loading phase behavior, such as macros andnative.*
;asserts
contains the assertions used within tests.
See https://bazel.build/extending/concepts for background about macros, rules, and the different phases of a build.
Rules
unittest_toolchain
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "unittest_toolchain")
unittest_toolchain(
# A unique name for this target.
name = "",
# Test script template with a single `%s`
failure_templ = "",
# File extension for test script, including leading dot.
file_ext = "",
# String used to join the lines in the failure message before including the resulting string in the script specified in `failure_templ`.
join_on = "",
# Test script generated when the test passes
success_templ = "",
)
name
Required name.
A unique name for this target.
escape_chars_with
Optional dictionary: String → String.
Default: {}
Dictionary of characters that need escaping in test failure message to prefix appended to escape those characters. For example, {"%": "%", ">": "^"}
would replace %
with %%
and >
with ^>
in the failure message before that is included in success_templ
.
escape_other_chars_with
Optional string.
Default: ""
String to prefix every character in test failure message which is not a key in escape_chars_with
before including that in success_templ
. For example, ""
would prefix every character in the failure message (except those in the keys of escape_chars_with
) with \
.
failure_templ
Required string.
Test script template with a single %s
. That placeholder is replaced with the lines in the failure message joined with the string specified in join_with
. The resulting script should print the failure message and exit with non-zero status.
file_ext
Required string.
File extension for test script, including leading dot.
join_on
Required string.
String used to join the lines in the failure message before including the resulting string in the script specified in failure_templ
.
success_templ
Required string.
Test script generated when the test passes. Should exit with status 0.
Macros and Functions
analysistest.make
Creates an analysis test rule from its implementation function.
An analysis test verifies the behavior of a "real" rule target by examining and asserting on the providers given by the real target.
Each analysis test is defined in an implementation function that must then be associated with a rule so that a target can be built. This function handles the boilerplate to create and return a test rule and captures the implementation function's name so that it can be printed in test feedback.
An example of an analysis test:
def _your_test(ctx):
env = analysistest.begin(ctx)
# Assert statements go here
return analysistest.end(env)
your_test = analysistest.make(_your_test)
Recall that names of test rules must end in _test
.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "analysistest")
analysistest.make(
# The implementation function of the unit test.
impl = None,
)
impl
Required.
The implementation function of the unit test.
expect_failure
Optional. Default: False
If true, the analysis test will expect the target_under_test to fail. Assertions can be made on the underlying failure using asserts.expect_failure
attrs
Optional. Default: {}
An optional dictionary to supplement the attrs passed to the
unit test's rule()
constructor.
fragments
Optional. Default: []
An optional list of fragment names that can be used to give rules access to language-specific parts of configuration.
config_settings
Optional. Default: {}
A dictionary of configuration settings to change for the target under test and its dependencies. This may be used to essentially change 'build flags' for the target under test, and may thus be utilized to test multiple targets with different flags in a single build
extra_target_under_test_aspects
Optional. Default: []
An optional list of aspects to apply to the target_under_test in addition to those set up by default for the test harness itself.
doc
Optional. Default: ""
A description of the rule that can be extracted by documentation generating tools.
analysistest.begin
Begins an analysis test.
This should be the first function called in an analysis test implementation function. It initializes a "test environment" that is used to collect assertion failures so that they can be reported and logged at the end of the test.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "analysistest")
analysistest.begin(
# The Starlark context
ctx = None,
)
ctx
Required.
The Starlark context. Pass the implementation function's ctx
argument
in verbatim.
analysistest.end
Ends an analysis test and logs the results.
This must be called and returned at the end of an analysis test implementation function so that the results are reported.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "analysistest")
analysistest.end(
# The test environment returned by `analysistest.begin`.
env = {},
)
env
Required.
The test environment returned by analysistest.begin
.
analysistest.fail
Unconditionally causes the current test to fail.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "analysistest")
analysistest.fail(
# The test environment returned by `unittest.begin`.
env = {},
# The message to log describing the failure.
msg = None,
)
env
Required.
The test environment returned by unittest.begin
.
msg
Required.
The message to log describing the failure.
analysistest.target_actions
Returns a list of actions registered by the target under test.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "analysistest")
analysistest.target_actions(
# The test environment returned by `analysistest.begin`.
env = {},
)
env
Required.
The test environment returned by analysistest.begin
.
analysistest.target_bin_dir_path
Returns ctx.bin_dir.path for the target under test.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "analysistest")
analysistest.target_bin_dir_path(
# The test environment returned by `analysistest.begin`.
env = {},
)
env
Required.
The test environment returned by analysistest.begin
.
analysistest.target_under_test
Returns the target under test.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "analysistest")
analysistest.target_under_test(
# The test environment returned by `analysistest.begin`.
env = {},
)
env
Required.
The test environment returned by analysistest.begin
.
asserts.expect_failure
Asserts that the target under test has failed with a given error message.
This requires that the analysis test is created with analysistest.make()
and
expect_failures = True
is specified.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "asserts")
asserts.expect_failure(
# The test environment returned by `analysistest.begin`.
env = {},
)
env
Required.
The test environment returned by analysistest.begin
.
expected_failure_msg
Optional. Default: ""
The error message to expect as a result of analysis failures.
asserts.equals
Asserts that the given expected
and actual
values are equal.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "asserts")
asserts.equals(
# The test environment returned by `unittest.begin`.
env = {},
# The expected value of some computation.
expected = None,
# The actual value returned by some computation.
actual = None,
)
env
Required.
The test environment returned by unittest.begin
.
expected
Required.
The expected value of some computation.
actual
Required.
The actual value returned by some computation.
msg
Optional. Default: None
An optional message that will be printed that describes the failure. If omitted, a default will be used.
asserts.false
Asserts that the given condition
is false.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "asserts")
asserts.false(
# The test environment returned by `unittest.begin`.
env = {},
# A value that will be evaluated in a Boolean context.
condition = None,
)
env
Required.
The test environment returned by unittest.begin
.
condition
Required.
A value that will be evaluated in a Boolean context.
msg
Optional. Default: "Expected condition to be false, but was true."
An optional message that will be printed that describes the failure. If omitted, a default will be used.
asserts.set_equals
Asserts that the given expected
and actual
sets are equal.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "asserts")
asserts.set_equals(
# The test environment returned by `unittest.begin`.
env = {},
# The expected set resulting from some computation.
expected = None,
# The actual set returned by some computation.
actual = None,
)
env
Required.
The test environment returned by unittest.begin
.
expected
Required.
The expected set resulting from some computation.
actual
Required.
The actual set returned by some computation.
msg
Optional. Default: None
An optional message that will be printed that describes the failure. If omitted, a default will be used.
asserts.new_set_equals
Asserts that the given expected
and actual
sets are equal.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "asserts")
asserts.new_set_equals(
# The test environment returned by `unittest.begin`.
env = {},
# The expected set resulting from some computation.
expected = None,
# The actual set returned by some computation.
actual = None,
)
env
Required.
The test environment returned by unittest.begin
.
expected
Required.
The expected set resulting from some computation.
actual
Required.
The actual set returned by some computation.
msg
Optional. Default: None
An optional message that will be printed that describes the failure. If omitted, a default will be used.
asserts.true
Asserts that the given condition
is true.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "asserts")
asserts.true(
# The test environment returned by `unittest.begin`.
env = {},
# A value that will be evaluated in a Boolean context.
condition = None,
)
env
Required.
The test environment returned by unittest.begin
.
condition
Required.
A value that will be evaluated in a Boolean context.
msg
Optional. Default: "Expected condition to be true, but was false."
An optional message that will be printed that describes the failure. If omitted, a default will be used.
loadingtest.make
Creates a loading phase test environment and test_suite.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "loadingtest")
loadingtest.make(
# name of the suite of tests to create
name = "",
)
name
Required.
name of the suite of tests to create
loadingtest.equals
Creates a test case for asserting state at LOADING phase.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "loadingtest")
loadingtest.equals(
# Loading test env created from loadingtest.make
env = {},
# Name of the test case
test_case = None,
# Expected value to test
expected = None,
# Actual value received.
actual = None,
)
env
Required.
Loading test env created from loadingtest.make
test_case
Required.
Name of the test case
expected
Required.
Expected value to test
actual
Required.
Actual value received.
register_unittest_toolchains
Registers the toolchains for unittest users.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "register_unittest_toolchains")
register_unittest_toolchains(
)
unittest.make
Creates a unit test rule from its implementation function.
Each unit test is defined in an implementation function that must then be associated with a rule so that a target can be built. This function handles the boilerplate to create and return a test rule and captures the implementation function's name so that it can be printed in test feedback.
The optional attrs
argument can be used to define dependencies for this
test, in order to form unit tests of rules.
An example of a unit test:
def _your_test(ctx):
env = unittest.begin(ctx)
# Assert statements go here
return unittest.end(env)
your_test = unittest.make(_your_test)
Recall that names of test rules must end in _test
.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "unittest")
unittest.make(
# The implementation function of the unit test.
impl = None,
)
impl
Required.
The implementation function of the unit test.
attrs
Optional. Default: {}
An optional dictionary to supplement the attrs passed to the
unit test's rule()
constructor.
doc
Optional. Default: ""
A description of the rule that can be extracted by documentation generating tools.
unittest.suite
Defines a test_suite
target that contains multiple tests.
After defining your test rules in a .bzl
file, you need to create targets
from those rules so that blaze test
can execute them. Doing this manually
in a BUILD file would consist of listing each test in your load
statement
and then creating each target one by one. To reduce duplication, we recommend
writing a macro in your .bzl
file to instantiate all targets, and calling
that macro from your BUILD file so you only have to load one symbol.
You can use this function to create the targets and wrap them in a single
test_suite target. If a test rule requires no arguments, you can simply list
it as an argument. If you wish to supply attributes explicitly, you can do so
using partial.make()
. For instance, in your .bzl
file, you could write:
def your_test_suite():
unittest.suite(
"your_test_suite",
your_test,
your_other_test,
partial.make(yet_another_test, timeout = "short"),
)
Then, in your BUILD
file, simply load the macro and invoke it to have all
of the targets created:
load("//path/to/your/package:tests.bzl", "your_test_suite")
your_test_suite()
If you pass N unit test rules to unittest.suite
, N + 1 targets will be
created: a test_suite
target named ${name}
(where ${name}
is the name
argument passed in here) and targets named ${name}_test_${i}
, where ${i}
is the index of the test in the test_rules
list, which is used to uniquely
name each target.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "unittest")
unittest.suite(
# The name of the `test_suite` target, and the prefix of all the test
name = "",
)
name
Required.
The name of the test_suite
target, and the prefix of all the test
target names.
test_rules
Optional.
A list of test rules defines by unittest.test
.
unittest.begin
Begins a unit test.
This should be the first function called in a unit test implementation function. It initializes a "test environment" that is used to collect assertion failures so that they can be reported and logged at the end of the test.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "unittest")
unittest.begin(
# The Starlark context
ctx = None,
)
ctx
Required.
The Starlark context. Pass the implementation function's ctx
argument
in verbatim.
unittest.end
Ends a unit test and logs the results.
This must be called and returned at the end of a unit test implementation function so that the results are reported.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "unittest")
unittest.end(
# The test environment returned by `unittest.begin`.
env = {},
)
env
Required.
The test environment returned by unittest.begin
.
unittest.fail
Unconditionally causes the current test to fail.
Example usage (generated):
load("@bazel_skylib//lib:unittest.bzl", "unittest")
unittest.fail(
# The test environment returned by `unittest.begin`.
env = {},
# The message to log describing the failure.
msg = None,
)
env
Required.
The test environment returned by unittest.begin
.
msg
Required.
The message to log describing the failure.