ztest_test.h File Reference

Zephyr testing framework _test. More...

#include <zephyr/app_memory/app_memdomain.h>
#include <zephyr/init.h>
#include <zephyr/sys/iterable_sections.h>
#include <stdbool.h>
#include <syscalls/ztest_test.h>

Go to the source code of this file.

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_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)    __ZTEST_EXPECT(_suite_name, _test_name, ZTEST_EXPECTED_RESULT_FAIL)
	Expect a test to fail (mark it passing if it failed)
#define	ZTEST_EXPECT_SKIP(_suite_name, _test_name)    __ZTEST_EXPECT(_suite_name, _test_name, ZTEST_EXPECTED_RESULT_SKIP)
	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)
#define	ZTEST_SUITE_COUNT   (_ztest_suite_node_list_end - _ztest_suite_node_list_start)
#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)
#define	ZTEST_BMEM   K_APP_BMEM(ztest_mem_partition)
#define	ZTEST_SECTION   K_APP_DMEM_SECTION(ztest_mem_partition)
#define	ZTEST(suite, fn)   Z_ZTEST(suite, fn, 0)
	Create and register a new unit test.
#define	ZTEST_USER(suite, fn)   Z_ZTEST(suite, fn, K_USER)
	Define a test function that should run as a user thread.
#define	ZTEST_F(suite, fn)   Z_ZTEST_F(suite, fn, 0)
	Define a test function.
#define	ZTEST_USER_F(suite, fn)   Z_ZTEST_F(suite, fn, K_USER)
	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)    z_ztest_run_test_suite(STRINGIFY(suite), shuffle, suite_iter, case_iter)
	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)
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.
void	sys_clock_tick_set (uint64_t tick)

Variables
struct k_mem_partition	ztest_mem_partition

Detailed Description

Zephyr testing framework _test.

Macro Definition Documentation

ZTEST_BMEM

#define ZTEST_BMEM   K_APP_BMEM(ztest_mem_partition)

ZTEST_DMEM

#define ZTEST_DMEM   K_APP_DMEM(ztest_mem_partition)

ZTEST_EXPECT_FAIL

#define ZTEST_EXPECT_FAIL	(		_suite_name,
			_test_name
	)		__ZTEST_EXPECT(_suite_name, _test_name, ZTEST_EXPECTED_RESULT_FAIL)

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
	)		__ZTEST_EXPECT(_suite_name, _test_name, ZTEST_EXPECTED_RESULT_SKIP)

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_SECTION

#define ZTEST_SECTION   K_APP_DMEM_SECTION(ztest_mem_partition)

ZTEST_SUITE

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

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 (using ztest_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 (see ztest_test_suite for more info)
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)

ZTEST_TEST_COUNT

#define ZTEST_TEST_COUNT   (_ztest_unit_test_list_end - _ztest_unit_test_list_start)

Typedef Documentation

ztest_suite_after_t

typedef void(* ztest_suite_after_t) (void *fixture)

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)

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)

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)

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)

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

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

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

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

sys_clock_tick_set()

void sys_clock_tick_set

(

uint64_t

tick

)

ztest_run_all()

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.

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
	)

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_verify_all_test_suites_ran()

void ztest_verify_all_test_suites_ran

(

void

)

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