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 and `native.*`; * `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. ## unittest_toolchain

unittest_toolchain(name, escape_chars_with, escape_other_chars_with, failure_templ, file_ext,
                   join_on, success_templ)

**ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | escape_chars_with | 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`. | Dictionary: String -> String | optional | `{}` | | escape_other_chars_with | 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 `\`. | String | optional | `""` | | failure_templ | 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. | String | required | | | file_ext | File extension for test script, including leading dot. | String | required | | | join_on | String used to join the lines in the failure message before including the resulting string in the script specified in `failure_templ`. | String | required | | | success_templ | Test script generated when the test passes. Should exit with status 0. | String | required | | ## analysistest.begin

analysistest.begin(ctx)

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. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | ctx | The Starlark context. Pass the implementation function's `ctx` argument in verbatim. | none | **RETURNS** A test environment struct that must be passed to assertions and finally to `analysistest.end`. Do not rely on internal details about the fields in this struct as it may change. ## analysistest.end

analysistest.end(env)

analysistest.fail(env, msg)

analysistest.make(impl, expect_failure, attrs, fragments, config_settings,
                  extra_target_under_test_aspects, doc)

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`. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | impl | The implementation function of the unit test. | none | | expect_failure | 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 | `False` | | attrs | An optional dictionary to supplement the attrs passed to the unit test's `rule()` constructor. | `{}` | | fragments | An optional list of fragment names that can be used to give rules access to language-specific parts of configuration. | `[]` | | config_settings | 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 | 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 | A description of the rule that can be extracted by documentation generating tools. | `""` | **RETURNS** A rule definition that should be stored in a global whose name ends in `_test`. ## analysistest.target_actions

analysistest.target_actions(env)

analysistest.target_bin_dir_path(env)

analysistest.target_under_test(env)

asserts.equals(env, expected, actual, msg)

asserts.expect_failure(env, expected_failure_msg)

asserts.false(env, condition, msg)

asserts.new_set_equals(env, expected, actual, msg)

asserts.set_equals(env, expected, actual, msg)

asserts.true(env, condition, msg)

loadingtest.equals(env, test_case, expected, actual)

loadingtest.make(name)

register_unittest_toolchains()

Registers the toolchains for unittest users. ## unittest.begin

unittest.begin(ctx)

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. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | ctx | The Starlark context. Pass the implementation function's `ctx` argument in verbatim. | none | **RETURNS** A test environment struct that must be passed to assertions and finally to `unittest.end`. Do not rely on internal details about the fields in this struct as it may change. ## unittest.end

unittest.end(env)

unittest.fail(env, msg)

unittest.make(impl, attrs, doc, toolchains)

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. The optional `toolchains` argument can be used to define toolchain dependencies for this test. 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`. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | impl | The implementation function of the unit test. | none | | attrs | An optional dictionary to supplement the attrs passed to the unit test's `rule()` constructor. | `{}` | | doc | A description of the rule that can be extracted by documentation generating tools. | `""` | | toolchains | An optional list to supplement the toolchains passed to the unit test's `rule()` constructor. | `[]` | **RETURNS** A rule definition that should be stored in a global whose name ends in `_test`. ## unittest.suite

unittest.suite(name, test_rules)

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. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name of the `test_suite` target, and the prefix of all the test target names. | none | | test_rules | A list of test rules defines by `unittest.test`. | none |