Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
|
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 |
This module eases the testing process by providing helpful macros and other testing structures.
#define ZTEST | ( | suite, | |
fn ) |
#include </home/runner/work/zephyr/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.
suite | The name of the test suite to attach this test |
fn | The test function to call. |
#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.
#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.
#define ZTEST_EXPECT_FAIL | ( | _suite_name, | |
_test_name ) |
#include </home/runner/work/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>
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); }
_suite_name | The name of the suite |
_test_name | The name of the test |
#define ZTEST_EXPECT_SKIP | ( | _suite_name, | |
_test_name ) |
#include </home/runner/work/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>
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); }
_suite_name | The name of the suite |
_test_name | The name of the test |
#define ZTEST_F | ( | suite, | |
fn ) |
#include </home/runner/work/zephyr/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
.
suite | The name of the test suite to attach this test |
fn | The test function to call. |
#define ZTEST_P | ( | suite, | |
fn ) |
#include </home/runner/work/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>
#define ZTEST_RULE | ( | name, | |
before_each_fn, | |||
after_each_fn ) |
#include </home/runner/work/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>
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:
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.after
function is not guaranteed to run in any particular order.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) |
#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>
Run the specified test suite.
suite | Test suite to run. |
shuffle | Shuffle tests |
suite_iter | Test suite repetitions. |
case_iter | Test case repetitions. |
param | Test parameter |
#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.
#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>
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.
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 |
#define ZTEST_SUITE_COUNT (_ztest_suite_node_list_end - _ztest_suite_node_list_start) |
#include </home/runner/work/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>
Number of registered test suites.
#define ZTEST_TEST_COUNT (_ztest_unit_test_list_end - _ztest_unit_test_list_start) |
#include </home/runner/work/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>
Number of registered unit tests.
#define ZTEST_USER | ( | suite, | |
fn ) |
#include </home/runner/work/zephyr/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.
suite | The name of the test suite to attach this test |
fn | The test function to call. |
#define ZTEST_USER_F | ( | suite, | |
fn ) |
#include </home/runner/work/zephyr/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
.
suite | The name of the test suite to attach this test |
fn | The test function to call. |
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).
test | Pointer to the unit test in context |
data | Pointer to the test's fixture data (may be NULL) |
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.
fixture | The test suite's fixture returned from setup() |
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.
fixture | The test suite's fixture returned from setup() |
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.
global_state | The current state of the test application. |
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.
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.
fixture | The test suite's data returned from setup() |
#include </home/runner/work/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>
The expected result of a test.
Enumerator | |
---|---|
ZTEST_EXPECTED_RESULT_FAIL | Expect a test to fail. |
ZTEST_EXPECTED_RESULT_SKIP | Expect a test to pass. |
enum 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 |
enum 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 |
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.
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. |
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.
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. |
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()
data | The test suite's data |
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()
data | The test suite's data |
void ztest_skip_failed_assumption | ( | void | ) |
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.
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.
void ztest_test_skip | ( | void | ) |
#include </home/runner/work/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztest_test.h>
Skip the current test.
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.
|
extern |