This module eases the testing process by providing helpful macros and other testing structures. More...

Data Structures
struct	ztest_expected_result_entry
	A single expectation entry allowing tests to fail/skip and be considered passing. More...
struct	ztest_unit_test
struct	ztest_param_values
	Parameter value set for value-parameterized tests. More...
struct	ztest_param_inst
	Registration entry mapping a test to a parameter value set. More...
struct	ztest_suite_stats
	Stats about a ztest suite. More...
struct	ztest_unit_test_stats
struct	ztest_suite_node
	A single node of test suite. More...
struct	ztest_arch_api
	Structure for architecture specific APIs. More...

Macros
#define	ZTEST_EXPECT_FAIL(_suite_name, _test_name)
	Expect a test to fail (mark it passing if it failed).
#define	ZTEST_EXPECT_SKIP(_suite_name, _test_name)
	Expect a test to skip (mark it passing if it failed).
#define	ZTEST_TEST_COUNT (_ztest_unit_test_list_end - _ztest_unit_test_list_start)
	Number of registered unit tests.
#define	ZTEST_PARAM_INST_COUNT (_ztest_param_inst_list_end - _ztest_param_inst_list_start)
	Number of registered value-parameterized test instantiations.
#define	ZTEST_SUITE_COUNT (_ztest_suite_node_list_end - _ztest_suite_node_list_start)
	Number of registered test suites.
#define	ZTEST_SUITE(SUITE_NAME, PREDICATE, setup_fn, before_fn, after_fn, teardown_fn)
	Create and register a ztest suite.
#define	ZTEST_DMEM K_APP_DMEM(ztest_mem_partition)
	Make data section used by Ztest userspace accessible.
#define	ZTEST_BMEM K_APP_BMEM(ztest_mem_partition)
	Make bss section used by Ztest userspace accessible.
#define	ZTEST_SECTION K_APP_DMEM_SECTION(ztest_mem_partition)
	Ztest data section for accessing data from userspace.
#define	ZTEST_GET_PARAM_PTR(type)
	Get current parameter as a typed pointer.
#define	ZTEST_GET_PARAM(type)
	Get current parameter as a typed value.
#define	ZTEST_DEFINE_PARAM_VALUES(name_, type_, ...)
	Declare a static value set for use with ZTEST_INSTANTIATE_TEST_SUITE_P().
#define	ZTEST_DEFINE_PARAM_VALUES_ARRAY(name_, array_)
	Declare a static value set from an existing array.
#define	ZTEST_DEFINE_PARAM_RANGE(name_, type_, begin_, end_, step_)
	Declare a numeric range for use with ZTEST_INSTANTIATE_TEST_SUITE_P().
#define	ZTEST_DEFINE_PARAM_GENERATOR(name_, type_, count_, gen_cb_)
	Declare a runtime-generated parameter set.
#define	ZTEST_DEFINE_PARAM_GENERATOR_WITH_SETUP(name_, type_, count_, setup_cb_, gen_cb_)
	Declare a runtime-generated parameter set with one-time setup.
#define	ZTEST_INSTANTIATE_TEST_SUITE_P(inst_, suite_, fn_, param_values_name_)
	Instantiate a ZTEST_P test with a set of parameter values.
#define	ZTEST_P(suite, fn)
#define	ZTEST_USER_P(suite, fn)
	Define a value-parameterized test function that runs as a user thread.
#define	ZTEST(suite, fn)
	Create and register a new unit test.
#define	ZTEST_USER(suite, fn)
	Define a test function that should run as a user thread.
#define	ZTEST_F(suite, fn)
	Define a test function.
#define	ZTEST_USER_F(suite, fn)
	Define a test function that should run as a user thread.
#define	ZTEST_RULE(name, before_each_fn, after_each_fn)
	Define a test rule that will run before/after each unit test.
#define	ztest_run_test_suite(suite, shuffle, suite_iter, case_iter, param)
	Run the specified test suite.

Typedefs
typedef void (	ztest_suite_setup_t) (void)
	Setup function to run before running this suite.
typedef void(*	ztest_suite_before_t) (void *fixture)
	Function to run before each test in this suite.
typedef void(*	ztest_suite_after_t) (void *fixture)
	Function to run after each test in this suite.
typedef void(*	ztest_suite_teardown_t) (void *fixture)
	Teardown function to run after running this suite.
typedef bool(*	ztest_suite_predicate_t) (const void *global_state)
	An optional predicate function to determine if the test should run.
typedef void(*	ztest_rule_cb) (const struct ztest_unit_test test, void data)
	Test rule callback function signature.

Enumerations
enum	ztest_expected_result { ZTEST_EXPECTED_RESULT_FAIL = 0 , ZTEST_EXPECTED_RESULT_SKIP }
	The expected result of a test. More...
enum	ztest_result { ZTEST_RESULT_PENDING , ZTEST_RESULT_PASS , ZTEST_RESULT_FAIL , ZTEST_RESULT_SKIP , ZTEST_RESULT_SUITE_SKIP , ZTEST_RESULT_SUITE_FAIL }
	The result of the current running test. More...
enum	ztest_phase { TEST_PHASE_SETUP , TEST_PHASE_BEFORE , TEST_PHASE_TEST , TEST_PHASE_AFTER , TEST_PHASE_TEARDOWN , TEST_PHASE_FRAMEWORK }
	Each enum member represents a distinct phase of execution for the test binary. More...

Functions
void	ztest_run_all (const void *state, bool shuffle, int suite_iter, int case_iter)
	Default entry point for running or listing registered unit tests.
int	ztest_run_test_suites (const void *state, bool shuffle, int suite_iter, int case_iter)
	Run the registered unit tests which return true from their predicate function.
void	ztest_verify_all_test_suites_ran (void)
	Fails the test if any of the registered tests did not run.
void	ztest_test_fail (void)
	Fail the currently running test.
void	ztest_test_pass (void)
	Pass the currently running test.
void	ztest_test_skip (void)
	Skip the current test.
void	ztest_skip_failed_assumption (void)
const void *	ztest_get_current_param (void)
	Returns currently active value-parameterized test argument.
size_t	ztest_get_current_param_index (void)
	Returns index of currently active value-parameterized test argument.
size_t	ztest_get_current_param_size (void)
	Returns size of current parameter element in bytes.
bool	ztest_has_current_param (void)
	Returns true when currently running a value-parameterized test instance.
void	ztest_simple_1cpu_before (void *data)
	A 'before' function to use in test suites that just need to start 1cpu.
void	ztest_simple_1cpu_after (void *data)
	A 'after' function to use in test suites that just need to stop 1cpu.

Variables
struct k_mem_partition	ztest_mem_partition

Detailed Description

This module eases the testing process by providing helpful macros and other testing structures.

Macro Definition Documentation

◆ ZTEST

#define ZTEST	(		suite,
			fn )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:

Z_ZTEST(suite, fn, 0)

Create and register a new unit test.

Calling this macro will create a new unit test and attach it to the declared suite. The suite does not need to be defined in the same compilation unit.

Parameters

suite	The name of the test suite to attach this test
fn	The test function to call.

◆ ZTEST_BMEM

#define ZTEST_BMEM K_APP_BMEM(ztest_mem_partition)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Make bss section used by Ztest userspace accessible.

◆ ZTEST_DEFINE_PARAM_GENERATOR

#define ZTEST_DEFINE_PARAM_GENERATOR	(	name_,
		type_,
		count_,
		gen_cb_ )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:

BUILD_ASSERT(sizeof(type_) <= 16U,                                                   \
             "ZTEST_DEFINE_PARAM_GENERATOR: type too large for scratch buffer");     \
static const struct ztest_param_values name_ = {                                     \
        .values      = NULL,                                                         \
        .count       = (count_),                                                     \
        .elem_size   = sizeof(type_),                                                \
        .name_cb     = NULL,                                                         \
        .value_at_cb = (gen_cb_),                                                    \
        .setup_cb    = NULL,                                                         \
}

Declare a runtime-generated parameter set.

gen_cb_ is called once per invocation with the 0-based iteration index and a pointer to an aligned scratch buffer; it must write exactly sizeof(type_) bytes into that buffer. The callback may read any runtime state — random numbers, hardware registers, computed values, etc.

Values are never stored in an array; count_ iterations cost no extra RAM regardless of type size.

For generators that require one-time initialisation (e.g. seeding a PRNG) use ZTEST_DEFINE_PARAM_GENERATOR_WITH_SETUP() instead.

Constraint (checked at compile time): sizeof(type_) must not exceed 16 bytes.

Parameters

name_	Identifier for the resulting variable.
type_	C type of each generated value.
count_	Number of invocations (constant expression).
gen_cb_	Generator: void ()(size_t index, void out).

◆ ZTEST_DEFINE_PARAM_GENERATOR_WITH_SETUP

#define ZTEST_DEFINE_PARAM_GENERATOR_WITH_SETUP	(	name_,
		type_,
		count_,
		setup_cb_,
		gen_cb_ )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:

BUILD_ASSERT(sizeof(type_) <= 16U,                                                   \
             "ZTEST_DEFINE_PARAM_GENERATOR_WITH_SETUP: type too large");             \
static const struct ztest_param_values name_ = {                                     \
        .values      = NULL,                                                         \
        .count       = (count_),                                                     \
        .elem_size   = sizeof(type_),                                                \
        .name_cb     = NULL,                                                         \
        .value_at_cb = (gen_cb_),                                                    \
        .setup_cb    = (setup_cb_),                                                  \
}

Declare a runtime-generated parameter set with one-time setup.

Identical to ZTEST_DEFINE_PARAM_GENERATOR() but also registers setup_cb_, which is called once before the first iteration of the dispatch loop. Use this to seed a PRNG, reset a stateful counter, or perform any other per-test-run initialisation that must happen before values are generated.

Example — reproducible fuzz testing:

static void seed_rng(void) { sys_rand_seed(MY_FUZZ_SEED); }
static void rand_u32(size_t idx, void *out)
{
    ARG_UNUSED(idx);
    *(uint32_t *)out = sys_rand32_get();
}
ZTEST_DEFINE_PARAM_GENERATOR_WITH_SETUP(fuzz_vals, uint32_t,
                                        MY_FUZZ_ITERATIONS,
                                        seed_rng, rand_u32);

Parameters

name_	Identifier for the resulting variable.
type_	C type of each generated value.
count_	Number of invocations (constant expression).
setup_cb_	Setup: void (*)(void) — called once before iteration 0.
gen_cb_	Generator: void ()(size_t index, void out).

◆ ZTEST_DEFINE_PARAM_RANGE

#define ZTEST_DEFINE_PARAM_RANGE	(	name_,
		type_,
		begin_,
		end_,
		step_ )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:

BUILD_ASSERT((end_) > (begin_), "ZTEST_DEFINE_PARAM_RANGE: end must be > begin"); \
BUILD_ASSERT((step_) > 0, "ZTEST_DEFINE_PARAM_RANGE: step must be > 0");          \
BUILD_ASSERT(sizeof(type_) <= 16U,                                                   \
             "ZTEST_DEFINE_PARAM_RANGE: type too large for scratch buffer");        \
static void z_ztest_range_value_at_##name_(size_t z_idx_, void *z_out_)             \
{                                                                                    \
        type_ z_val_ = (type_)(begin_) + (type_)(step_) * (type_)(z_idx_);         \
        *(type_ *)z_out_ = z_val_;                                                   \
}                                                                                    \
static const struct ztest_param_values name_ = {                                     \
        .values      = NULL,                                                         \
        .count       = (size_t)(((end_) - (begin_) - 1) / (step_) + 1),             \
        .elem_size   = sizeof(type_),                                                \
        .name_cb     = NULL,                                                         \
        .value_at_cb = z_ztest_range_value_at_##name_,                              \
        .setup_cb    = NULL,                                                         \
}

Declare a numeric range for use with ZTEST_INSTANTIATE_TEST_SUITE_P().

Modelled on GoogleTest's testing::Range(begin, end [, step]). The range is half-open: values are {begin, begin+step, begin+2*step, ...} up to (but not including) end_. step_ defaults to 1 when omitted.

Values are computed on demand via a generated callback — no array is allocated, so arbitrarily large ranges have zero RAM cost.

Constraints (checked at compile time):

end_ > begin_
step_ > 0
sizeof(type_) must not exceed 16 bytes

Parameters

name_	Identifier for the resulting variable.
type_	Scalar C type (e.g. int, uint32_t).
begin_	First value in the range (inclusive).
end_	Upper bound of the range (exclusive).
step_	Increment between successive values (default 1).

◆ ZTEST_DEFINE_PARAM_VALUES

#define ZTEST_DEFINE_PARAM_VALUES	(	name_,
		type_,
		... )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:

static const type_ z_ztest_param_arr_##name_[] = {__VA_ARGS__};                     \
static const struct ztest_param_values name_ = {                                     \
        .values       = z_ztest_param_arr_##name_,                                   \
        .count        = ARRAY_SIZE(z_ztest_param_arr_##name_),                       \
        .elem_size    = sizeof(type_),                                                \
        .name_cb      = NULL,                                                        \
        .value_at_cb  = NULL,                                                        \
        .setup_cb     = NULL,                                                        \
}

Declare a static value set for use with ZTEST_INSTANTIATE_TEST_SUITE_P().

Creates a named static const struct ztest_param_values backed by the supplied literal values. The resulting name is passed directly to ZTEST_INSTANTIATE_TEST_SUITE_P().

Parameters

name_	Identifier for the resulting variable.
type_	C type of each individual parameter value.
...	Comma-separated list of parameter values.

◆ ZTEST_DEFINE_PARAM_VALUES_ARRAY

#define ZTEST_DEFINE_PARAM_VALUES_ARRAY	(		name_,
			array_ )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:

static const struct ztest_param_values name_ = {                                     \
        .values      = (array_),                                                     \
        .count       = ARRAY_SIZE(array_),                                           \
        .elem_size   = sizeof((array_)[0]),                                          \
        .name_cb     = NULL,                                                         \
        .value_at_cb = NULL,                                                         \
        .setup_cb    = NULL,                                                         \
}

Declare a static value set from an existing array.

Parameters

name_	Identifier for the resulting variable.
array_	Array of parameter values (must be in scope at call site).

◆ ZTEST_DMEM

#define ZTEST_DMEM K_APP_DMEM(ztest_mem_partition)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Make data section used by Ztest userspace accessible.

◆ ZTEST_EXPECT_FAIL

#define ZTEST_EXPECT_FAIL	(		_suite_name,
			_test_name )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:

__ZTEST_EXPECT(_suite_name, _test_name, ZTEST_EXPECTED_RESULT_FAIL)

ZTEST_EXPECTED_RESULT_FAIL

@ ZTEST_EXPECTED_RESULT_FAIL

Expect a test to fail.

Definition ztest_test.h:50

Expect a test to fail (mark it passing if it failed).

Adding this macro to your logic will allow the failing test to be considered passing, example:

ZTEST_EXPECT_FAIL(my_suite, test_x);
ZTEST(my_suite, text_x) {
  zassert_true(false, NULL);
}

Parameters

_suite_name	The name of the suite
_test_name	The name of the test

◆ ZTEST_EXPECT_SKIP

#define ZTEST_EXPECT_SKIP	(		_suite_name,
			_test_name )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:

__ZTEST_EXPECT(_suite_name, _test_name, ZTEST_EXPECTED_RESULT_SKIP)

ZTEST_EXPECTED_RESULT_SKIP

@ ZTEST_EXPECTED_RESULT_SKIP

Expect a test to pass.

Definition ztest_test.h:51

Expect a test to skip (mark it passing if it failed).

Adding this macro to your logic will allow the failing test to be considered passing, example:

ZTEST_EXPECT_SKIP(my_suite, test_x);
ZTEST(my_suite, text_x) {
  zassume_true(false, NULL);
}

Parameters

_suite_name	The name of the suite
_test_name	The name of the test

◆ ZTEST_F

#define ZTEST_F	(		suite,
			fn )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:

Z_ZTEST_F(suite, fn, 0)

Define a test function.

This macro behaves exactly the same as ZTEST(), but the function takes an argument for the fixture of type struct suite##_fixture* named fixture.

Parameters

suite	The name of the test suite to attach this test
fn	The test function to call.

◆ ZTEST_GET_PARAM

#define ZTEST_GET_PARAM ( type )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:

(*ZTEST_GET_PARAM_PTR(type))

ZTEST_GET_PARAM_PTR

#define ZTEST_GET_PARAM_PTR(type)

Get current parameter as a typed pointer.

Definition ztest_test.h:494

Get current parameter as a typed value.

◆ ZTEST_GET_PARAM_PTR

#define ZTEST_GET_PARAM_PTR ( type )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:

((const type *)ztest_get_current_param())

ztest_get_current_param

const void * ztest_get_current_param(void)

Returns currently active value-parameterized test argument.

Get current parameter as a typed pointer.

◆ ZTEST_INSTANTIATE_TEST_SUITE_P

#define ZTEST_INSTANTIATE_TEST_SUITE_P	(	inst_,
		suite_,
		fn_,
		param_values_name_ )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:

static const STRUCT_SECTION_ITERABLE(                                                \
        ztest_param_inst,                                                            \
        UTIL_CAT(UTIL_CAT(z_ztest_param_inst_, suite_),                              \
                 UTIL_CAT(_, UTIL_CAT(fn_, UTIL_CAT(_, inst_))))) = {               \
        .test_suite_name = STRINGIFY(suite_),                                        \
        .test_name       = STRINGIFY(fn_),                                           \
        .instance_name   = STRINGIFY(inst_),                                         \
        .values          = &(param_values_name_),                                    \
}

Instantiate a ZTEST_P test with a set of parameter values.

Registers a struct ztest_param_inst entry in the ztest_param_inst linker section. During suite execution the framework calls fn once per value in param_values_name, setting the per-invocation parameter context before each call. Inside the test body use ztest_get_current_param() or the typed helper ZTEST_GET_PARAM() to retrieve the current value.

The suite fixture returned by setup() is passed as the data argument of the ZTEST_P function and is never overwritten by the parameter.

Parameters

inst_	Unique identifier for this instantiation.
suite_	Suite name (must match the ZTEST_SUITE declaration).
fn_	Test name (must be declared with ZTEST_P).
param_values_name_	Name of a variable declared with ZTEST_DEFINE_PARAM_VALUES() or ZTEST_DEFINE_PARAM_VALUES_ARRAY().

◆ ZTEST_P

#define ZTEST_P	(		suite,
			fn )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:

Z_TEST_P(suite, fn, 0)

◆ ZTEST_PARAM_INST_COUNT

#define ZTEST_PARAM_INST_COUNT (_ztest_param_inst_list_end - _ztest_param_inst_list_start)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Number of registered value-parameterized test instantiations.

◆ ZTEST_RULE

#define ZTEST_RULE	(	name,
		before_each_fn,
		after_each_fn )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:

static STRUCT_SECTION_ITERABLE(ztest_test_rule, z_ztest_test_rule_##name) = {              \
        .before_each = (before_each_fn),                                                   \
        .after_each = (after_each_fn),                                                     \
}

Define a test rule that will run before/after each unit test.

Functions defined here will run before/after each unit test for every test suite. Along with the callback, the test functions are provided a pointer to the test being run, and the data. This provides a mechanism for tests to perform custom operations depending on the specific test or the data (for example logging may use the test's name).

Ordering:

Test rule's before function will run before the suite's before function. This is done to allow the test suite's customization to take precedence over the rule which is applied to all suites.
Test rule's after function is not guaranteed to run in any particular order.

Parameters

name	The name for the test rule (must be unique within the compilation unit)
before_each_fn	The callback function (ztest_rule_cb) to call before each test (may be NULL)
after_each_fn	The callback function (ztest_rule_cb) to call after each test (may be NULL)

◆ ztest_run_test_suite

#define ztest_run_test_suite	(	suite,
		shuffle,
		suite_iter,
		case_iter,
		param )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:

z_ztest_run_test_suite(STRINGIFY(suite), shuffle, suite_iter, case_iter, param)

Run the specified test suite.

Parameters

suite	Test suite to run.
shuffle	Shuffle tests
suite_iter	Test suite repetitions.
case_iter	Test case repetitions.
param	Test parameter

◆ ZTEST_SECTION

#define ZTEST_SECTION K_APP_DMEM_SECTION(ztest_mem_partition)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Ztest data section for accessing data from userspace.

◆ ZTEST_SUITE

#define ZTEST_SUITE	(	SUITE_NAME,
		PREDICATE,
		setup_fn,
		before_fn,
		after_fn,
		teardown_fn )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:

struct ztest_suite_stats UTIL_CAT(z_ztest_suite_node_stats_, SUITE_NAME);                  \
static const STRUCT_SECTION_ITERABLE(ztest_suite_node,                                     \
                                     UTIL_CAT(z_ztest_test_node_, SUITE_NAME)) = {         \
        .name = STRINGIFY(SUITE_NAME),                                                     \
        .setup = (setup_fn),                                                               \
        .before = (before_fn),                                                             \
        .after = (after_fn),                                                               \
        .teardown = (teardown_fn),                                                         \
        .predicate = PREDICATE,                                                            \
        .stats = &UTIL_CAT(z_ztest_suite_node_stats_, SUITE_NAME),             \
}

Create and register a ztest suite.

Using this macro creates a new test suite. It then creates a struct ztest_suite_node in a specific linker section.

Tests can then be run by calling ztest_run_test_suites(const void *state) by passing in the current state. See the documentation for ztest_run_test_suites for more info.

Parameters

SUITE_NAME	The name of the suite
PREDICATE	A function to test against the state and determine if the test should run.
setup_fn	The setup function to call before running this test suite
before_fn	The function to call before each unit test in this suite
after_fn	The function to call after each unit test in this suite
teardown_fn	The function to call after running all the tests in this suite

◆ ZTEST_SUITE_COUNT

#define ZTEST_SUITE_COUNT (_ztest_suite_node_list_end - _ztest_suite_node_list_start)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Number of registered test suites.

◆ ZTEST_TEST_COUNT

#define ZTEST_TEST_COUNT (_ztest_unit_test_list_end - _ztest_unit_test_list_start)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Number of registered unit tests.

◆ ZTEST_USER

#define ZTEST_USER	(		suite,
			fn )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:

Z_ZTEST(suite, fn, K_USER)

K_USER

#define K_USER

user mode thread

Definition kernel.h:293

Define a test function that should run as a user thread.

This macro behaves exactly the same as ZTEST, but calls the test function in user space if CONFIG_USERSPACE was enabled.

Parameters

suite	The name of the test suite to attach this test
fn	The test function to call.

◆ ZTEST_USER_F

#define ZTEST_USER_F	(		suite,
			fn )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:

Z_ZTEST_F(suite, fn, K_USER)

Define a test function that should run as a user thread.

If CONFIG_USERSPACE is not enabled, this is functionally identical to ZTEST_F(). The test function takes a single fixture argument of type struct suite##_fixture* named fixture.

Parameters

suite	The name of the test suite to attach this test
fn	The test function to call.

◆ ZTEST_USER_P

#define ZTEST_USER_P	(		suite,
			fn )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:

Z_TEST_P(suite, fn, K_USER)

Define a value-parameterized test function that runs as a user thread.

Behaves exactly like ZTEST_P() but spawns the test thread with the K_USER flag so the test body executes in user space when CONFIG_USERSPACE is enabled. Use this instead of ZTEST_P() when the code under test is a syscall or must otherwise be exercised from an unprivileged context.

Parameters

suite	The name of the test suite to attach this test.
fn	The test function to call (must be paired with ZTEST_INSTANTIATE_TEST_SUITE_P()).

Typedef Documentation

◆ ztest_rule_cb

typedef void(* ztest_rule_cb) (const struct ztest_unit_test *test, void *data)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Test rule callback function signature.

The function signature that can be used to register a test rule's before/after callback. This provides access to the test and the fixture data (if provided).

Parameters

test	Pointer to the unit test in context
data	Pointer to the test's fixture data (may be NULL)

◆ ztest_suite_after_t

typedef void(* ztest_suite_after_t) (void *fixture)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Function to run after each test in this suite.

Parameters

fixture The test suite's fixture returned from setup()

◆ ztest_suite_before_t

typedef void(* ztest_suite_before_t) (void *fixture)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Function to run before each test in this suite.

Parameters

fixture The test suite's fixture returned from setup()

◆ ztest_suite_predicate_t

typedef bool(* ztest_suite_predicate_t) (const void *global_state)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

An optional predicate function to determine if the test should run.

If NULL, then the test will only run once on the first attempt.

Parameters

global_state The current state of the test application.

Returns: True if the suite should be run; false to skip.

◆ ztest_suite_setup_t

typedef void *(* ztest_suite_setup_t) (void)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Setup function to run before running this suite.

Returns: Pointer to the data structure that will be used throughout this test suite

◆ ztest_suite_teardown_t

typedef void(* ztest_suite_teardown_t) (void *fixture)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Teardown function to run after running this suite.

Parameters

fixture The test suite's data returned from setup()

Enumeration Type Documentation

◆ ztest_expected_result

enum ztest_expected_result

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

The expected result of a test.

See also: ZTEST_EXPECT_FAIL; ZTEST_EXPECT_SKIP

Enumerator
ZTEST_EXPECTED_RESULT_FAIL	Expect a test to fail.
ZTEST_EXPECTED_RESULT_SKIP	Expect a test to pass.

◆ ztest_phase

enum ztest_phase

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Each enum member represents a distinct phase of execution for the test binary.

TEST_PHASE_FRAMEWORK is active when internal ztest code is executing; the rest refer to corresponding phases of user test code.

Enumerator
TEST_PHASE_SETUP
TEST_PHASE_BEFORE
TEST_PHASE_TEST
TEST_PHASE_AFTER
TEST_PHASE_TEARDOWN
TEST_PHASE_FRAMEWORK

◆ ztest_result

enum ztest_result

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

The result of the current running test.

It's possible that the setup function sets the result to ZTEST_RESULT_SUITE_* which will apply the failure/skip to every test in the suite.

Enumerator
ZTEST_RESULT_PENDING
ZTEST_RESULT_PASS
ZTEST_RESULT_FAIL
ZTEST_RESULT_SKIP
ZTEST_RESULT_SUITE_SKIP
ZTEST_RESULT_SUITE_FAIL

Function Documentation

◆ ztest_get_current_param()

const void * ztest_get_current_param ( void )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Returns currently active value-parameterized test argument.

For non-parameterized tests this returns NULL.

◆ ztest_get_current_param_index()

size_t ztest_get_current_param_index ( void )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Returns index of currently active value-parameterized test argument.

For non-parameterized tests this returns 0.

◆ ztest_get_current_param_size()

size_t ztest_get_current_param_size ( void )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Returns size of current parameter element in bytes.

For non-parameterized tests this returns 0.

◆ ztest_has_current_param()

bool ztest_has_current_param ( void )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Returns true when currently running a value-parameterized test instance.

◆ ztest_run_all()

void ztest_run_all	(	const void *	state,
		bool	shuffle,
		int	suite_iter,
		int	case_iter )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Default entry point for running or listing registered unit tests.

Parameters

state	The current state of the machine as it relates to the test executable.
shuffle	Shuffle tests
suite_iter	Test suite repetitions.
case_iter	Test case repetitions.

◆ ztest_run_test_suites()

int ztest_run_test_suites	(	const void *	state,
		bool	shuffle,
		int	suite_iter,
		int	case_iter )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Run the registered unit tests which return true from their predicate function.

Parameters

state	The current state of the machine as it relates to the test executable.
shuffle	Shuffle tests
suite_iter	Test suite repetitions.
case_iter	Test case repetitions.

Returns: The number of tests that ran.

◆ ztest_simple_1cpu_after()

void ztest_simple_1cpu_after ( void * data )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

A 'after' function to use in test suites that just need to stop 1cpu.

Ignores data, and calls z_test_1cpu_stop()

Parameters

data	The test suite's data

◆ ztest_simple_1cpu_before()

void ztest_simple_1cpu_before ( void * data )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

A 'before' function to use in test suites that just need to start 1cpu.

Ignores data, and calls z_test_1cpu_start()

Parameters

data	The test suite's data

◆ ztest_skip_failed_assumption()

void ztest_skip_failed_assumption ( void )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

◆ ztest_test_fail()

void ztest_test_fail ( void )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Fail the currently running test.

This is the function called from failed assertions and the like. You probably don't need to call it yourself.

◆ ztest_test_pass()

void ztest_test_pass ( void )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Pass the currently running test.

Normally a test passes just by returning without an assertion failure. However, if the success case for your test involves a fatal fault, you can call this function from k_sys_fatal_error_handler to indicate that the test passed before aborting the thread.

◆ ztest_test_skip()

void ztest_test_skip ( void )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Skip the current test.

◆ ztest_verify_all_test_suites_ran()

void ztest_verify_all_test_suites_ran ( void )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Fails the test if any of the registered tests did not run.

When registering test suites, a pragma function can be provided to determine WHEN the test should run. It is possible that a test suite could be registered but the pragma always prevents it from running. In cases where a test should make sure that ALL suites ran at least once, this function may be called at the end of test_main(). It will cause the test to fail if any suite was registered but never ran.

Variable Documentation

◆ ztest_mem_partition

struct k_mem_partition ztest_mem_partition

extern

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ ZTEST

◆ ZTEST_BMEM

◆ ZTEST_DEFINE_PARAM_GENERATOR

◆ ZTEST_DEFINE_PARAM_GENERATOR_WITH_SETUP

◆ ZTEST_DEFINE_PARAM_RANGE

◆ ZTEST_DEFINE_PARAM_VALUES

◆ ZTEST_DEFINE_PARAM_VALUES_ARRAY

◆ ZTEST_DMEM

◆ ZTEST_EXPECT_FAIL

◆ ZTEST_EXPECT_SKIP

◆ ZTEST_F

◆ ZTEST_GET_PARAM

◆ ZTEST_GET_PARAM_PTR

◆ ZTEST_INSTANTIATE_TEST_SUITE_P

◆ ZTEST_P

◆ ZTEST_PARAM_INST_COUNT

◆ ZTEST_RULE

◆ ztest_run_test_suite

◆ ZTEST_SECTION

◆ ZTEST_SUITE

◆ ZTEST_SUITE_COUNT

◆ ZTEST_TEST_COUNT

◆ ZTEST_USER

◆ ZTEST_USER_F

◆ ZTEST_USER_P

Typedef Documentation

◆ ztest_rule_cb

◆ ztest_suite_after_t

◆ ztest_suite_before_t

◆ ztest_suite_predicate_t

◆ ztest_suite_setup_t

◆ ztest_suite_teardown_t

Enumeration Type Documentation

◆ ztest_expected_result

◆ ztest_phase

◆ ztest_result

Function Documentation

◆ ztest_get_current_param()

◆ ztest_get_current_param_index()

◆ ztest_get_current_param_size()

◆ ztest_has_current_param()

◆ ztest_run_all()

◆ ztest_run_test_suites()

◆ ztest_simple_1cpu_after()

◆ ztest_simple_1cpu_before()

◆ ztest_skip_failed_assumption()

◆ ztest_test_fail()

◆ ztest_test_pass()

◆ ztest_test_skip()

◆ ztest_verify_all_test_suites_ran()

Variable Documentation

◆ ztest_mem_partition