docs/ztests.md

# Zephyr tests (ztests) in zephyr-bazel

zephyr-bazel is capable of running Zephyr's test suites (ztests) and uses them
to ensure build correctness. Ztests are treated like regular apps. Script-generated
BUILD.bazel files exist for every ztest directory (directory with a
testcase.yaml file) and contains a `zephyr_app()` Bazel target. For example,
the `tests/kernel/fifo/fifo_api/` directory contains the following generated snippet:

```
zephyr_app(
    name = package_name().split("/")[-1],
    deps = [":main"],
)

zephyr_cc_library(
    name = "main",
    visibility = ["//visibility:private"],
    srcs = glob(["**/*.c"]) + glob(["**/*.h"], allow_empty=True),
)
```

During analysis phase, the name of the `zephyr_app` expands to `fifo_api`. The
user can build this particular ztest for the nrf52833 board by running:

```bash
bazelisk build --lockfile_mode=off  \
@zephyr//tests/kernel/fifo/fifo_api \
--platforms=@zephyr//boards/nordic/nrf52833dk:nrf52833
```

To build the `fifo_api` test for the native_sim board:
```bash
bazelisk build --lockfile_mode=off  \
@zephyr//tests/kernel/fifo/fifo_api \
--platforms=@zephyr//boards/native/native_sim
```

After building for the native_sim, you can directly run the ztest binary:
```bash
ztests$ bazel-bin/external/zephyr-bazel++zephyr_patch_file+zephyr/tests/kernel/fifo/fifo_api/fifo_api
*** Booting Zephyr OS build v4.3.0-0 ***
Running TESTSUITE fifo_api

...

===================================================================
PROJECT EXECUTION SUCCESSFUL
```