Skip to content

ZTest

ZTest is a testing framework, which comes bundled with Zephyr. This document should serve as a quick overview only, for more information please refer to the official documentation.

Overall Structure

Ztest is intended to run inside a regular Zephyr application. This means you would usually need at least the following files in your project:

  • a CMakeLists.txt file
  • a prj.conf, containing at least CONFIG_ZTEST=y
  • at least one source file (.c or .cpp) containing the actual tests
  • usually a testcase.yaml for Twister integration

Take a look at the demo project in the tests/ directory for a truly minimal example.

Test Suite Setup

Inside the source file, you need to create a test suite with the ZTEST_SUITE() macro. For the test suite, you can optionally specify a setup function (runs once before all tests), a before function (runs before each test case), an after function (runs after each test case), and a teardown function (runs once after all tests).

ZTEST_SUITE(test_suite_name, NULL, setup, before, after, teardown);

For more details see the upstream docs.

Test Cases

You can add test cases to your test suite with the ZTEST() macro. This macro does some weird stuff under the hood, but basically it creates a function which will be called by the ZTest framework when the test is run.

What goes into the test function is up to you.

ZTEST(test_suite_name, test_answer_is_42)
{
    zassert_equal(42, 6 * 7);
}

See the list of assertions for a list of zassert_*() functions you can use inside your test cases.

When an assertion fails, the test case will abort and be declared as failed, but other test cases will continue to run.

Running Tests

As the tests are regular Zephyr applications, they can be compiled, flashed and run just like any other application.

Use your regular west build, west flash and console commands to run the tests. Results will be printed to the console.

Example

See below for one of the most basic test projects you can create.

# CMakeLists.txt
cmake_minimum_required(VERSION 3.20.0)

find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(demo_test)

target_sources(app PRIVATE main.c)

# prj.conf
CONFIG_ZTEST=y

// main.c

#include <zephyr/ztest.h>

ZTEST_SUITE(demo_suite, NULL, NULL, NULL, NULL, NULL);

ZTEST(demo_suite, test_answer_is_42)
{
    zassert_equal(42, 6 * 7);
}

As this is a Zephyr application without any hardware dependencies, it can be easily run in simulation.

$ west build -b native_sim tests/demo
-- west build: generating a build system
Loading Zephyr default modules (Zephyr base).
[...]
Generating files from build/zephyr/zephyr.elf for board: native_sim

$ west build -t run
-- west build: running target run
[1/2] cd /home/lasse/src/zephyr/bms/project/build && /home/lasse/src/zephyr/bms/project/build/zephyr/zephyr.exe
*** Booting Zephyr OS build v3.6.0+starcopter-04 ***
Running TESTSUITE demo_suite
===================================================================
START - test_answer_is_42
 PASS - test_answer_is_42 in 0.000 seconds
===================================================================
TESTSUITE demo_suite succeeded

------ TESTSUITE SUMMARY START ------

SUITE PASS - 100.00% [demo_suite]: pass = 1, fail = 0, skip = 0, total = 1 duration = 0.000 seconds
 - PASS - [demo_suite.test_answer_is_42] duration = 0.000 seconds

------ TESTSUITE SUMMARY END ------

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

Next Steps

Browse through the test cases in this repository, maybe take a peek at the tests in the Zephyr repository, and read the upstream docs for more information on ZTest itself.

If you're comfortable with ZTest, continue to the next part to see how to automate running multiple test suites in different environments with Twister.