Unit tests

Unit tests are for Starlark code that isn’t specific to analysis-phase or loading phase cases; usually utility code of some sort. Such tests typically don’t require a rule ctx or instantiating other targets to verify the code under test.

To write such a test, simply write a function accepting env and pass it to test_suite. The test suite will pass your verification function to unit_test() for you.

# BUILD

load(":my_tests.bzl", "my_test_suite")
load("@rules_testing//lib:test_suite.bzl", "test_suite")

my_test_suite(name = "my_tests")

# my_tests.bzl

def _foo_test(env):
  env.expect.that_str(...).equals(...)

def my_test_suite(name):
  test_suite(
    name = name,
    basic_tests = [
      _foo_test,
    ]
  )

Note that it isn’t required to write a custom test suite function, but doing so is preferred because it’s uncommon for BUILD files to pass around function objects, and tools won’t be confused by it.

Customizing setup

If you want to customize the setup (loading phase) of a unit test, e.g. to add custom attributes, then you need to write in the same style as an analysis test: one function is a verification function, and another function performs setup and calls unit_test(), passing in the verification function.

Custom tests are like basic tests, except you can hook into the loading phase before the actual unit test is defined. Because you control the invocation of unit_test, you can e.g. define custom attributes specific to the test.

# my_tests.bzl
def _foo_test(name):
  unit_test(
    name = name,
    impl = _foo_test_impl,
    attrs = {"myattr": attr.string(default="default")}
  )

def _foo_test_impl(env):
  env.expect.that_str(...).equals(...)

def my_test_suite(name):
  test_suite(
    name = name,
    custom_tests = [
      _foo_test,
    ]
  )

Note that a custom test is not required to define custom attributes; the above is just an example. If you want to define custom attributes for every test in a suite, the test_kwargs argument of test_suite can be used to pass additional arguments to all tests in the suite.