Unit testing support.

Unlike most Skylib files, this exports two modules: unittest which contains functions to declare and define unit tests, and asserts which contains the assertions used to within tests.

Rules

unittest_toolchain

Example usage (generated)

load("@bazel_skylib//lib:unittest.bzl", "unittest_toolchain")

unittest_toolchain(
    # A unique name for this target.
    name = "",
    failure_templ = "",
    file_ext = "",
    join_on = "",
    success_templ = "",
)

name

A unique name for this target.

failure_templ

file_ext

join_on

success_templ


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

The implementation function of the unit test.

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

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.


analysistest.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", "analysistest")

analysistest.begin(
    # The Starlark context
    ctx = None,
)

ctx

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

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

The test environment returned by unittest.begin.

msg

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

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

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

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

The test environment returned by analysistest.begin.

expected_failure_msg

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

The test environment returned by unittest.begin.

expected

The expected value of some computation.

actual

The actual value returned by some computation.

msg

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

The test environment returned by unittest.begin.

condition

A value that will be evaluated in a Boolean context.

msg

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

The test environment returned by unittest.begin.

expected

The expected set resulting from some computation.

actual

The actual set returned by some computation.

msg

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

The test environment returned by unittest.begin.

expected

The expected set resulting from some computation.

actual

The actual set returned by some computation.

msg

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

The test environment returned by unittest.begin.

condition

A value that will be evaluated in a Boolean context.

msg

An optional message that will be printed that describes the failure. If omitted, a default will be used.


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

The implementation function of the unit test.

attrs

An optional dictionary to supplement the attrs passed to the unit test's rule() constructor.


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

The name of the test_suite target, and the prefix of all the test target names.

test_rules

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

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

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

The test environment returned by unittest.begin.

msg

The message to log describing the failure.