Ztest testing macros

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

Data Structures
struct	ztest_arch_api
	Structure for architecture specific APIs. More...

Macros
#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_rule_cb) (const struct ztest_unit_test *test, void *data)
	Test rule callback function signature.

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

Detailed Description

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

Macro Definition Documentation

ZTEST

#define ZTEST	(		suite,
			fn
	)		Z_ZTEST(suite, fn, 0)

#include </home/runner/work/sdk-nrf/sdk-nrf/ncs/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

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_F

#define ZTEST_F	(		suite,
			fn
	)		Z_ZTEST_F(suite, fn, 0)

#include </home/runner/work/sdk-nrf/sdk-nrf/ncs/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

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_RULE

#define ZTEST_RULE	(		name,
			before_each_fn,
			after_each_fn
	)

#include </home/runner/work/sdk-nrf/sdk-nrf/ncs/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
	)		z_ztest_run_test_suite(STRINGIFY(suite), shuffle, suite_iter, case_iter)

#include </home/runner/work/sdk-nrf/sdk-nrf/ncs/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

Run the specified test suite.

Parameters

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

ZTEST_USER

#define ZTEST_USER	(		suite,
			fn
	)		Z_ZTEST(suite, fn, K_USER)

#include </home/runner/work/sdk-nrf/sdk-nrf/ncs/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

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
	)		Z_ZTEST_F(suite, fn, K_USER)

#include </home/runner/work/sdk-nrf/sdk-nrf/ncs/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>

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.

Typedef Documentation

ztest_rule_cb

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

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

Function Documentation

ztest_simple_1cpu_after()

void ztest_simple_1cpu_after

(

void *

data

)

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

ztest_test_fail()

void ztest_test_fail

(

void

)

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

Skip the current test.