Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches

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_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_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_P(suite, fn)
 
#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)
 
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 </home/runner/work/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
suiteThe name of the test suite to attach this test
fnThe test function to call.

◆ ZTEST_BMEM

#define ZTEST_BMEM   K_APP_BMEM(ztest_mem_partition)

#include </home/runner/work/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Make bss section used by Ztest userspace accessible.

◆ ZTEST_DMEM

#define ZTEST_DMEM   K_APP_DMEM(ztest_mem_partition)

#include </home/runner/work/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 </home/runner/work/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
Expect a test to fail.
Definition ztest_test.h:49

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_nameThe name of the suite
_test_nameThe name of the test

◆ ZTEST_EXPECT_SKIP

#define ZTEST_EXPECT_SKIP ( _suite_name,
_test_name )

#include </home/runner/work/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
Expect a test to pass.
Definition ztest_test.h:50

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_nameThe name of the suite
_test_nameThe name of the test

◆ ZTEST_F

#define ZTEST_F ( suite,
fn )

#include </home/runner/work/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
suiteThe name of the test suite to attach this test
fnThe test function to call.

◆ ZTEST_P

#define ZTEST_P ( suite,
fn )

◆ ZTEST_RULE

#define ZTEST_RULE ( name,
before_each_fn,
after_each_fn )

#include </home/runner/work/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 STRUCT_SECTION_ITERABLE(struct_type, varname)
Defines a new element for an iterable section.
Definition iterable_sections.h:216

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
nameThe name for the test rule (must be unique within the compilation unit)
before_each_fnThe callback function (ztest_rule_cb) to call before each test (may be NULL)
after_each_fnThe 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 </home/runner/work/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:
z_ztest_run_test_suite(STRINGIFY(suite), shuffle, suite_iter, case_iter, param)
#define STRINGIFY(s)
Definition common.h:134

Run the specified test suite.

Parameters
suiteTest suite to run.
shuffleShuffle tests
suite_iterTest suite repetitions.
case_iterTest case repetitions.
paramTest parameter

◆ ZTEST_SECTION

#define ZTEST_SECTION   K_APP_DMEM_SECTION(ztest_mem_partition)

#include </home/runner/work/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 </home/runner/work/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:
struct ztest_suite_stats UTIL_CAT(z_ztest_suite_node_stats_, SUITE_NAME); \
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), \
}
A single node of test suite.
Definition ztest_test.h:190
Stats about a ztest suite.
Definition ztest_test.h:127
#define UTIL_CAT(a,...)
Definition util_internal.h:104

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_NAMEThe name of the suite
PREDICATEA function to test against the state and determine if the test should run.
setup_fnThe setup function to call before running this test suite
before_fnThe function to call before each unit test in this suite
after_fnThe function to call after each unit test in this suite
teardown_fnThe 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)

◆ ZTEST_USER

#define ZTEST_USER ( suite,
fn )

#include </home/runner/work/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Value:
Z_ZTEST(suite, fn, K_USER)
#define K_USER
user mode thread
Definition kernel.h:271

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
suiteThe name of the test suite to attach this test
fnThe test function to call.

◆ ZTEST_USER_F

#define ZTEST_USER_F ( suite,
fn )

#include </home/runner/work/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
suiteThe name of the test suite to attach this test
fnThe test function to call.

Typedef Documentation

◆ ztest_rule_cb

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

#include </home/runner/work/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
testPointer to the unit test in context
dataPointer to the test's fixture data (may be NULL)

◆ ztest_suite_after_t

typedef void(* ztest_suite_after_t) (void *fixture)

#include </home/runner/work/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Function to run after each test in this suite.

Parameters
fixtureThe test suite's fixture returned from setup()

◆ ztest_suite_before_t

typedef void(* ztest_suite_before_t) (void *fixture)

#include </home/runner/work/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Function to run before each test in this suite.

Parameters
fixtureThe test suite's fixture returned from setup()

◆ ztest_suite_predicate_t

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

#include </home/runner/work/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_stateThe 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 </home/runner/work/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 </home/runner/work/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Teardown function to run after running this suite.

Parameters
fixtureThe test suite's data returned from setup()

Enumeration Type Documentation

◆ ztest_expected_result

#include </home/runner/work/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

#include </home/runner/work/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

#include </home/runner/work/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_run_all()

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

#include </home/runner/work/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Default entry point for running or listing registered unit tests.

Parameters
stateThe current state of the machine as it relates to the test executable.
shuffleShuffle tests
suite_iterTest suite repetitions.
case_iterTest case repetitions.

◆ ztest_run_test_suites()

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

#include </home/runner/work/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

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

Parameters
stateThe current state of the machine as it relates to the test executable.
shuffleShuffle tests
suite_iterTest suite repetitions.
case_iterTest case repetitions.
Returns
The number of tests that ran.

◆ ztest_simple_1cpu_after()

void ztest_simple_1cpu_after ( void * data)

#include </home/runner/work/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
dataThe test suite's data

◆ ztest_simple_1cpu_before()

void ztest_simple_1cpu_before ( void * data)

#include </home/runner/work/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
dataThe test suite's data

◆ ztest_skip_failed_assumption()

void ztest_skip_failed_assumption ( void )

◆ ztest_test_fail()

void ztest_test_fail ( void )

#include </home/runner/work/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 </home/runner/work/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 )

◆ ztest_verify_all_test_suites_ran()

void ztest_verify_all_test_suites_ran ( void )

#include </home/runner/work/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