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_new.h>

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

struct	ztest_unit_test_stats

struct	ztest_suite_node

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) More...

#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) More...

#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)

#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. More...

#define	ZTEST_USER(suite, fn) Z_ZTEST(suite, fn, K_USER)
	Define a test function that should run as a user thread. More...

#define	ZTEST_F(suite, fn) Z_ZTEST_F(suite, fn, 0)
	Define a test function. More...

#define	ZTEST_USER_F(suite, fn) Z_ZTEST_F(suite, fn, K_USER)
	Define a test function that should run as a user thread. More...

#define	ZTEST_RULE(name, before_each_fn, after_each_fn)
	Define a test rule that will run before/after each unit test. More...

#define	ztest_run_test_suite(suite) z_ztest_run_test_suite(STRINGIFY(suite))
	Run the specified test suite. More...

Typedefs
typedef void (	ztest_suite_setup_t) (void)

typedef void(*	ztest_suite_before_t) (void *fixture)

typedef void(*	ztest_suite_after_t) (void *fixture)

typedef void(*	ztest_suite_teardown_t) (void *fixture)

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

typedef void(*	ztest_rule_cb) (const struct ztest_unit_test test, void data)
	Test rule callback function signature. More...

Enumerations
enum	ztest_expected_result { ZTEST_EXPECTED_RESULT_FAIL = 0 , ZTEST_EXPECTED_RESULT_SKIP }
	The expected result of a test. More...

Functions
void	ztest_run_all (const void *state)

int	ztest_run_test_suites (const void *state)

void	ztest_verify_all_test_suites_ran (void)
	Fails the test if any of the registered tests did not run. More...

void	ztest_test_fail (void)
	Fail the currently running test. More...

void	ztest_test_pass (void)
	Pass the currently running test. More...

void	ztest_test_skip (void)
	Skip the current test. More...

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. More...

void	ztest_simple_1cpu_after (void *data)
	A 'after' function to use in test suites that just need to stop 1cpu. More...

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

Function Documentation

◆ ztest_run_all()

void ztest_run_all ( const void * state )

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.

◆ ztest_run_test_suites()

int ztest_run_test_suites ( const void * state )

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.

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

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ ZTEST_BMEM

◆ ZTEST_DMEM

◆ ZTEST_EXPECT_FAIL

◆ ZTEST_EXPECT_SKIP

◆ ZTEST_SECTION

◆ ZTEST_SUITE

◆ ZTEST_SUITE_COUNT

◆ ZTEST_TEST_COUNT

Typedef Documentation

◆ 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

Function Documentation

◆ ztest_run_all()

◆ ztest_run_test_suites()

◆ ztest_verify_all_test_suites_ran()

Variable Documentation

◆ ztest_mem_partition