1# Test suites 2 3The `test_suite` macro is a front-end for easily instantiating groups of 4Starlark tests. It can handle both analysis tests and unit tests. Under the 5hood, each test is its own target with an aggregating `native.test_suite` 6for the group of tests. 7 8## Basic tests 9 10Basic tests are tests that don't require any custom setup or attributes. This is 11the common case for tests of utility code that doesn't interact with objects 12only available to rules (e.g. Targets). These tests are created using 13`unit_test`. 14 15To write such a test, simply write a `unit_test` compatible function (one that 16accepts `env`) and pass it to `test_suite.basic_tests`. 17 18```starlark 19# BUILD 20 21load(":my_tests.bzl", "my_test_suite") 22load("@rules_testing//lib:test_suite.bzl", "test_suite") 23 24my_test_suite(name = "my_tests") 25 26# my_tests.bzl 27 28def _foo_test(env): 29 env.expect.that_str(...).equals(...) 30 31def my_test_suite(name): 32 test_suite( 33 name = name, 34 basic_tests = [ 35 _foo_test, 36 ] 37 ) 38``` 39 40Note that it isn't _required_ to write a custom test suite function, but doing 41so is preferred because it's uncommon for BUILD files to pass around function 42objects, and tools won't be confused by it. 43 44## Regular tests 45 46A regular test is a macro that acts as a setup function and is expected to 47create a target of the given name (which is added to the underlying test suite). 48 49The setup function can perform arbitrary logic, but in the end, it's expected to 50call `unit_test` or `analysis_test` to create a target with the provided name. 51 52If you're writing an `analysis_test`, then you're writing a regular test. 53 54```starlark 55# my_tests.bzl 56def _foo_test(name): 57 analysis_test( 58 name = name, 59 impl = _foo_test_impl, 60 attrs = {"myattr": attr.string(default="default")} 61 ) 62 63def _foo_test_impl(env): 64 env.expect.that_str(...).equals(...) 65 66def my_test_suite(name): 67 test_suite( 68 name = name, 69 tests = [ 70 _foo_test, 71 ] 72 ) 73``` 74 75Note that a using a setup function with `unit_test` test is not required to 76define custom attributes; the above is just an example. If you want to define 77custom attributes for every test in a suite, the `test_kwargs` argument of 78`test_suite` can be used to pass additional arguments to all tests in the suite. 79