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.
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.
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.
Unconditionally causes the current test to fail.
Returns a list of actions registered by the target under test.
Returns the target under test.
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.
Asserts that the given expected and actual values are equal.
Asserts that the given condition is false.
Asserts that the given expected and actual sets are equal.
Asserts that the given expected and actual sets are equal.
Asserts that the given condition is true.
Registers the toolchains for unittest users.
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.
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.
For the case where your unit tests do not take any (non-default) attributes -- i.e., if your unit tests do not test rules -- you can use this function to create the targets and wrap them in a single test_suite target. In your .bzl file, write:
def your_test_suite():
unittest.suite(
"your_test_suite",
your_test,
your_other_test,
yet_another_test,
)
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.
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.
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.
Unconditionally causes the current test to fail.