1 // Copyright 2016 The Fuchsia Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4
5 #pragma once
6
7 /*
8 * The Unittest API.
9 *
10 * The API consists of some functions for invoking Unittest, all prefixed
11 * with unittest_, and some macros for registering testcases as well as
12 * performing tests.
13 *
14 * Sample usage:
15 *
16 * A test case runs a collection of tests like this, with
17 * BEGIN_TEST_CASE and END_TEST_CASE and the beginning and end of the
18 * function and RUN_TEST to call each individual test, as follows:
19 *
20 * BEGIN_TEST_CASE(foo_tests);
21 *
22 * RUN_TEST(test_foo);
23 * RUN_TEST(test_bar);
24 * RUN_TEST(test_baz);
25 *
26 * END_TEST_CASE(foo_tests);
27 *
28 * This creates a static function foo_tests() and registers it with the
29 * unit test framework. foo_tests() can be executed either by a shell
30 * command or by a call to run_all_tests(), which runs all registered
31 * unit tests.
32 *
33 * A test looks like this, using the BEGIN_TEST and END_TEST macros at
34 * the beginning and end of the test and the EXPECT_* macros to
35 * validate test results, as shown:
36 *
37 * static bool test_foo(void)
38 * {
39 * BEGIN_TEST;
40 *
41 * ...declare variables and do stuff...
42 * int foo_value = foo_func();
43 * ...See if the stuff produced the correct value...
44 * EXPECT_EQ(1, foo_value, "foo_func failed");
45 * ... there are EXPECT_* macros for many conditions...
46 * EXPECT_TRUE(foo_condition(), "condition should be true");
47 * EXPECT_NE(ZX_ERR_TIMED_OUT, foo_event(), "event timed out");
48 *
49 * END_TEST;
50 * }
51 *
52 * The main() function of the test is expected to call unittest_run_all_tests.
53 * By default it will run all registered tests, but it also provides an option
54 * for running individual tests. Run the test binary with --help for details.
55 *
56 * Test binaries may recognize their own command line options. Make sure they
57 * don't interfere with Unittests's options. See unittest/README.md for rules
58 * on argv processing. To have test-specific options included in --help
59 * output register a function that prints the test-specific help with
60 * unittest_register_test_help_printer().
61 */
62
63 #include <stdarg.h>
64 #include <stdbool.h>
65 #include <stddef.h>
66 #include <stdint.h>
67 #include <stdio.h>
68 #include <stdlib.h>
69 #include <string.h>
70
71 #include <zircon/compiler.h>
72
73 #ifdef __Fuchsia__
74 #include <zircon/types.h>
75 #define UNITTEST_CRASH_HANDLER_SUPPORTED
76 #endif // __Fuchsia__
77
78 // The following helper function makes the "msg" argument optional in
79 // C++, so that you can write either of the following:
80 // ASSERT_EQ(x, y, "Check that x equals y");
81 // ASSERT_EQ(x, y);
82 // (We could allow the latter in C by making unittest_get_message() a
83 // var-args function, but that would be less type safe.)
unittest_get_message(const char * arg)84 static inline const char* unittest_get_message(const char* arg) {
85 return arg;
86 }
87 #ifdef __cplusplus
unittest_get_message()88 static inline const char* unittest_get_message() {
89 return "<no message>";
90 }
91 #endif
92
93 // A workaround to help static analyzer identify assertion failures
94 #if defined(__clang__)
95 #define ZX_ANALYZER_CREATE_SINK __attribute__((annotate("zx_create_sink")))
96 #else
97 #define ZX_ANALYZER_CREATE_SINK //no-op
98 #endif
99 // This function will help terminate the static analyzer when it reaches
100 // an assertion failure site which returns from test case function. The bugs
101 // discovered by the static analyzer will be suppressed as they are expected
102 // by the test cases.
unittest_returns_early(void)103 static inline void unittest_returns_early(void) ZX_ANALYZER_CREATE_SINK {}
104
105 __BEGIN_CDECLS
106
107 extern int utest_verbosity_level;
108
109 typedef enum test_type {
110 TEST_SMALL = 0x00000001,
111 TEST_MEDIUM = 0x00000002,
112 TEST_LARGE = 0x00000004,
113 TEST_PERFORMANCE = 0x00000008,
114 TEST_ALL = 0xFFFFFFFF,
115 } test_type_t;
116
117 #define TEST_ENV_NAME "RUNTESTS_TEST_CLASS"
118 #define TEST_DEFAULT (TEST_SMALL | TEST_MEDIUM)
119
120 extern test_type_t utest_test_type;
121
122 // An environment variable may be used to specify the timeout.
123 // An env var is used because runtests doesn't make assumptions about what
124 // arguments we understand.
125 #define WATCHDOG_ENV_NAME "RUNTESTS_WATCHDOG_TIMEOUT"
126
127 /*
128 * Type for unit test result Output
129 */
130 typedef void (*test_output_func)(const char* line, int len, void* arg);
131
132 /*
133 * Printf dedicated to the unittest library
134 * the default output is the printf
135 */
136 void unittest_printf_critical(const char* format, ...)
137 __attribute__((format (printf, 1, 2)));
138
139 /*
140 * Printf dedicated to the unittest library, prints output if
141 * verbosity of any level is enabled.
142 */
143
144 #define unittest_printf(format, ...) \
145 do { \
146 if (utest_verbosity_level > 0) \
147 unittest_printf_critical(format, ##__VA_ARGS__); \
148 } while (0)
149
150 /*
151 * Printf dedicated to the unittest library which output
152 * depends on the verbosity level.
153 */
154
155 #define unittest_level_printf(level, format, ...) \
156 do { \
157 if (utest_verbosity_level >= (level)) \
158 unittest_printf_critical(format, ##__VA_ARGS__); \
159 } while (0)
160
161 /*
162 * Function to set the callback for printing
163 * the unit test output
164 */
165 void unittest_set_output_function(test_output_func fun, void* arg);
166
167 /*
168 * Function to restore output callback to
169 * default_printf.
170 */
171 void unittest_restore_output_function(void);
172
173 /*
174 * Function to set the verbosity level. This affects
175 * the output of unittest_printf().
176 */
177 int unittest_set_verbosity_level(int new_level);
178
179 #define UNITTEST_FAIL_TRACEF_FORMAT " [FAILED]\n %s:%d:%s:\n "
180
181 /*
182 * Format the error string
183 */
184 #define UNITTEST_FAIL_TRACEF(str, x...) \
185 do { \
186 unittest_printf_critical( \
187 UNITTEST_FAIL_TRACEF_FORMAT str, \
188 __FILE__, __LINE__, __PRETTY_FUNCTION__, ##x); \
189 } while (0)
190
191 /*
192 * Format a tracing message
193 */
194 #define UNITTEST_TRACEF(level, str, x...) \
195 do { \
196 if (utest_verbosity_level >= (level)) { \
197 unittest_printf_critical( \
198 "%s:%d:%s:\n " str, \
199 __FILE__, __LINE__, __PRETTY_FUNCTION__, ##x); \
200 } \
201 } while (0)
202
203 /*
204 * Internal-only.
205 * Used by macros to check that the test state is set up correctly.
206 */
207 #define UT_ASSERT_VALID_TEST_STATE \
208 do { \
209 if (current_test_info == NULL) { \
210 unittest_printf_critical( \
211 "FATAL: %s:%d:%s: Invalid state for EXPECT/ASSERT: " \
212 "possible missing BEGIN_TEST or BEGIN_HELPER\n", \
213 __FILE__, __LINE__, __PRETTY_FUNCTION__); \
214 exit(101); /* Arbitrary, atypical exit status */ \
215 } \
216 } while (0)
217
218 /*
219 * BEGIN_TEST_CASE and END_TEST_CASE define a function that calls RUN_TEST. The
220 * test_name parameter specifies an optional test name to run. If null, all
221 * tests will be run.
222 */
223 #define BEGIN_TEST_CASE(case_name) \
224 bool case_name(bool list_only, const char* test_name_matching) { \
225 bool all_success = true; \
226 if (list_only) { \
227 unittest_printf_critical("\nCASE %s\n", #case_name); \
228 } else { \
229 unittest_printf_critical("\nCASE %-50s [STARTED] \n", \
230 #case_name); \
231 }
232
233 #define DEFINE_REGISTER_TEST_CASE(case_name) \
234 __attribute__((constructor)) static void _register_##case_name(void) { \
235 unittest_register_test_case(&_##case_name##_element); \
236 }
237
238 #define END_TEST_CASE(case_name) \
239 if (list_only) { \
240 unittest_printf_critical("CASE %s\n", #case_name); \
241 } else if (all_success) { \
242 unittest_printf_critical("CASE %-50s [PASSED]\n", #case_name); \
243 } else { \
244 unittest_printf_critical("CASE %-50s [FAILED]\n", #case_name); \
245 } \
246 return all_success; \
247 } \
248 static struct test_case_element _##case_name##_element = { \
249 .next = NULL, \
250 .failed_next = NULL, \
251 .name = #case_name, \
252 .test_case = case_name, \
253 }; \
254 DEFINE_REGISTER_TEST_CASE(case_name);
255
256 #define RUN_NAMED_TEST_TYPE(name, test, test_type, enable_crash_handler) \
257 if (!test_name_matching || strcmp(test_name_matching, name) == 0) { \
258 if (list_only) { \
259 unittest_printf_critical(" %s\n", name); \
260 } else { \
261 unittest_run_named_test(name, test, test_type, ¤t_test_info, \
262 &all_success, enable_crash_handler); \
263 } \
264 }
265
266 #define TEST_CASE_ELEMENT(case_name) &_##case_name##_element
267
268 /*
269 * Test classes:
270 *
271 * Small: Isolated tests for functions and classes. These must be totally
272 * synchronous and single-threaded. These tests should be parallelizable;
273 * there shouldn't be any shared resources between them.
274 *
275 * Medium: Single-process integration tests. Ideally these are also synchronous
276 * and single-threaded but they might run through a large chunk of code in each
277 * test case, or they might use disk, making them a bit slower.
278 *
279 * Large: Multi-process (or particularly incomprehensible single-process)
280 * integration tests. These tests are often too flaky to run in a CQ, and we
281 * should try to limit how many we have.
282 *
283 * Performance: Tests which are expected to pass, but which are measured
284 * using other metrics (thresholds, statistical techniques) to identify
285 * regressions.
286 */
287
288 // TODO(INTK-312): Need to fine tune these. The current values are quite
289 // conservative until the bots provide more appropriate values for bot
290 // purposes.
291 // TODO(ZX-2104): An alternative is to machine generate timeouts for each
292 // test via training runs. Taking that on will require more research.
293 #define DEFAULT_BASE_TIMEOUT_SECONDS 20
294
295 // Timeout scale for each of the test classes, from the base timeout.
296 #define TEST_TIMEOUT_FACTOR_SMALL 1
297 // TODO(ZX-2103): fvm-test:TestSliceAccessNonContiguousPhysical is a medium
298 // test that runs for 130 seconds. IWBN to make the medium timeout factor
299 // smaller.
300 #define TEST_TIMEOUT_FACTOR_MEDIUM 10
301 // TODO(ZX-2107): Some large tests are really large.
302 #define TEST_TIMEOUT_FACTOR_LARGE 100
303 #define TEST_TIMEOUT_FACTOR_PERFORMANCE 100
304
305 // Called by tests that for whatever reason want to disable their timeout.
306 // An example is really long running tests (ZX-2107).
307 void unittest_cancel_timeout(void);
308
309 #define RUN_TEST_SMALL(test) RUN_NAMED_TEST_TYPE(#test, test, TEST_SMALL, false)
310 #define RUN_TEST_MEDIUM(test) RUN_NAMED_TEST_TYPE(#test, test, TEST_MEDIUM, false)
311 #define RUN_TEST_LARGE(test) RUN_NAMED_TEST_TYPE(#test, test, TEST_LARGE, false)
312 #define RUN_TEST_PERFORMANCE(test) RUN_NAMED_TEST_TYPE(#test, test, TEST_PERFORMANCE, false)
313
314 #define RUN_NAMED_TEST_SMALL(name, test) RUN_NAMED_TEST_TYPE(name, test, TEST_SMALL, false)
315 #define RUN_NAMED_TEST_MEDIUM(name, test) RUN_NAMED_TEST_TYPE(name, test, TEST_MEDIUM, false)
316 #define RUN_NAMED_TEST_LARGE(name, test) RUN_NAMED_TEST_TYPE(name, test, TEST_LARGE, false)
317 #define RUN_NAMED_TEST_PERFORMANCE(name, test) RUN_NAMED_TEST_TYPE(name, test, TEST_PERFORMANCE, false)
318
319 // "RUN_TEST" implies the test is small
320 #define RUN_TEST(test) RUN_NAMED_TEST_TYPE(#test, test, TEST_SMALL, false)
321 #define RUN_NAMED_TEST(name, test) RUN_NAMED_TEST_TYPE(name, test, TEST_SMALL, false)
322
323 #ifdef UNITTEST_CRASH_HANDLER_SUPPORTED
324
325 #define RUN_TEST_ENABLE_CRASH_HANDLER(test) RUN_NAMED_TEST_TYPE(#test, test, TEST_SMALL, true)
326
327 /**
328 * Registers the process or thread as expected to crash. Tests utilizing this
329 * should be run with RUN_TEST_ENABLE_CRASH_HANDLER. If a crash occurs and
330 * matches a registered process or thread, it is not bubbled up to the crashlogger
331 * and the test continues. If any crash was registered but did not occur,
332 * the test fails.
333 * Unregistered crashes will also fail the test.
334 *
335 * A use case could be as follows:
336 *
337 * static bool test_foo_process_expected_crash(void)
338 * {
339 * BEGIN_TEST;
340 *
341 * ...create a process...
342 * zx_handle_t process;
343 * zx_handle_t vmar;
344 * ASSERT_EQ(zx_process_create(zx_job_default(), fooName, sizeof(fooName),
345 * 0, &process, &vmar),
346 * ZX_OK, ""));
347 * ...register the process as expected to crash...
348 * REGISTER_CRASH(process);
349 * ...trigger the crash...
350 *
351 * END_TEST;
352 * }
353 */
354 #define REGISTER_CRASH(handle) \
355 unittest_register_crash(current_test_info, handle)
356
357 #endif // UNITTEST_CRASH_HANDLER_SUPPORTED
358
359 /*
360 * BEGIN_TEST and END_TEST go in a function that is called by RUN_TEST
361 * and that call the EXPECT_ macros.
362 */
363 #define BEGIN_TEST \
364 do { \
365 UT_ASSERT_VALID_TEST_STATE; \
366 } while (0)
367
368 #define END_TEST \
369 do { \
370 UT_ASSERT_VALID_TEST_STATE; \
371 return current_test_info->all_ok; \
372 } while (0)
373
374 /*
375 * BEGIN_HELPER and END_HELPER let helper threads and files use
376 * the ASSERT_*,EXPECT_* macros, which require an in-scope, non-NULL
377 * |test_info* current_test_info|.
378 *
379 * This header file defines a static |current_test_info|, which is unlocked and
380 * should only be touched by the main thread; also, it is not visible to
381 * functions in other compilation units.
382 *
383 * Example usage:
384 *
385 * bool my_helper_in_another_file_or_thread() {
386 * BEGIN_HELPER;
387 * // Use ASSERT_* or EXPECT_*
388 * END_HELPER; // Returns false if any EXPECT calls failed.
389 * }
390 */
391 // Intentionally shadows the global current_test_info to avoid accidentally
392 // leaking dangling stack pointers.
393 #define BEGIN_HELPER \
394 struct test_info _ut_helper_test_info = { .all_ok = true, .crash_list = NULL }; \
395 struct test_info* current_test_info = &_ut_helper_test_info; \
396 // By referring to _ut_helper_test_info, we guarantee that
397 // END_HELPER is matched with BEGIN_HELPER.
398 #define END_HELPER \
399 return _ut_helper_test_info.all_ok
400
401 #ifdef __cplusplus
402 #define AUTO_TYPE_VAR(type) auto
403 #else
404 #define AUTO_TYPE_VAR(type) __typeof__(type)
405 #endif
406
407 #define RET_FALSE do { unittest_returns_early(); return false; } while (0)
408 #define DONOT_RET
409
410 #define UT_CMP(op, lhs, rhs, lhs_str, rhs_str, ret, ...) \
411 do { \
412 UT_ASSERT_VALID_TEST_STATE; \
413 UNITTEST_TRACEF(2, "%s %s %s\n", lhs_str, #op, rhs_str); \
414 const AUTO_TYPE_VAR(lhs) _lhs_val = (lhs); \
415 const AUTO_TYPE_VAR(rhs) _rhs_val = (rhs); \
416 if (!(_lhs_val op _rhs_val)) { \
417 UNITTEST_FAIL_TRACEF( \
418 "%s:\n" \
419 " Comparison failed: %s %s %s is false\n" \
420 " Specifically, %lld (0x%llx) %s %lld (0x%llx) is false\n", \
421 unittest_get_message(__VA_ARGS__), \
422 lhs_str, #op, rhs_str, (long long int)_lhs_val, \
423 (unsigned long long)_lhs_val, \
424 #op, (long long int)_rhs_val, \
425 (unsigned long long)_rhs_val); \
426 current_test_info->all_ok = false; \
427 ret; \
428 } \
429 } while (0)
430
431 #define UT_TRUE(actual, ret, ...) \
432 do { \
433 UT_ASSERT_VALID_TEST_STATE; \
434 UNITTEST_TRACEF(2, "%s\n", #actual); \
435 if (!(actual)) { \
436 UNITTEST_FAIL_TRACEF("%s: %s is false\n", \
437 unittest_get_message(__VA_ARGS__), \
438 #actual); \
439 current_test_info->all_ok = false; \
440 ret; \
441 } \
442 } while (0)
443
444 #define UT_FALSE(actual, ret, ...) \
445 do { \
446 UT_ASSERT_VALID_TEST_STATE; \
447 UNITTEST_TRACEF(2, "!(%s)\n", #actual); \
448 if (actual) { \
449 UNITTEST_FAIL_TRACEF("%s: %s is true\n", \
450 unittest_get_message(__VA_ARGS__), \
451 #actual); \
452 current_test_info->all_ok = false; \
453 ret; \
454 } \
455 } while (0)
456
457 #define UT_NULL(actual, ret, ...) \
458 do { \
459 UT_ASSERT_VALID_TEST_STATE; \
460 UNITTEST_TRACEF(2, "(%s) == NULL\n", #actual); \
461 if (actual != NULL) { \
462 UNITTEST_FAIL_TRACEF("%s: %s is non-null!\n", \
463 unittest_get_message(__VA_ARGS__), \
464 #actual); \
465 current_test_info->all_ok = false; \
466 ret; \
467 } \
468 } while (0)
469
470 #define UT_NONNULL(actual, ret, ...) \
471 do { \
472 UT_ASSERT_VALID_TEST_STATE; \
473 UNITTEST_TRACEF(2, "(%s) != NULL\n", #actual); \
474 if (actual == NULL) { \
475 UNITTEST_FAIL_TRACEF("%s: %s is null!\n", \
476 unittest_get_message(__VA_ARGS__), \
477 #actual); \
478 current_test_info->all_ok = false; \
479 ret; \
480 } \
481 } while (0)
482
483 #define UT_BYTES_EQ(expected, actual, length, msg, ret) \
484 do { \
485 UT_ASSERT_VALID_TEST_STATE; \
486 UNITTEST_TRACEF(2, "bytes_eq(%s, %s, %s)\n", \
487 #expected, #actual, #length); \
488 if (!unittest_expect_bytes_eq((expected), (actual), (length), msg)) { \
489 current_test_info->all_ok = false; \
490 ret; \
491 } \
492 } while (0)
493
494 #define UT_BYTES_NE(bytes1, bytes2, length, msg, ret) \
495 do { \
496 UT_ASSERT_VALID_TEST_STATE; \
497 UNITTEST_TRACEF(2, "bytes_ne(%s, %s, %s)\n", \
498 #bytes1, #bytes2, #length); \
499 size_t _length = (length); \
500 if (!memcmp(bytes1, bytes2, _length)) { \
501 UNITTEST_FAIL_TRACEF( \
502 "%s: %s and %s are the same; " \
503 "expected different\n", \
504 msg, #bytes1, #bytes2); \
505 hexdump8(bytes1, _length); \
506 current_test_info->all_ok = false; \
507 ret; \
508 } \
509 } while (0)
510
511 /* Check that two strings are equal. */
512 #define UT_STR_EQ(str1, str2, ret, ...) \
513 do { \
514 UT_ASSERT_VALID_TEST_STATE; \
515 UNITTEST_TRACEF(2, "str_eq(%s, %s)\n", #str1, #str2); \
516 /* Note that we should not do the following here: \
517 * const char* str1_val = str1; \
518 * That does not work in C++ if str1 is string.c_str(): the \
519 * storage for the C string will get deallocated before the \
520 * string is used. Instead we must use a helper function. */ \
521 if (!unittest_expect_str_eq((str1), (str2), #str1, #str2, \
522 unittest_get_message(__VA_ARGS__), \
523 __FILE__, __LINE__, \
524 __PRETTY_FUNCTION__)) { \
525 current_test_info->all_ok = false; \
526 ret; \
527 } \
528 } while (0)
529
530 /* Check that two strings are not equal. */
531 #define UT_STR_NE(str1, str2, ret, ...) \
532 do { \
533 UT_ASSERT_VALID_TEST_STATE; \
534 UNITTEST_TRACEF(2, "str_ne(%s, %s)\n", #str1, #str2); \
535 if (!unittest_expect_str_ne((str1), (str2), #str1, #str2, \
536 unittest_get_message(__VA_ARGS__), \
537 __FILE__, __LINE__, \
538 __PRETTY_FUNCTION__)) { \
539 current_test_info->all_ok = false; \
540 ret; \
541 } \
542 } while (0)
543
544 /* Check that str1 contains str2. */
545 #define UT_STR_STR(str1, str2, ret, ...) \
546 do { \
547 UT_ASSERT_VALID_TEST_STATE; \
548 UNITTEST_TRACEF(2, "str_str(%s, %s)\n", #str1, #str2); \
549 /* Note that we should not do the following here: \
550 * const char* str1_val = str1; \
551 * That does not work in C++ if str1 is string.c_str(): the \
552 * storage for the C string will get deallocated before the \
553 * string is used. Instead we must use a helper function. */ \
554 if (!unittest_expect_str_str((str1), (str2), #str1, #str2, \
555 unittest_get_message(__VA_ARGS__), \
556 __FILE__, __LINE__, \
557 __PRETTY_FUNCTION__)) { \
558 current_test_info->all_ok = false; \
559 ret; \
560 } \
561 } while (0)
562
563 #define EXPECT_CMP(op, lhs, rhs, lhs_str, rhs_str, ...) \
564 UT_CMP(op, lhs, rhs, lhs_str, rhs_str, DONOT_RET, ##__VA_ARGS__)
565
566 /*
567 * Use the EXPECT_* macros to check test results.
568 */
569 #define EXPECT_EQ(lhs, rhs, ...) EXPECT_CMP(==, lhs, rhs, #lhs, #rhs, ##__VA_ARGS__)
570 #define EXPECT_NE(lhs, rhs, ...) EXPECT_CMP(!=, lhs, rhs, #lhs, #rhs, ##__VA_ARGS__)
571 #define EXPECT_LE(lhs, rhs, ...) EXPECT_CMP(<=, lhs, rhs, #lhs, #rhs, ##__VA_ARGS__)
572 #define EXPECT_GE(lhs, rhs, ...) EXPECT_CMP(>=, lhs, rhs, #lhs, #rhs, ##__VA_ARGS__)
573 #define EXPECT_LT(lhs, rhs, ...) EXPECT_CMP(<, lhs, rhs, #lhs, #rhs, ##__VA_ARGS__)
574 #define EXPECT_GT(lhs, rhs, ...) EXPECT_CMP(>, lhs, rhs, #lhs, #rhs, ##__VA_ARGS__)
575
576 #define EXPECT_TRUE(actual, ...) UT_TRUE(actual, DONOT_RET, ##__VA_ARGS__)
577 #define EXPECT_FALSE(actual, ...) UT_FALSE(actual, DONOT_RET, ##__VA_ARGS__)
578 #define EXPECT_NULL(actual, ...) UT_NULL(actual, DONOT_RET, ##__VA_ARGS__)
579 #define EXPECT_NONNULL(actual, ...) UT_NONNULL(actual, DONOT_RET, ##__VA_ARGS__)
580 #define EXPECT_BYTES_EQ(expected, actual, length, msg) UT_BYTES_EQ(expected, actual, length, msg, DONOT_RET)
581 #define EXPECT_BYTES_NE(bytes1, bytes2, length, msg) UT_BYTES_NE(bytes1, bytes2, length, msg, DONOT_RET)
582 #define EXPECT_STR_EQ(str1, str2, ...) UT_STR_EQ(str1, str2, DONOT_RET, ##__VA_ARGS__)
583 #define EXPECT_STR_NE(str1, str2, ...) UT_STR_NE(str1, str2, DONOT_RET, ##__VA_ARGS__)
584
585 /*
586 * The ASSERT_* macros are similar to the EXPECT_* macros except that
587 * they return on failure.
588 */
589 #define ASSERT_NOT_NULL(p) \
590 do { \
591 UT_ASSERT_VALID_TEST_STATE; \
592 if (!p) { \
593 UNITTEST_FAIL_TRACEF("ERROR: NULL pointer\n"); \
594 return false; \
595 } \
596 } while (0)
597
598 #define ASSERT_CMP(op, lhs, rhs, lhs_str, rhs_str, ...) \
599 UT_CMP(op, lhs, rhs, lhs_str, rhs_str, RET_FALSE, ##__VA_ARGS__)
600
601 #define ASSERT_EQ(lhs, rhs, ...) ASSERT_CMP(==, lhs, rhs, #lhs, #rhs, ##__VA_ARGS__)
602 #define ASSERT_NE(lhs, rhs, ...) ASSERT_CMP(!=, lhs, rhs, #lhs, #rhs, ##__VA_ARGS__)
603 #define ASSERT_LE(lhs, rhs, ...) ASSERT_CMP(<=, lhs, rhs, #lhs, #rhs, ##__VA_ARGS__)
604 #define ASSERT_GE(lhs, rhs, ...) ASSERT_CMP(>=, lhs, rhs, #lhs, #rhs, ##__VA_ARGS__)
605 #define ASSERT_LT(lhs, rhs, ...) ASSERT_CMP(<, lhs, rhs, #lhs, #rhs, ##__VA_ARGS__)
606 #define ASSERT_GT(lhs, rhs, ...) ASSERT_CMP(>, lhs, rhs, #lhs, #rhs, ##__VA_ARGS__)
607
608 #define ASSERT_TRUE(actual, ...) UT_TRUE(actual, RET_FALSE, ##__VA_ARGS__)
609 #define ASSERT_FALSE(actual, ...) UT_FALSE(actual, RET_FALSE, ##__VA_ARGS__)
610 #define ASSERT_NULL(actual, ...) UT_NULL(actual, RET_FALSE, ##__VA_ARGS__)
611 #define ASSERT_NONNULL(actual, ...) UT_NONNULL(actual, RET_FALSE, ##__VA_ARGS__)
612 #define ASSERT_BYTES_EQ(expected, actual, length, msg) UT_BYTES_EQ(expected, actual, length, msg, RET_FALSE)
613 #define ASSERT_BYTES_NE(bytes1, bytes2, length, msg) UT_BYTES_NE(bytes1, bytes2, length, msg, RET_FALSE)
614 #define ASSERT_STR_EQ(str1, str2, ...) UT_STR_EQ(str1, str2, RET_FALSE, ##__VA_ARGS__)
615 #define ASSERT_STR_NE(str1, str2, ...) UT_STR_NE(str1, str2, RET_FALSE, ##__VA_ARGS__)
616 #define ASSERT_STR_STR(str1, str2, ...) UT_STR_STR(str1, str2, RET_FALSE, ##__VA_ARGS__)
617
618 #ifdef UNITTEST_CRASH_HANDLER_SUPPORTED
619
620 /**
621 * Runs the given function in a separate thread, and fails if the function does not crash.
622 * This is a blocking call.
623 *
624 * static void crash(void* arg) {
625 * ...trigger the crash...
626 * }
627 *
628 * static bool test_crash(void)
629 * {
630 * BEGIN_TEST;
631 *
632 * ...construct arg...
633 *
634 * ASSERT_DEATH(crash, arg, "msg about crash");
635 *
636 * END_TEST;
637 * }
638 */
639 #define ASSERT_DEATH(fn, arg, msg) ASSERT_TRUE(unittest_run_death_fn(fn, arg), msg)
640 #define ASSERT_NO_DEATH(fn, arg, msg) ASSERT_TRUE(unittest_run_no_death_fn(fn, arg), msg)
641
642 #endif // UNITTEST_CRASH_HANDLER_SUPPORTED
643
644 /*
645 * The list of test cases is made up of these elements.
646 */
647 struct test_case_element {
648 struct test_case_element* next;
649 struct test_case_element* failed_next;
650 const char* name;
651 bool (*test_case)(bool list_only, const char* test_name_matching);
652 };
653
654 /* List of processes or threads which are expected to crash. */
655 typedef struct crash_list* crash_list_t;
656
657 /*
658 * Struct to store current test case info
659 */
660 struct test_info {
661 bool all_ok;
662 crash_list_t crash_list;
663 };
664
665 /*
666 * Object which stores current test info
667 */
668 __UNUSED static struct test_info* current_test_info;
669
670 /*
671 * Registers a test case with the unit test framework.
672 */
673 void unittest_register_test_case(struct test_case_element* elem);
674
675 /*
676 * Runs all registered test cases.
677 */
678 bool unittest_run_all_tests(int argc, char** argv);
679
680 /*
681 * Runs a single test case.
682 */
683 bool unittest_run_one_test(struct test_case_element* elem, test_type_t type);
684
685 /*
686 * Register a function to print test-specific options in the output of --help.
687 * Only one help printer may be registered, each new call replaces any
688 * previously registered function.
689 */
690 typedef void unittest_help_printer_type(FILE* output);
691 void unittest_register_test_help_printer(unittest_help_printer_type* func);
692
693 /*
694 * Returns false if expected does not equal actual and prints msg and a hexdump8
695 * of the input buffers.
696 */
697 bool unittest_expect_bytes_eq(const uint8_t* expected, const uint8_t* actual, size_t len,
698 const char* msg);
699
700 bool unittest_expect_str_eq(const char* str1_value, const char* str2_value,
701 const char* str1_expr, const char* str2_expr,
702 const char* msg,
703 const char* source_filename, int source_line_num,
704 const char* source_function);
705
706 bool unittest_expect_str_ne(const char* str1_value, const char* str2_value,
707 const char* str1_expr, const char* str2_expr,
708 const char* msg,
709 const char* source_filename, int source_line_num,
710 const char* source_function);
711
712 bool unittest_expect_str_str(const char* str1_value, const char* str2_value,
713 const char* str1_expr, const char* str2_expr,
714 const char* msg,
715 const char* source_filename, int source_line_num,
716 const char* source_function);
717
718 /* Used to implement RUN_TEST() and other variants. */
719 void unittest_run_named_test(const char* name, bool (*test)(void),
720 test_type_t test_type,
721 struct test_info** current_test_info,
722 bool* all_success, bool enable_crash_handler);
723
724 #ifdef UNITTEST_CRASH_HANDLER_SUPPORTED
725 void unittest_register_crash(struct test_info* current_test_info, zx_handle_t handle);
726 bool unittest_run_death_fn(void (*fn_to_run)(void*), void* arg);
727 bool unittest_run_no_death_fn(void (*fn_to_run)(void*), void* arg);
728 #endif // UNITTEST_CRASH_HANDLER_SUPPORTED
729
730 __END_CDECLS
731