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