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_deprecated.
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 #ifdef __cplusplus
22 extern "C" {
23 #endif
24
25 struct unit_test {
26 const char *name;
27 void (*test)(void);
28 void (*setup)(void);
29 void (*teardown)(void);
30 uint32_t thread_options;
31 };
32
33 /**
34 * Stats about a ztest suite
35 */
36 struct ztest_suite_stats {
37 /** The number of times that the suite ran */
38 uint32_t run_count;
39 /** The number of times that the suite was skipped */
40 uint32_t skip_count;
41 /** The number of times that the suite failed */
42 uint32_t fail_count;
43 };
44
45 /**
46 * A single node of test suite. Each node should be added to a single linker section which will
47 * allow ztest_run_registered_test_suites() to iterate over the various nodes.
48 */
49 struct ztest_suite_node {
50 /** The name of the test suite. */
51 const char *name;
52 /** Pointer to the test suite. */
53 struct unit_test *suite;
54 /**
55 * An optional predicate function to determine if the test should run. If NULL, then the
56 * test will only run once on the first attempt.
57 *
58 * @param state The current state of the test application.
59 * @return True if the suite should be run; false to skip.
60 */
61 bool (*predicate)(const void *state);
62 /** Stats */
63 struct ztest_suite_stats *stats;
64 };
65
66 extern struct ztest_suite_node _ztest_suite_node_list_start[];
67 extern struct ztest_suite_node _ztest_suite_node_list_end[];
68
69 /**
70 * Create and register a ztest suite. Using this macro creates a new test suite (using
71 * ztest_test_suite). It then creates a struct ztest_suite_node in a specific linker section.
72 *
73 * Tests can then be run by calling ztest_run_registered_test_suites(const void *state) by passing
74 * in the current state. See the documentation for ztest_run_registered_test_suites for more info.
75 *
76 * @param SUITE_NAME The name of the suite (see ztest_test_suite for more info)
77 * @param PREDICATE A function to test against the state and determine if the test should run.
78 * @param args Varargs placeholder for the remaining arguments passed for the unit tests.
79 */
80 #define ztest_register_test_suite(SUITE_NAME, PREDICATE, args...) \
81 ztest_test_suite(SUITE_NAME, ##args); \
82 struct ztest_suite_stats UTIL_CAT(z_ztest_test_node_stats_, SUITE_NAME); \
83 static STRUCT_SECTION_ITERABLE(ztest_suite_node, z_ztest_test_node_##SUITE_NAME) = { \
84 .name = #SUITE_NAME, \
85 .suite = _##SUITE_NAME, \
86 .predicate = PREDICATE, \
87 .stats = &UTIL_CAT(z_ztest_test_node_stats_, SUITE_NAME), \
88 };
89
90 /**
91 * Run the registered unit tests which return true from their pragma function.
92 *
93 * @param state The current state of the machine as it relates to the test executable.
94 * @return The number of tests that ran.
95 */
96 __deprecated
97 int ztest_run_registered_test_suites(const void *state);
98
99 /**
100 * @brief Fails the test if any of the registered tests did not run.
101 *
102 * When registering test suites, a pragma function can be provided to determine WHEN the test should
103 * run. It is possible that a test suite could be registered but the pragma always prevents it from
104 * running. In cases where a test should make sure that ALL suites ran at least once, this function
105 * may be called at the end of test_main(). It will cause the test to fail if any suite was
106 * registered but never ran.
107 */
108 __deprecated
109 void ztest_verify_all_registered_test_suites_ran(void);
110
111 /**
112 * @brief Run a test suite.
113 *
114 * Internal implementation. Do not call directly. This will run the full test suite along with some
115 * checks for fast failures and initialization.
116 *
117 * @param name The name of the suite to run.
118 * @param suite Pointer to the first unit test.
119 * @return Negative value if the test suite never ran; otherwise, return the number of failures.
120 */
121 int z_ztest_run_test_suite(const char *name, struct unit_test *suite);
122
123 /**
124 * @defgroup ztest_test_deprecated Ztest testing macros
125 * @ingroup ztest
126 *
127 * This module eases the testing process by providing helpful macros and other
128 * testing structures.
129 *
130 * @{
131 */
132
133 /**
134 * @brief Fail the currently running test.
135 *
136 * This is the function called from failed assertions and the like. You
137 * probably don't need to call it yourself.
138 */
139 void ztest_test_fail(void);
140
141 /**
142 * @brief Pass the currently running test.
143 *
144 * Normally a test passes just by returning without an assertion failure.
145 * However, if the success case for your test involves a fatal fault,
146 * you can call this function from k_sys_fatal_error_handler to indicate that
147 * the test passed before aborting the thread.
148 */
149 void ztest_test_pass(void);
150
151 /**
152 * @brief Skip the current test.
153 */
154 void ztest_test_skip(void);
155
156 /**
157 * @brief Do nothing, successfully.
158 *
159 * Unit test / setup function / teardown function that does
160 * nothing, successfully. Can be used as a parameter to
161 * ztest_unit_test_setup_teardown().
162 */
unit_test_noop(void)163 static inline void unit_test_noop(void)
164 {
165 }
166
167 /**
168 * @brief Define a test with setup and teardown functions
169 *
170 * This should be called as an argument to ztest_test_suite. The test will
171 * be run in the following order: @a setup, @a fn, @a teardown.
172 *
173 * @param fn Main test function
174 * @param setup Setup function
175 * @param teardown Teardown function
176 */
177 #define ztest_unit_test_setup_teardown(fn, setup, teardown) \
178 { \
179 STRINGIFY(fn), fn, setup, teardown, 0 \
180 }
181
182 /**
183 * @brief Define a user mode test with setup and teardown functions
184 *
185 * This should be called as an argument to ztest_test_suite. The test will
186 * be run in the following order: @a setup, @a fn, @a teardown. ALL
187 * test functions will be run in user mode, and only if CONFIG_USERSPACE
188 * is enabled, otherwise this is the same as ztest_unit_test_setup_teardown().
189 *
190 * @param fn Main test function
191 * @param setup Setup function
192 * @param teardown Teardown function
193 */
194 #define ztest_user_unit_test_setup_teardown(fn, setup, teardown) \
195 { \
196 STRINGIFY(fn), fn, setup, teardown, K_USER \
197 }
198
199 /**
200 * @brief Define a test function
201 *
202 * This should be called as an argument to ztest_test_suite.
203 *
204 * @param fn Test function
205 */
206 #define ztest_unit_test(fn) \
207 ztest_unit_test_setup_teardown(fn, unit_test_noop, unit_test_noop)
208
209 /**
210 * @brief Define a test function that should run as a user thread
211 *
212 * This should be called as an argument to ztest_test_suite.
213 * If CONFIG_USERSPACE is not enabled, this is functionally identical to
214 * ztest_unit_test().
215 *
216 * @param fn Test function
217 */
218 #define ztest_user_unit_test(fn) \
219 ztest_user_unit_test_setup_teardown(fn, unit_test_noop, unit_test_noop)
220
221 /**
222 * @brief Define a SMP-unsafe test function
223 *
224 * As ztest_unit_test(), but ensures all test code runs on only
225 * one CPU when in SMP.
226 *
227 * @param fn Test function
228 */
229 #ifdef CONFIG_SMP
230 #define ztest_1cpu_unit_test(fn) \
231 ztest_unit_test_setup_teardown(fn, z_test_1cpu_start, z_test_1cpu_stop)
232 #else
233 #define ztest_1cpu_unit_test(fn) ztest_unit_test(fn)
234 #endif
235
236 /**
237 * @brief Define a SMP-unsafe test function that should run as a user thread
238 *
239 * As ztest_user_unit_test(), but ensures all test code runs on only
240 * one CPU when in SMP.
241 *
242 * @param fn Test function
243 */
244 #ifdef CONFIG_SMP
245 #define ztest_1cpu_user_unit_test(fn) \
246 ztest_user_unit_test_setup_teardown(fn, z_test_1cpu_start, z_test_1cpu_stop)
247 #else
248 #define ztest_1cpu_user_unit_test(fn) ztest_user_unit_test(fn)
249 #endif
250
251 /* definitions for use with testing application shared memory */
252 #ifdef CONFIG_USERSPACE
253 #define ZTEST_DMEM K_APP_DMEM(ztest_mem_partition)
254 #define ZTEST_BMEM K_APP_BMEM(ztest_mem_partition)
255 #define ZTEST_SECTION K_APP_DMEM_SECTION(ztest_mem_partition)
256 extern struct k_mem_partition ztest_mem_partition;
257 #else
258 #define ZTEST_DMEM
259 #define ZTEST_BMEM
260 #define ZTEST_SECTION .data
261 #endif
262
263 /**
264 * @brief Define a test suite
265 *
266 * This function should be called in the following fashion:
267 * ```{.c}
268 * ztest_test_suite(test_suite_name,
269 * ztest_unit_test(test_function),
270 * ztest_unit_test(test_other_function)
271 * );
272 *
273 * ztest_run_test_suite(test_suite_name);
274 * ```
275 *
276 * @param suite Name of the testing suite
277 */
278 #define ztest_test_suite(suite, ...) __DEPRECATED_MACRO \
279 static ZTEST_DMEM struct unit_test _##suite[] = { __VA_ARGS__, { 0 } }
280 /**
281 * @brief Run the specified test suite.
282 *
283 * @param suite Test suite to run.
284 */
285 #define ztest_run_test_suite(suite) __DEPRECATED_MACRO \
286 z_ztest_run_test_suite(#suite, _##suite)
287
288 /**
289 * @}
290 */
291
292 #ifdef __cplusplus
293 }
294 #endif
295
296 #endif /* ZEPHYR_TESTSUITE_ZTEST_TEST_H_ */
297
