ztest: document test rules

Add documentation to test rules.

Signed-off-by: Yuval Peress <peress@google.com>
This commit is contained in:
Yuval Peress 2022-01-25 10:57:44 -07:00 committed by Anas Nashif
commit 47113211c7

View file

@ -254,6 +254,15 @@ static inline void unit_test_noop(void)
*/
#define ZTEST_USER_F(suite, fn) Z_ZTEST_F(suite, fn, COND_CODE_1(CONFIG_USERSPACE, (K_USER), (0)))
/**
* @brief 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).
*
* @param test Pointer to the unit test in context
* @param data Pointer to the test's fixture data (may be NULL)
*/
typedef void (*ztest_rule_cb)(const struct ztest_unit_test *test, void *data);
struct ztest_test_rule {
@ -261,6 +270,18 @@ struct ztest_test_rule {
ztest_rule_cb after_each;
};
/**
* @brief 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).
*
* @param name The name for the test rule (must be unique within the compilational unit)
* @param before_each_fn The callback function to call before each test (may be NULL)
* @param after_each_fn The callback function to call after each test (may be NULL)
*/
#define ZTEST_RULE(name, before_each_fn, after_each_fn) \
static STRUCT_SECTION_ITERABLE(ztest_test_rule, z_ztest_test_rule_##name) = { \
.before_each = (before_each_fn), \