Zephyr tests (ztests) in zephyr-bazel

zephyr-bazel is capable of running Zephyr‘s test suites (ztests) hermetically using Bazel’s standard testing workflows.

The ztest Macro

The ztest macro compiles a Zephyr ZTest application and wraps it in an automated Python runner that executes the test, parses the output for success, and reports results back to Bazel.

Usage

To declare a ZTest in your BUILD.bazel, load the ztest macro and define your target:

load("@zephyr-bazel//bazel_overlay:cc_test.bzl", "ztest")

ztest(
    name = "my_integration_test",
    deps = [
        ":test_sources",
    ],
)

Under the hood, this macro:

1. Compiles the executable binary as a zephyr_app named [name]_bin.
2. Generates a Python runner script.
3. Creates a simulator test target (py_test) named [name]_sim.
4. Creates a hardware test target (py_test) named [name]_hw.
5. Creates a unified test_suite named [name] that groups both tests.

Running Tests

You can run the tests using standard bazelisk test:

bazelisk test //path/to:my_integration_test --platforms=@zephyr//boards/native/native_sim:native

By default, the unified test_suite contains both simulator and hardware tests.

• Simulator Tests (_sim) are only compatible with simulator platforms (platforms that have the //boards:sim) that produce host-executable binaries. If you run on a hardware platform, this target will be skipped as incompatible.
• Hardware Tests (_hw) are compatible with actual hardware boards (platforms that have the //boards:hw constraint) and are incompatible with simulator platforms.

When you run with a simulator platform, the _sim test will run and _hw will be skipped. When you run with a hardware platform, the _hw test will run and _sim will be skipped.

Caching and Hardware Execution

• Simulator Tests are fully sandboxed and cached by Bazel.
• Hardware Tests are configured to run with tags = ["local", "exclusive"] to ensure they run locally (not on a remote build grid) and exclusively (one at a time to avoid conflicts on shared hardware).
• By default, hardware test results are cached by Bazel. If the test code and configurations haven't changed, Bazel will reuse the cached test result.
• To disable caching for a test (forcing it to run on the physical hardware every time you invoke bazel test), pass the no-cache tag to the macro:

ztest(
    name = "my_hardware_test",
    tags = ["no-cache"],
    deps = [
        ":test_sources",
    ],
)

Hardware Runners

Hardware tests (_hw targets) use Zephyr's runner infrastructure under the hood to flash the binary to the target device and, in some cases, to reset or debug it. These runners are the same ones used by west flash and west debug.

The runner configuration is defined in the board's setup (specifically in board_runner_config and runners.yaml).

For more information on how Zephyr runners work and how to write or configure custom runners, refer to the official Zephyr documentation:

• Zephyr Flash & Debug Runners

Manual Execution (Legacy/Debugging)

While bazelisk test is the preferred way to run tests, you can still build the underlying binary and run it manually for debugging.

The zephyr_app target is named [name]_bin. To build it for native_sim:

bazelisk build //path/to:my_integration_test_bin --platforms=@zephyr//boards/native/native_sim:native

After building, you can find the binary in bazel-bin and run it directly:

./bazel-bin/path/to/my_integration_test_bin