1 /*
2 * Copyright (c) 2016 Intel Corporation
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 /**
8 * @file
9 *
10 * @brief Zephyr testing framework _test.
11 */
12
13 #ifndef ZEPHYR_TESTSUITE_ZTEST_TEST_H_
14 #define ZEPHYR_TESTSUITE_ZTEST_TEST_H_
15
16 #include <zephyr/app_memory/app_memdomain.h>
17 #include <zephyr/init.h>
18 #include <zephyr/sys/iterable_sections.h>
19 #include <stdbool.h>
20
21 #if defined(CONFIG_USERSPACE)
22 #define __USERSPACE_FLAGS (K_USER)
23 #else
24 #define __USERSPACE_FLAGS (0)
25 #endif
26
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30
31 /**
32 * @brief The expected result of a test.
33 *
34 * @see ZTEST_EXPECT_FAIL
35 * @see ZTEST_EXPECT_SKIP
36 */
37 enum ztest_expected_result {
38 ZTEST_EXPECTED_RESULT_FAIL = 0, /**< Expect a test to fail */
39 ZTEST_EXPECTED_RESULT_SKIP, /**< Expect a test to pass */
40 };
41
42 /**
43 * @brief A single expectation entry allowing tests to fail/skip and be considered passing.
44 *
45 * @see ZTEST_EXPECT_FAIL
46 * @see ZTEST_EXPECT_SKIP
47 */
48 struct ztest_expected_result_entry {
49 const char *test_suite_name; /**< The test suite's name for the expectation */
50 const char *test_name; /**< The test's name for the expectation */
51 enum ztest_expected_result expected_result; /**< The expectation */
52 };
53
54 extern struct ztest_expected_result_entry _ztest_expected_result_entry_list_start[];
55 extern struct ztest_expected_result_entry _ztest_expected_result_entry_list_end[];
56
57 #define __ZTEST_EXPECT(_suite_name, _test_name, expectation) \
58 static const STRUCT_SECTION_ITERABLE( \
59 ztest_expected_result_entry, \
60 UTIL_CAT(UTIL_CAT(z_ztest_expected_result_, _suite_name), _test_name)) = { \
61 .test_suite_name = STRINGIFY(_suite_name), \
62 .test_name = STRINGIFY(_test_name), \
63 .expected_result = expectation, \
64 }
65
66 /**
67 * @brief Expect a test to fail (mark it passing if it failed)
68 *
69 * Adding this macro to your logic will allow the failing test to be considered passing, example:
70 *
71 * ZTEST_EXPECT_FAIL(my_suite, test_x);
72 * ZTEST(my_suite, text_x) {
73 * zassert_true(false, NULL);
74 * }
75 *
76 * @param _suite_name The name of the suite
77 * @param _test_name The name of the test
78 */
79 #define ZTEST_EXPECT_FAIL(_suite_name, _test_name) \
80 __ZTEST_EXPECT(_suite_name, _test_name, ZTEST_EXPECTED_RESULT_FAIL)
81
82 /**
83 * @brief Expect a test to skip (mark it passing if it failed)
84 *
85 * Adding this macro to your logic will allow the failing test to be considered passing, example:
86 *
87 * ZTEST_EXPECT_SKIP(my_suite, test_x);
88 * ZTEST(my_suite, text_x) {
89 * zassume_true(false, NULL);
90 * }
91 *
92 * @param _suite_name The name of the suite
93 * @param _test_name The name of the test
94 */
95 #define ZTEST_EXPECT_SKIP(_suite_name, _test_name) \
96 __ZTEST_EXPECT(_suite_name, _test_name, ZTEST_EXPECTED_RESULT_SKIP)
97
98 struct ztest_unit_test {
99 const char *test_suite_name;
100 const char *name;
101 void (*test)(void *data);
102 uint32_t thread_options;
103
104 /** Stats */
105 struct ztest_unit_test_stats *const stats;
106 };
107
108 extern struct ztest_unit_test _ztest_unit_test_list_start[];
109 extern struct ztest_unit_test _ztest_unit_test_list_end[];
110 #define ZTEST_TEST_COUNT (_ztest_unit_test_list_end - _ztest_unit_test_list_start)
111
112 /**
113 * Stats about a ztest suite
114 */
115 struct ztest_suite_stats {
116 /** The number of times that the suite ran */
117 uint32_t run_count;
118 /** The number of times that the suite was skipped */
119 uint32_t skip_count;
120 /** The number of times that the suite failed */
121 uint32_t fail_count;
122 };
123
124 struct ztest_unit_test_stats {
125 /** The number of times that the test ran */
126 uint32_t run_count;
127 /** The number of times that the test was skipped */
128 uint32_t skip_count;
129 /** The number of times that the test failed */
130 uint32_t fail_count;
131 /** The number of times that the test passed */
132 uint32_t pass_count;
133 /** The longest duration of the test across multiple times */
134 uint32_t duration_worst_ms;
135 };
136
137 /**
138 * Setup function to run before running this suite
139 *
140 * @return Pointer to the data structure that will be used throughout this test suite
141 */
142 typedef void *(*ztest_suite_setup_t)(void);
143
144 /**
145 * Function to run before each test in this suite
146 *
147 * @param fixture The test suite's fixture returned from setup()
148 */
149 typedef void (*ztest_suite_before_t)(void *fixture);
150
151 /**
152 * Function to run after each test in this suite
153 *
154 * @param fixture The test suite's fixture returned from setup()
155 */
156 typedef void (*ztest_suite_after_t)(void *fixture);
157
158 /**
159 * Teardown function to run after running this suite
160 *
161 * @param fixture The test suite's data returned from setup()
162 */
163 typedef void (*ztest_suite_teardown_t)(void *fixture);
164
165 /**
166 * An optional predicate function to determine if the test should run. If NULL, then the
167 * test will only run once on the first attempt.
168 *
169 * @param global_state The current state of the test application.
170 * @return True if the suite should be run; false to skip.
171 */
172 typedef bool (*ztest_suite_predicate_t)(const void *global_state);
173
174 /**
175 * A single node of test suite. Each node should be added to a single linker section which will
176 * allow ztest_run_test_suites() to iterate over the various nodes.
177 */
178 struct ztest_suite_node {
179 /** The name of the test suite. */
180 const char *const name;
181
182 /** Setup function */
183 const ztest_suite_setup_t setup;
184
185 /** Before function */
186 const ztest_suite_before_t before;
187
188 /** After function */
189 const ztest_suite_after_t after;
190
191 /** Teardown function */
192 const ztest_suite_teardown_t teardown;
193
194 /** Optional predicate filter */
195 const ztest_suite_predicate_t predicate;
196
197 /** Stats */
198 struct ztest_suite_stats *const stats;
199 };
200
201 extern struct ztest_suite_node _ztest_suite_node_list_start[];
202 extern struct ztest_suite_node _ztest_suite_node_list_end[];
203 #define ZTEST_SUITE_COUNT (_ztest_suite_node_list_end - _ztest_suite_node_list_start)
204
205 /**
206 * Create and register a ztest suite. Using this macro creates a new test suite (using
207 * ztest_test_suite). It then creates a struct ztest_suite_node in a specific linker section.
208 *
209 * Tests can then be run by calling ztest_run_test_suites(const void *state) by passing
210 * in the current state. See the documentation for ztest_run_test_suites for more info.
211 *
212 * @param SUITE_NAME The name of the suite (see ztest_test_suite for more info)
213 * @param PREDICATE A function to test against the state and determine if the test should run.
214 * @param setup_fn The setup function to call before running this test suite
215 * @param before_fn The function to call before each unit test in this suite
216 * @param after_fn The function to call after each unit test in this suite
217 * @param teardown_fn The function to call after running all the tests in this suite
218 */
219 #define ZTEST_SUITE(SUITE_NAME, PREDICATE, setup_fn, before_fn, after_fn, teardown_fn) \
220 struct ztest_suite_stats UTIL_CAT(z_ztest_suite_node_stats_, SUITE_NAME); \
221 static const STRUCT_SECTION_ITERABLE(ztest_suite_node, \
222 UTIL_CAT(z_ztest_test_node_, SUITE_NAME)) = { \
223 .name = STRINGIFY(SUITE_NAME), \
224 .setup = (setup_fn), \
225 .before = (before_fn), \
226 .after = (after_fn), \
227 .teardown = (teardown_fn), \
228 .predicate = PREDICATE, \
229 .stats = &UTIL_CAT(z_ztest_suite_node_stats_, SUITE_NAME), \
230 }
231 /**
232 * Default entry point for running or listing registered unit tests.
233 *
234 * @param state The current state of the machine as it relates to the test executable.
235 */
236 void ztest_run_all(const void *state);
237
238 /**
239 * The result of the current running test. It's possible that the setup function sets the result
240 * to ZTEST_RESULT_SUITE_* which will apply the failure/skip to every test in the suite.
241 */
242 enum ztest_result {
243 ZTEST_RESULT_PENDING,
244 ZTEST_RESULT_PASS,
245 ZTEST_RESULT_FAIL,
246 ZTEST_RESULT_SKIP,
247 ZTEST_RESULT_SUITE_SKIP,
248 ZTEST_RESULT_SUITE_FAIL,
249 };
250 /**
251 * Each enum member represents a distinct phase of execution for the test binary.
252 * TEST_PHASE_FRAMEWORK is active when internal ztest code is executing; the rest refer to
253 * corresponding phases of user test code.
254 */
255 enum ztest_phase {
256 TEST_PHASE_SETUP,
257 TEST_PHASE_BEFORE,
258 TEST_PHASE_TEST,
259 TEST_PHASE_AFTER,
260 TEST_PHASE_TEARDOWN,
261 TEST_PHASE_FRAMEWORK,
262 };
263
264 /**
265 * Run the registered unit tests which return true from their predicate function.
266 *
267 * @param state The current state of the machine as it relates to the test executable.
268 * @return The number of tests that ran.
269 */
270
271 #ifdef ZTEST_UNITTEST
272 int z_impl_ztest_run_test_suites(const void *state);
ztest_run_test_suites(const void * state)273 static inline int ztest_run_test_suites(const void *state)
274 {
275 return z_impl_ztest_run_test_suites(state);
276 }
277
278 #else
279 __syscall int ztest_run_test_suites(const void *state);
280 #endif
281
282 #ifdef ZTEST_UNITTEST
283 void z_impl___ztest_set_test_result(enum ztest_result new_result);
__ztest_set_test_result(enum ztest_result new_result)284 static inline void __ztest_set_test_result(enum ztest_result new_result)
285 {
286 z_impl___ztest_set_test_result(new_result);
287 }
288
289 void z_impl___ztest_set_test_phase(enum ztest_phase new_phase);
__ztest_set_test_phase(enum ztest_phase new_phase)290 static inline void __ztest_set_test_phase(enum ztest_phase new_phase)
291 {
292 z_impl___ztest_set_test_phase(new_phase);
293 }
294 #else
295 __syscall void __ztest_set_test_result(enum ztest_result new_result);
296 __syscall void __ztest_set_test_phase(enum ztest_phase new_phase);
297 #endif
298
299 #ifndef ZTEST_UNITTEST
300 #include <syscalls/ztest_test_new.h>
301 #endif
302
303 /**
304 * @brief Fails the test if any of the registered tests did not run.
305 *
306 * When registering test suites, a pragma function can be provided to determine WHEN the test should
307 * run. It is possible that a test suite could be registered but the pragma always prevents it from
308 * running. In cases where a test should make sure that ALL suites ran at least once, this function
309 * may be called at the end of test_main(). It will cause the test to fail if any suite was
310 * registered but never ran.
311 */
312 void ztest_verify_all_test_suites_ran(void);
313
314 /**
315 * @brief Run a test suite.
316 *
317 * Internal implementation. Do not call directly. This will run the full test suite along with some
318 * checks for fast failures and initialization.
319 *
320 * @param name The name of the suite to run.
321 * @return Negative value if the test suite never ran; otherwise, return the number of failures.
322 */
323 int z_ztest_run_test_suite(const char *name);
324
325 /**
326 * @brief Returns next test within suite.
327 *
328 * @param suite Name of suite to get next test from.
329 * @param prev Previous unit test acquired from suite, use NULL to return first
330 * unit test.
331 * @return struct ztest_unit_test*
332 */
333 struct ztest_unit_test *z_ztest_get_next_test(const char *suite, struct ztest_unit_test *prev);
334
335 /* definitions for use with testing application shared memory */
336 #ifdef CONFIG_USERSPACE
337 #define ZTEST_DMEM K_APP_DMEM(ztest_mem_partition)
338 #define ZTEST_BMEM K_APP_BMEM(ztest_mem_partition)
339 #define ZTEST_SECTION K_APP_DMEM_SECTION(ztest_mem_partition)
340 extern struct k_mem_partition ztest_mem_partition;
341 #else
342 #define ZTEST_DMEM
343 #define ZTEST_BMEM
344 #define ZTEST_SECTION .data
345 #endif
346
347 /**
348 * @defgroup ztest_test Ztest testing macros
349 * @ingroup ztest
350 *
351 * This module eases the testing process by providing helpful macros and other
352 * testing structures.
353 *
354 * @{
355 */
356
357 /**
358 * @brief Fail the currently running test.
359 *
360 * This is the function called from failed assertions and the like. You
361 * probably don't need to call it yourself.
362 */
363 void ztest_test_fail(void);
364
365 /**
366 * @brief Pass the currently running test.
367 *
368 * Normally a test passes just by returning without an assertion failure.
369 * However, if the success case for your test involves a fatal fault,
370 * you can call this function from k_sys_fatal_error_handler to indicate that
371 * the test passed before aborting the thread.
372 */
373 void ztest_test_pass(void);
374
375 /**
376 * @brief Skip the current test.
377 *
378 */
379 void ztest_test_skip(void);
380
381
382 void ztest_skip_failed_assumption(void);
383
384 #define Z_TEST(suite, fn, t_options, use_fixture) \
385 struct ztest_unit_test_stats z_ztest_unit_test_stats_##suite##_##fn; \
386 static void _##suite##_##fn##_wrapper(void *data); \
387 static void suite##_##fn( \
388 COND_CODE_1(use_fixture, (struct suite##_fixture *fixture), (void))); \
389 static STRUCT_SECTION_ITERABLE(ztest_unit_test, z_ztest_unit_test__##suite##__##fn) = { \
390 .test_suite_name = STRINGIFY(suite), \
391 .name = STRINGIFY(fn), \
392 .test = (_##suite##_##fn##_wrapper), \
393 .thread_options = t_options, \
394 .stats = &z_ztest_unit_test_stats_##suite##_##fn \
395 }; \
396 static void _##suite##_##fn##_wrapper(void *wrapper_data) \
397 { \
398 COND_CODE_1(use_fixture, (suite##_##fn((struct suite##_fixture *)wrapper_data);), \
399 (ARG_UNUSED(wrapper_data); suite##_##fn();)) \
400 } \
401 static inline void suite##_##fn( \
402 COND_CODE_1(use_fixture, (struct suite##_fixture *fixture), (void)))
403
404 #define Z_ZTEST(suite, fn, t_options) Z_TEST(suite, fn, t_options, 0)
405 #define Z_ZTEST_F(suite, fn, t_options) Z_TEST(suite, fn, t_options, 1)
406
407 /**
408 * @brief Skips the test if config is enabled
409 *
410 * Use this macro at the start of your test case, to skip it when
411 * config is enabled. Useful when your test is still under development.
412 *
413 * @param config The Kconfig option used to skip the test.
414 */
415 #define Z_TEST_SKIP_IFDEF(config) COND_CODE_1(config, (ztest_test_skip()), ())
416
417 /**
418 * @brief Skips the test if config is not enabled
419 *
420 * Use this macro at the start of your test case, to skip it when
421 * config is not enabled. Useful when your need to skip test if some
422 * conifiguration option is not enabled.
423 *
424 * @param config The Kconfig option used to skip the test (if not enabled).
425 */
426 #define Z_TEST_SKIP_IFNDEF(config) COND_CODE_1(config, (), (ztest_test_skip()))
427
428 /**
429 * @brief Create and register a new unit test.
430 *
431 * Calling this macro will create a new unit test and attach it to the declared `suite`. The `suite`
432 * does not need to be defined in the same compilation unit.
433 *
434 * @param suite The name of the test suite to attach this test
435 * @param fn The test function to call.
436 */
437 #define ZTEST(suite, fn) Z_ZTEST(suite, fn, 0)
438
439 /**
440 * @brief Define a test function that should run as a user thread
441 *
442 * This macro behaves exactly the same as ZTEST, but calls the test function in user space if
443 * `CONFIG_USERSPACE` was enabled.
444 *
445 * @param suite The name of the test suite to attach this test
446 * @param fn The test function to call.
447 */
448 #define ZTEST_USER(suite, fn) Z_ZTEST(suite, fn, K_USER)
449
450 /**
451 * @brief Define a test function
452 *
453 * This macro behaves exactly the same as ZTEST(), but the function takes an argument for the
454 * fixture of type `struct suite##_fixture*` named `this`.
455 *
456 * @param suite The name of the test suite to attach this test
457 * @param fn The test function to call.
458 */
459 #define ZTEST_F(suite, fn) Z_ZTEST_F(suite, fn, 0)
460
461 /**
462 * @brief Define a test function that should run as a user thread
463 *
464 * If CONFIG_USERSPACE is not enabled, this is functionally identical to ZTEST_F(). The test
465 * function takes a single fixture argument of type `struct suite##_fixture*` named `this`.
466 *
467 * @param suite The name of the test suite to attach this test
468 * @param fn The test function to call.
469 */
470 #define ZTEST_USER_F(suite, fn) Z_ZTEST_F(suite, fn, K_USER)
471
472 /**
473 * @brief Test rule callback function signature
474 *
475 * The function signature that can be used to register a test rule's before/after callback. This
476 * provides access to the test and the fixture data (if provided).
477 *
478 * @param test Pointer to the unit test in context
479 * @param data Pointer to the test's fixture data (may be NULL)
480 */
481 typedef void (*ztest_rule_cb)(const struct ztest_unit_test *test, void *data);
482
483 /** @private */
484 struct ztest_test_rule {
485 ztest_rule_cb before_each;
486 ztest_rule_cb after_each;
487 };
488
489 /**
490 * @brief Define a test rule that will run before/after each unit test.
491 *
492 * Functions defined here will run before/after each unit test for every test suite. Along with the
493 * callback, the test functions are provided a pointer to the test being run, and the data. This
494 * provides a mechanism for tests to perform custom operations depending on the specific test or
495 * the data (for example logging may use the test's name).
496 *
497 * Ordering:
498 * - Test rule's `before` function will run before the suite's `before` function. This is done to
499 * allow the test suite's customization to take precedence over the rule which is applied to all
500 * suites.
501 * - Test rule's `after` function is not guaranteed to run in any particular order.
502 *
503 * @param name The name for the test rule (must be unique within the compilation unit)
504 * @param before_each_fn The callback function (ztest_rule_cb) to call before each test
505 * (may be NULL)
506 * @param after_each_fn The callback function (ztest_rule_cb) to call after each test (may be NULL)
507 */
508 #define ZTEST_RULE(name, before_each_fn, after_each_fn) \
509 static STRUCT_SECTION_ITERABLE(ztest_test_rule, z_ztest_test_rule_##name) = { \
510 .before_each = (before_each_fn), \
511 .after_each = (after_each_fn), \
512 }
513
514 extern struct ztest_test_rule _ztest_test_rule_list_start[];
515 extern struct ztest_test_rule _ztest_test_rule_list_end[];
516
517 /**
518 * @brief A 'before' function to use in test suites that just need to start 1cpu
519 *
520 * Ignores data, and calls z_test_1cpu_start()
521 *
522 * @param data The test suite's data
523 */
524 void ztest_simple_1cpu_before(void *data);
525
526 /**
527 * @brief A 'after' function to use in test suites that just need to stop 1cpu
528 *
529 * Ignores data, and calls z_test_1cpu_stop()
530 *
531 * @param data The test suite's data
532 */
533 void ztest_simple_1cpu_after(void *data);
534
535 /**
536 * @brief Run the specified test suite.
537 *
538 * @param suite Test suite to run.
539 */
540 #define ztest_run_test_suite(suite) z_ztest_run_test_suite(STRINGIFY(suite))
541
542 /**
543 * @brief Structure for architecture specific APIs
544 *
545 */
546 struct ztest_arch_api {
547 void (*run_all)(const void *state);
548 bool (*should_suite_run)(const void *state, struct ztest_suite_node *suite);
549 bool (*should_test_run)(const char *suite, const char *test);
550 };
551
552 /**
553 * @}
554 */
555
556 #ifdef __cplusplus
557 }
558 #endif
559
560 #endif /* ZEPHYR_TESTSUITE_ZTEST_TEST_H_ */
561
