1 /* SPDX-License-Identifier: GPL-2.0-only */
2 /*
3 * Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
4 *
5 * kselftest_harness.h: simple C unit test helper.
6 *
7 * See documentation in Documentation/dev-tools/kselftest.rst
8 *
9 * API inspired by code.google.com/p/googletest
10 */
11
12 /**
13 * DOC: example
14 *
15 * .. code-block:: c
16 *
17 * #include "../kselftest_harness.h"
18 *
19 * TEST(standalone_test) {
20 * do_some_stuff;
21 * EXPECT_GT(10, stuff) {
22 * stuff_state_t state;
23 * enumerate_stuff_state(&state);
24 * TH_LOG("expectation failed with state: %s", state.msg);
25 * }
26 * more_stuff;
27 * ASSERT_NE(some_stuff, NULL) TH_LOG("how did it happen?!");
28 * last_stuff;
29 * EXPECT_EQ(0, last_stuff);
30 * }
31 *
32 * FIXTURE(my_fixture) {
33 * mytype_t *data;
34 * int awesomeness_level;
35 * };
36 * FIXTURE_SETUP(my_fixture) {
37 * self->data = mytype_new();
38 * ASSERT_NE(NULL, self->data);
39 * }
40 * FIXTURE_TEARDOWN(my_fixture) {
41 * mytype_free(self->data);
42 * }
43 * TEST_F(my_fixture, data_is_good) {
44 * EXPECT_EQ(1, is_my_data_good(self->data));
45 * }
46 *
47 * TEST_HARNESS_MAIN
48 */
49
50 #ifndef __KSELFTEST_HARNESS_H
51 #define __KSELFTEST_HARNESS_H
52
53 #ifndef _GNU_SOURCE
54 #define _GNU_SOURCE
55 #endif
56 #include <asm/types.h>
57 #include <ctype.h>
58 #include <errno.h>
59 #include <linux/unistd.h>
60 #include <poll.h>
61 #include <stdbool.h>
62 #include <stdint.h>
63 #include <stdio.h>
64 #include <stdlib.h>
65 #include <string.h>
66 #include <sys/mman.h>
67 #include <sys/types.h>
68 #include <sys/wait.h>
69 #include <unistd.h>
70
71 #include "kselftest.h"
72
73 #define TEST_TIMEOUT_DEFAULT 30
74
75 /* Utilities exposed to the test definitions */
76 #ifndef TH_LOG_STREAM
77 # define TH_LOG_STREAM stderr
78 #endif
79
80 #ifndef TH_LOG_ENABLED
81 # define TH_LOG_ENABLED 1
82 #endif
83
84 /**
85 * TH_LOG()
86 *
87 * @fmt: format string
88 * @...: optional arguments
89 *
90 * .. code-block:: c
91 *
92 * TH_LOG(format, ...)
93 *
94 * Optional debug logging function available for use in tests.
95 * Logging may be enabled or disabled by defining TH_LOG_ENABLED.
96 * E.g., #define TH_LOG_ENABLED 1
97 *
98 * If no definition is provided, logging is enabled by default.
99 */
100 #define TH_LOG(fmt, ...) do { \
101 if (TH_LOG_ENABLED) \
102 __TH_LOG(fmt, ##__VA_ARGS__); \
103 } while (0)
104
105 /* Unconditional logger for internal use. */
106 #define __TH_LOG(fmt, ...) \
107 fprintf(TH_LOG_STREAM, "# %s:%d:%s:" fmt "\n", \
108 __FILE__, __LINE__, _metadata->name, ##__VA_ARGS__)
109
110 /**
111 * SKIP()
112 *
113 * @statement: statement to run after reporting SKIP
114 * @fmt: format string
115 * @...: optional arguments
116 *
117 * .. code-block:: c
118 *
119 * SKIP(statement, fmt, ...);
120 *
121 * This forces a "pass" after reporting why something is being skipped
122 * and runs "statement", which is usually "return" or "goto skip".
123 */
124 #define SKIP(statement, fmt, ...) do { \
125 snprintf(_metadata->results->reason, \
126 sizeof(_metadata->results->reason), fmt, ##__VA_ARGS__); \
127 if (TH_LOG_ENABLED) { \
128 fprintf(TH_LOG_STREAM, "# SKIP %s\n", \
129 _metadata->results->reason); \
130 } \
131 _metadata->exit_code = KSFT_SKIP; \
132 _metadata->trigger = 0; \
133 statement; \
134 } while (0)
135
136 /**
137 * TEST() - Defines the test function and creates the registration
138 * stub
139 *
140 * @test_name: test name
141 *
142 * .. code-block:: c
143 *
144 * TEST(name) { implementation }
145 *
146 * Defines a test by name.
147 * Names must be unique and tests must not be run in parallel. The
148 * implementation containing block is a function and scoping should be treated
149 * as such. Returning early may be performed with a bare "return;" statement.
150 *
151 * EXPECT_* and ASSERT_* are valid in a TEST() { } context.
152 */
153 #define TEST(test_name) __TEST_IMPL(test_name, -1)
154
155 /**
156 * TEST_SIGNAL()
157 *
158 * @test_name: test name
159 * @signal: signal number
160 *
161 * .. code-block:: c
162 *
163 * TEST_SIGNAL(name, signal) { implementation }
164 *
165 * Defines a test by name and the expected term signal.
166 * Names must be unique and tests must not be run in parallel. The
167 * implementation containing block is a function and scoping should be treated
168 * as such. Returning early may be performed with a bare "return;" statement.
169 *
170 * EXPECT_* and ASSERT_* are valid in a TEST() { } context.
171 */
172 #define TEST_SIGNAL(test_name, signal) __TEST_IMPL(test_name, signal)
173
174 #define __TEST_IMPL(test_name, _signal) \
175 static void test_name(struct __test_metadata *_metadata); \
176 static void wrapper_##test_name( \
177 struct __test_metadata *_metadata, \
178 struct __fixture_variant_metadata __attribute__((unused)) *variant) \
179 { \
180 test_name(_metadata); \
181 } \
182 static struct __test_metadata _##test_name##_object = \
183 { .name = #test_name, \
184 .fn = &wrapper_##test_name, \
185 .fixture = &_fixture_global, \
186 .termsig = _signal, \
187 .timeout = TEST_TIMEOUT_DEFAULT, }; \
188 static void __attribute__((constructor)) _register_##test_name(void) \
189 { \
190 __register_test(&_##test_name##_object); \
191 } \
192 static void test_name( \
193 struct __test_metadata __attribute__((unused)) *_metadata)
194
195 /**
196 * FIXTURE_DATA() - Wraps the struct name so we have one less
197 * argument to pass around
198 *
199 * @datatype_name: datatype name
200 *
201 * .. code-block:: c
202 *
203 * FIXTURE_DATA(datatype_name)
204 *
205 * Almost always, you want just FIXTURE() instead (see below).
206 * This call may be used when the type of the fixture data
207 * is needed. In general, this should not be needed unless
208 * the *self* is being passed to a helper directly.
209 */
210 #define FIXTURE_DATA(datatype_name) struct _test_data_##datatype_name
211
212 /**
213 * FIXTURE() - Called once per fixture to setup the data and
214 * register
215 *
216 * @fixture_name: fixture name
217 *
218 * .. code-block:: c
219 *
220 * FIXTURE(fixture_name) {
221 * type property1;
222 * ...
223 * };
224 *
225 * Defines the data provided to TEST_F()-defined tests as *self*. It should be
226 * populated and cleaned up using FIXTURE_SETUP() and FIXTURE_TEARDOWN().
227 */
228 #define FIXTURE(fixture_name) \
229 FIXTURE_VARIANT(fixture_name); \
230 static struct __fixture_metadata _##fixture_name##_fixture_object = \
231 { .name = #fixture_name, }; \
232 static void __attribute__((constructor)) \
233 _register_##fixture_name##_data(void) \
234 { \
235 __register_fixture(&_##fixture_name##_fixture_object); \
236 } \
237 FIXTURE_DATA(fixture_name)
238
239 /**
240 * FIXTURE_SETUP() - Prepares the setup function for the fixture.
241 * *_metadata* is included so that EXPECT_*, ASSERT_* etc. work correctly.
242 *
243 * @fixture_name: fixture name
244 *
245 * .. code-block:: c
246 *
247 * FIXTURE_SETUP(fixture_name) { implementation }
248 *
249 * Populates the required "setup" function for a fixture. An instance of the
250 * datatype defined with FIXTURE_DATA() will be exposed as *self* for the
251 * implementation.
252 *
253 * ASSERT_* are valid for use in this context and will prempt the execution
254 * of any dependent fixture tests.
255 *
256 * A bare "return;" statement may be used to return early.
257 */
258 #define FIXTURE_SETUP(fixture_name) \
259 static void fixture_name##_setup( \
260 struct __test_metadata __attribute__((unused)) *_metadata, \
261 FIXTURE_DATA(fixture_name) __attribute__((unused)) *self, \
262 const FIXTURE_VARIANT(fixture_name) \
263 __attribute__((unused)) *variant)
264
265 /**
266 * FIXTURE_TEARDOWN()
267 * *_metadata* is included so that EXPECT_*, ASSERT_* etc. work correctly.
268 *
269 * @fixture_name: fixture name
270 *
271 * .. code-block:: c
272 *
273 * FIXTURE_TEARDOWN(fixture_name) { implementation }
274 *
275 * Populates the required "teardown" function for a fixture. An instance of the
276 * datatype defined with FIXTURE_DATA() will be exposed as *self* for the
277 * implementation to clean up.
278 *
279 * A bare "return;" statement may be used to return early.
280 */
281 #define FIXTURE_TEARDOWN(fixture_name) \
282 static const bool fixture_name##_teardown_parent; \
283 __FIXTURE_TEARDOWN(fixture_name)
284
285 /**
286 * FIXTURE_TEARDOWN_PARENT()
287 * *_metadata* is included so that EXPECT_*, ASSERT_* etc. work correctly.
288 *
289 * @fixture_name: fixture name
290 *
291 * .. code-block:: c
292 *
293 * FIXTURE_TEARDOWN_PARENT(fixture_name) { implementation }
294 *
295 * Same as FIXTURE_TEARDOWN() but run this code in a parent process. This
296 * enables the test process to drop its privileges without impacting the
297 * related FIXTURE_TEARDOWN_PARENT() (e.g. to remove files from a directory
298 * where write access was dropped).
299 *
300 * To make it possible for the parent process to use *self*, share (MAP_SHARED)
301 * the fixture data between all forked processes.
302 */
303 #define FIXTURE_TEARDOWN_PARENT(fixture_name) \
304 static const bool fixture_name##_teardown_parent = true; \
305 __FIXTURE_TEARDOWN(fixture_name)
306
307 #define __FIXTURE_TEARDOWN(fixture_name) \
308 static void fixture_name##_teardown( \
309 struct __test_metadata __attribute__((unused)) *_metadata, \
310 FIXTURE_DATA(fixture_name) __attribute__((unused)) *self, \
311 const FIXTURE_VARIANT(fixture_name) \
312 __attribute__((unused)) *variant)
313
314 /**
315 * FIXTURE_VARIANT() - Optionally called once per fixture
316 * to declare fixture variant
317 *
318 * @fixture_name: fixture name
319 *
320 * .. code-block:: c
321 *
322 * FIXTURE_VARIANT(fixture_name) {
323 * type property1;
324 * ...
325 * };
326 *
327 * Defines type of constant parameters provided to FIXTURE_SETUP(), TEST_F() and
328 * FIXTURE_TEARDOWN as *variant*. Variants allow the same tests to be run with
329 * different arguments.
330 */
331 #define FIXTURE_VARIANT(fixture_name) struct _fixture_variant_##fixture_name
332
333 /**
334 * FIXTURE_VARIANT_ADD() - Called once per fixture
335 * variant to setup and register the data
336 *
337 * @fixture_name: fixture name
338 * @variant_name: name of the parameter set
339 *
340 * .. code-block:: c
341 *
342 * FIXTURE_VARIANT_ADD(fixture_name, variant_name) {
343 * .property1 = val1,
344 * ...
345 * };
346 *
347 * Defines a variant of the test fixture, provided to FIXTURE_SETUP() and
348 * TEST_F() as *variant*. Tests of each fixture will be run once for each
349 * variant.
350 */
351 #define FIXTURE_VARIANT_ADD(fixture_name, variant_name) \
352 extern const FIXTURE_VARIANT(fixture_name) \
353 _##fixture_name##_##variant_name##_variant; \
354 static struct __fixture_variant_metadata \
355 _##fixture_name##_##variant_name##_object = \
356 { .name = #variant_name, \
357 .data = &_##fixture_name##_##variant_name##_variant}; \
358 static void __attribute__((constructor)) \
359 _register_##fixture_name##_##variant_name(void) \
360 { \
361 __register_fixture_variant(&_##fixture_name##_fixture_object, \
362 &_##fixture_name##_##variant_name##_object); \
363 } \
364 const FIXTURE_VARIANT(fixture_name) \
365 _##fixture_name##_##variant_name##_variant =
366
367 /**
368 * TEST_F() - Emits test registration and helpers for
369 * fixture-based test cases
370 *
371 * @fixture_name: fixture name
372 * @test_name: test name
373 *
374 * .. code-block:: c
375 *
376 * TEST_F(fixture, name) { implementation }
377 *
378 * Defines a test that depends on a fixture (e.g., is part of a test case).
379 * Very similar to TEST() except that *self* is the setup instance of fixture's
380 * datatype exposed for use by the implementation.
381 *
382 * The _metadata object is shared (MAP_SHARED) with all the potential forked
383 * processes, which enables them to use EXCEPT_*() and ASSERT_*().
384 *
385 * The *self* object is only shared with the potential forked processes if
386 * FIXTURE_TEARDOWN_PARENT() is used instead of FIXTURE_TEARDOWN().
387 */
388 #define TEST_F(fixture_name, test_name) \
389 __TEST_F_IMPL(fixture_name, test_name, -1, TEST_TIMEOUT_DEFAULT)
390
391 #define TEST_F_SIGNAL(fixture_name, test_name, signal) \
392 __TEST_F_IMPL(fixture_name, test_name, signal, TEST_TIMEOUT_DEFAULT)
393
394 #define TEST_F_TIMEOUT(fixture_name, test_name, timeout) \
395 __TEST_F_IMPL(fixture_name, test_name, -1, timeout)
396
397 #define __TEST_F_IMPL(fixture_name, test_name, signal, tmout) \
398 static void fixture_name##_##test_name( \
399 struct __test_metadata *_metadata, \
400 FIXTURE_DATA(fixture_name) *self, \
401 const FIXTURE_VARIANT(fixture_name) *variant); \
402 static void wrapper_##fixture_name##_##test_name( \
403 struct __test_metadata *_metadata, \
404 struct __fixture_variant_metadata *variant) \
405 { \
406 /* fixture data is alloced, setup, and torn down per call. */ \
407 FIXTURE_DATA(fixture_name) self_private, *self = NULL; \
408 pid_t child = 1; \
409 int status = 0; \
410 /* Makes sure there is only one teardown, even when child forks again. */ \
411 _metadata->no_teardown = mmap(NULL, sizeof(*_metadata->no_teardown), \
412 PROT_READ | PROT_WRITE, MAP_SHARED | MAP_ANONYMOUS, -1, 0); \
413 *_metadata->no_teardown = true; \
414 if (sizeof(*self) > 0) { \
415 if (fixture_name##_teardown_parent) { \
416 self = mmap(NULL, sizeof(*self), PROT_READ | PROT_WRITE, \
417 MAP_SHARED | MAP_ANONYMOUS, -1, 0); \
418 } else { \
419 memset(&self_private, 0, sizeof(self_private)); \
420 self = &self_private; \
421 } \
422 } \
423 _metadata->variant = variant->data; \
424 _metadata->self = self; \
425 /* _metadata and potentially self are shared with all forks. */ \
426 child = fork(); \
427 if (child == 0) { \
428 fixture_name##_setup(_metadata, self, variant->data); \
429 /* Let setup failure terminate early. */ \
430 if (_metadata->exit_code) \
431 _exit(0); \
432 *_metadata->no_teardown = false; \
433 fixture_name##_##test_name(_metadata, self, variant->data); \
434 _metadata->teardown_fn(false, _metadata, self, variant->data); \
435 _exit(0); \
436 } else if (child < 0 || child != waitpid(child, &status, 0)) { \
437 ksft_print_msg("ERROR SPAWNING TEST GRANDCHILD\n"); \
438 _metadata->exit_code = KSFT_FAIL; \
439 } \
440 _metadata->teardown_fn(true, _metadata, self, variant->data); \
441 munmap(_metadata->no_teardown, sizeof(*_metadata->no_teardown)); \
442 _metadata->no_teardown = NULL; \
443 if (self && fixture_name##_teardown_parent) \
444 munmap(self, sizeof(*self)); \
445 if (WIFEXITED(status)) { \
446 if (WEXITSTATUS(status)) \
447 _metadata->exit_code = WEXITSTATUS(status); \
448 } else if (WIFSIGNALED(status)) { \
449 /* Forward signal to __wait_for_test(). */ \
450 kill(getpid(), WTERMSIG(status)); \
451 } \
452 } \
453 static void wrapper_##fixture_name##_##test_name##_teardown( \
454 bool in_parent, struct __test_metadata *_metadata, \
455 void *self, const void *variant) \
456 { \
457 if (fixture_name##_teardown_parent == in_parent && \
458 !__atomic_test_and_set(_metadata->no_teardown, __ATOMIC_RELAXED)) \
459 fixture_name##_teardown(_metadata, self, variant); \
460 } \
461 static struct __test_metadata *_##fixture_name##_##test_name##_object; \
462 static void __attribute__((constructor)) \
463 _register_##fixture_name##_##test_name(void) \
464 { \
465 struct __test_metadata *object = mmap(NULL, sizeof(*object), \
466 PROT_READ | PROT_WRITE, MAP_SHARED | MAP_ANONYMOUS, -1, 0); \
467 object->name = #test_name; \
468 object->fn = &wrapper_##fixture_name##_##test_name; \
469 object->fixture = &_##fixture_name##_fixture_object; \
470 object->teardown_fn = &wrapper_##fixture_name##_##test_name##_teardown; \
471 object->termsig = signal; \
472 object->timeout = tmout; \
473 _##fixture_name##_##test_name##_object = object; \
474 __register_test(object); \
475 } \
476 static void fixture_name##_##test_name( \
477 struct __test_metadata __attribute__((unused)) *_metadata, \
478 FIXTURE_DATA(fixture_name) __attribute__((unused)) *self, \
479 const FIXTURE_VARIANT(fixture_name) \
480 __attribute__((unused)) *variant)
481
482 /**
483 * TEST_HARNESS_MAIN - Simple wrapper to run the test harness
484 *
485 * .. code-block:: c
486 *
487 * TEST_HARNESS_MAIN
488 *
489 * Use once to append a main() to the test file.
490 */
491 #define TEST_HARNESS_MAIN \
492 int main(int argc, char **argv) { \
493 return test_harness_run(argc, argv); \
494 }
495
496 /**
497 * DOC: operators
498 *
499 * Operators for use in TEST() and TEST_F().
500 * ASSERT_* calls will stop test execution immediately.
501 * EXPECT_* calls will emit a failure warning, note it, and continue.
502 */
503
504 /**
505 * ASSERT_EQ()
506 *
507 * @expected: expected value
508 * @seen: measured value
509 *
510 * ASSERT_EQ(expected, measured): expected == measured
511 */
512 #define ASSERT_EQ(expected, seen) \
513 __EXPECT(expected, #expected, seen, #seen, ==, 1)
514
515 /**
516 * ASSERT_NE()
517 *
518 * @expected: expected value
519 * @seen: measured value
520 *
521 * ASSERT_NE(expected, measured): expected != measured
522 */
523 #define ASSERT_NE(expected, seen) \
524 __EXPECT(expected, #expected, seen, #seen, !=, 1)
525
526 /**
527 * ASSERT_LT()
528 *
529 * @expected: expected value
530 * @seen: measured value
531 *
532 * ASSERT_LT(expected, measured): expected < measured
533 */
534 #define ASSERT_LT(expected, seen) \
535 __EXPECT(expected, #expected, seen, #seen, <, 1)
536
537 /**
538 * ASSERT_LE()
539 *
540 * @expected: expected value
541 * @seen: measured value
542 *
543 * ASSERT_LE(expected, measured): expected <= measured
544 */
545 #define ASSERT_LE(expected, seen) \
546 __EXPECT(expected, #expected, seen, #seen, <=, 1)
547
548 /**
549 * ASSERT_GT()
550 *
551 * @expected: expected value
552 * @seen: measured value
553 *
554 * ASSERT_GT(expected, measured): expected > measured
555 */
556 #define ASSERT_GT(expected, seen) \
557 __EXPECT(expected, #expected, seen, #seen, >, 1)
558
559 /**
560 * ASSERT_GE()
561 *
562 * @expected: expected value
563 * @seen: measured value
564 *
565 * ASSERT_GE(expected, measured): expected >= measured
566 */
567 #define ASSERT_GE(expected, seen) \
568 __EXPECT(expected, #expected, seen, #seen, >=, 1)
569
570 /**
571 * ASSERT_NULL()
572 *
573 * @seen: measured value
574 *
575 * ASSERT_NULL(measured): NULL == measured
576 */
577 #define ASSERT_NULL(seen) \
578 __EXPECT(NULL, "NULL", seen, #seen, ==, 1)
579
580 /**
581 * ASSERT_TRUE()
582 *
583 * @seen: measured value
584 *
585 * ASSERT_TRUE(measured): measured != 0
586 */
587 #define ASSERT_TRUE(seen) \
588 __EXPECT(0, "0", seen, #seen, !=, 1)
589
590 /**
591 * ASSERT_FALSE()
592 *
593 * @seen: measured value
594 *
595 * ASSERT_FALSE(measured): measured == 0
596 */
597 #define ASSERT_FALSE(seen) \
598 __EXPECT(0, "0", seen, #seen, ==, 1)
599
600 /**
601 * ASSERT_STREQ()
602 *
603 * @expected: expected value
604 * @seen: measured value
605 *
606 * ASSERT_STREQ(expected, measured): !strcmp(expected, measured)
607 */
608 #define ASSERT_STREQ(expected, seen) \
609 __EXPECT_STR(expected, seen, ==, 1)
610
611 /**
612 * ASSERT_STRNE()
613 *
614 * @expected: expected value
615 * @seen: measured value
616 *
617 * ASSERT_STRNE(expected, measured): strcmp(expected, measured)
618 */
619 #define ASSERT_STRNE(expected, seen) \
620 __EXPECT_STR(expected, seen, !=, 1)
621
622 /**
623 * EXPECT_EQ()
624 *
625 * @expected: expected value
626 * @seen: measured value
627 *
628 * EXPECT_EQ(expected, measured): expected == measured
629 */
630 #define EXPECT_EQ(expected, seen) \
631 __EXPECT(expected, #expected, seen, #seen, ==, 0)
632
633 /**
634 * EXPECT_NE()
635 *
636 * @expected: expected value
637 * @seen: measured value
638 *
639 * EXPECT_NE(expected, measured): expected != measured
640 */
641 #define EXPECT_NE(expected, seen) \
642 __EXPECT(expected, #expected, seen, #seen, !=, 0)
643
644 /**
645 * EXPECT_LT()
646 *
647 * @expected: expected value
648 * @seen: measured value
649 *
650 * EXPECT_LT(expected, measured): expected < measured
651 */
652 #define EXPECT_LT(expected, seen) \
653 __EXPECT(expected, #expected, seen, #seen, <, 0)
654
655 /**
656 * EXPECT_LE()
657 *
658 * @expected: expected value
659 * @seen: measured value
660 *
661 * EXPECT_LE(expected, measured): expected <= measured
662 */
663 #define EXPECT_LE(expected, seen) \
664 __EXPECT(expected, #expected, seen, #seen, <=, 0)
665
666 /**
667 * EXPECT_GT()
668 *
669 * @expected: expected value
670 * @seen: measured value
671 *
672 * EXPECT_GT(expected, measured): expected > measured
673 */
674 #define EXPECT_GT(expected, seen) \
675 __EXPECT(expected, #expected, seen, #seen, >, 0)
676
677 /**
678 * EXPECT_GE()
679 *
680 * @expected: expected value
681 * @seen: measured value
682 *
683 * EXPECT_GE(expected, measured): expected >= measured
684 */
685 #define EXPECT_GE(expected, seen) \
686 __EXPECT(expected, #expected, seen, #seen, >=, 0)
687
688 /**
689 * EXPECT_NULL()
690 *
691 * @seen: measured value
692 *
693 * EXPECT_NULL(measured): NULL == measured
694 */
695 #define EXPECT_NULL(seen) \
696 __EXPECT(NULL, "NULL", seen, #seen, ==, 0)
697
698 /**
699 * EXPECT_TRUE()
700 *
701 * @seen: measured value
702 *
703 * EXPECT_TRUE(measured): 0 != measured
704 */
705 #define EXPECT_TRUE(seen) \
706 __EXPECT(0, "0", seen, #seen, !=, 0)
707
708 /**
709 * EXPECT_FALSE()
710 *
711 * @seen: measured value
712 *
713 * EXPECT_FALSE(measured): 0 == measured
714 */
715 #define EXPECT_FALSE(seen) \
716 __EXPECT(0, "0", seen, #seen, ==, 0)
717
718 /**
719 * EXPECT_STREQ()
720 *
721 * @expected: expected value
722 * @seen: measured value
723 *
724 * EXPECT_STREQ(expected, measured): !strcmp(expected, measured)
725 */
726 #define EXPECT_STREQ(expected, seen) \
727 __EXPECT_STR(expected, seen, ==, 0)
728
729 /**
730 * EXPECT_STRNE()
731 *
732 * @expected: expected value
733 * @seen: measured value
734 *
735 * EXPECT_STRNE(expected, measured): strcmp(expected, measured)
736 */
737 #define EXPECT_STRNE(expected, seen) \
738 __EXPECT_STR(expected, seen, !=, 0)
739
740 #ifndef ARRAY_SIZE
741 #define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))
742 #endif
743
744 /* Support an optional handler after and ASSERT_* or EXPECT_*. The approach is
745 * not thread-safe, but it should be fine in most sane test scenarios.
746 *
747 * Using __bail(), which optionally abort()s, is the easiest way to early
748 * return while still providing an optional block to the API consumer.
749 */
750 #define OPTIONAL_HANDLER(_assert) \
751 for (; _metadata->trigger; _metadata->trigger = \
752 __bail(_assert, _metadata))
753
754 #define is_signed_type(var) (!!(((__typeof__(var))(-1)) < (__typeof__(var))1))
755
756 #define __EXPECT(_expected, _expected_str, _seen, _seen_str, _t, _assert) do { \
757 /* Avoid multiple evaluation of the cases */ \
758 __typeof__(_expected) __exp = (_expected); \
759 __typeof__(_seen) __seen = (_seen); \
760 if (!(__exp _t __seen)) { \
761 /* Report with actual signedness to avoid weird output. */ \
762 switch (is_signed_type(__exp) * 2 + is_signed_type(__seen)) { \
763 case 0: { \
764 uintmax_t __exp_print = (uintmax_t)__exp; \
765 uintmax_t __seen_print = (uintmax_t)__seen; \
766 __TH_LOG("Expected %s (%ju) %s %s (%ju)", \
767 _expected_str, __exp_print, #_t, \
768 _seen_str, __seen_print); \
769 break; \
770 } \
771 case 1: { \
772 uintmax_t __exp_print = (uintmax_t)__exp; \
773 intmax_t __seen_print = (intmax_t)__seen; \
774 __TH_LOG("Expected %s (%ju) %s %s (%jd)", \
775 _expected_str, __exp_print, #_t, \
776 _seen_str, __seen_print); \
777 break; \
778 } \
779 case 2: { \
780 intmax_t __exp_print = (intmax_t)__exp; \
781 uintmax_t __seen_print = (uintmax_t)__seen; \
782 __TH_LOG("Expected %s (%jd) %s %s (%ju)", \
783 _expected_str, __exp_print, #_t, \
784 _seen_str, __seen_print); \
785 break; \
786 } \
787 case 3: { \
788 intmax_t __exp_print = (intmax_t)__exp; \
789 intmax_t __seen_print = (intmax_t)__seen; \
790 __TH_LOG("Expected %s (%jd) %s %s (%jd)", \
791 _expected_str, __exp_print, #_t, \
792 _seen_str, __seen_print); \
793 break; \
794 } \
795 } \
796 _metadata->exit_code = KSFT_FAIL; \
797 /* Ensure the optional handler is triggered */ \
798 _metadata->trigger = 1; \
799 } \
800 } while (0); OPTIONAL_HANDLER(_assert)
801
802 #define __EXPECT_STR(_expected, _seen, _t, _assert) do { \
803 const char *__exp = (_expected); \
804 const char *__seen = (_seen); \
805 if (!(strcmp(__exp, __seen) _t 0)) { \
806 __TH_LOG("Expected '%s' %s '%s'.", __exp, #_t, __seen); \
807 _metadata->exit_code = KSFT_FAIL; \
808 _metadata->trigger = 1; \
809 } \
810 } while (0); OPTIONAL_HANDLER(_assert)
811
812 /* List helpers */
813 #define __LIST_APPEND(head, item) \
814 { \
815 /* Circular linked list where only prev is circular. */ \
816 if (head == NULL) { \
817 head = item; \
818 item->next = NULL; \
819 item->prev = item; \
820 return; \
821 } \
822 if (__constructor_order_forward) { \
823 item->next = NULL; \
824 item->prev = head->prev; \
825 item->prev->next = item; \
826 head->prev = item; \
827 } else { \
828 item->next = head; \
829 item->next->prev = item; \
830 item->prev = item; \
831 head = item; \
832 } \
833 }
834
835 struct __test_results {
836 char reason[1024]; /* Reason for test result */
837 };
838
839 struct __test_metadata;
840 struct __fixture_variant_metadata;
841
842 /* Contains all the information about a fixture. */
843 struct __fixture_metadata {
844 const char *name;
845 struct __test_metadata *tests;
846 struct __fixture_variant_metadata *variant;
847 struct __fixture_metadata *prev, *next;
848 } _fixture_global __attribute__((unused)) = {
849 .name = "global",
850 .prev = &_fixture_global,
851 };
852
853 struct __test_xfail {
854 struct __fixture_metadata *fixture;
855 struct __fixture_variant_metadata *variant;
856 struct __test_metadata *test;
857 struct __test_xfail *prev, *next;
858 };
859
860 /**
861 * XFAIL_ADD() - mark variant + test case combination as expected to fail
862 * @fixture_name: name of the fixture
863 * @variant_name: name of the variant
864 * @test_name: name of the test case
865 *
866 * Mark a combination of variant + test case for a given fixture as expected
867 * to fail. Tests marked this way will report XPASS / XFAIL return codes,
868 * instead of PASS / FAIL,and use respective counters.
869 */
870 #define XFAIL_ADD(fixture_name, variant_name, test_name) \
871 static struct __test_xfail \
872 _##fixture_name##_##variant_name##_##test_name##_xfail = \
873 { \
874 .fixture = &_##fixture_name##_fixture_object, \
875 .variant = &_##fixture_name##_##variant_name##_object, \
876 }; \
877 static void __attribute__((constructor)) \
878 _register_##fixture_name##_##variant_name##_##test_name##_xfail(void) \
879 { \
880 _##fixture_name##_##variant_name##_##test_name##_xfail.test = \
881 _##fixture_name##_##test_name##_object; \
882 __register_xfail(&_##fixture_name##_##variant_name##_##test_name##_xfail); \
883 }
884
885 static struct __fixture_metadata *__fixture_list = &_fixture_global;
886 static bool __constructor_order_forward;
887
__register_fixture(struct __fixture_metadata * f)888 static inline void __register_fixture(struct __fixture_metadata *f)
889 {
890 __LIST_APPEND(__fixture_list, f);
891 }
892
893 struct __fixture_variant_metadata {
894 const char *name;
895 const void *data;
896 struct __test_xfail *xfails;
897 struct __fixture_variant_metadata *prev, *next;
898 };
899
900 static inline void
__register_fixture_variant(struct __fixture_metadata * f,struct __fixture_variant_metadata * variant)901 __register_fixture_variant(struct __fixture_metadata *f,
902 struct __fixture_variant_metadata *variant)
903 {
904 __LIST_APPEND(f->variant, variant);
905 }
906
907 /* Contains all the information for test execution and status checking. */
908 struct __test_metadata {
909 const char *name;
910 void (*fn)(struct __test_metadata *,
911 struct __fixture_variant_metadata *);
912 pid_t pid; /* pid of test when being run */
913 struct __fixture_metadata *fixture;
914 void (*teardown_fn)(bool in_parent, struct __test_metadata *_metadata,
915 void *self, const void *variant);
916 int termsig;
917 int exit_code;
918 int trigger; /* extra handler after the evaluation */
919 int timeout; /* seconds to wait for test timeout */
920 bool aborted; /* stopped test due to failed ASSERT */
921 bool *no_teardown; /* fixture needs teardown */
922 void *self;
923 const void *variant;
924 struct __test_results *results;
925 struct __test_metadata *prev, *next;
926 };
927
__test_passed(struct __test_metadata * metadata)928 static inline bool __test_passed(struct __test_metadata *metadata)
929 {
930 return metadata->exit_code != KSFT_FAIL &&
931 metadata->exit_code <= KSFT_SKIP;
932 }
933
934 /*
935 * Since constructors are called in reverse order, reverse the test
936 * list so tests are run in source declaration order.
937 * https://gcc.gnu.org/onlinedocs/gccint/Initialization.html
938 * However, it seems not all toolchains do this correctly, so use
939 * __constructor_order_foward to detect which direction is called first
940 * and adjust list building logic to get things running in the right
941 * direction.
942 */
__register_test(struct __test_metadata * t)943 static inline void __register_test(struct __test_metadata *t)
944 {
945 __LIST_APPEND(t->fixture->tests, t);
946 }
947
__register_xfail(struct __test_xfail * xf)948 static inline void __register_xfail(struct __test_xfail *xf)
949 {
950 __LIST_APPEND(xf->variant->xfails, xf);
951 }
952
__bail(int for_realz,struct __test_metadata * t)953 static inline int __bail(int for_realz, struct __test_metadata *t)
954 {
955 /* if this is ASSERT, return immediately. */
956 if (for_realz) {
957 if (t->teardown_fn)
958 t->teardown_fn(false, t, t->self, t->variant);
959 abort();
960 }
961 /* otherwise, end the for loop and continue. */
962 return 0;
963 }
964
__wait_for_test(struct __test_metadata * t)965 static void __wait_for_test(struct __test_metadata *t)
966 {
967 /*
968 * Sets status so that WIFEXITED(status) returns true and
969 * WEXITSTATUS(status) returns KSFT_FAIL. This safe default value
970 * should never be evaluated because of the waitpid(2) check and
971 * timeout handling.
972 */
973 int status = KSFT_FAIL << 8;
974 struct pollfd poll_child;
975 int ret, child, childfd;
976 bool timed_out = false;
977
978 childfd = syscall(__NR_pidfd_open, t->pid, 0);
979 if (childfd == -1) {
980 t->exit_code = KSFT_FAIL;
981 fprintf(TH_LOG_STREAM,
982 "# %s: unable to open pidfd\n",
983 t->name);
984 return;
985 }
986
987 poll_child.fd = childfd;
988 poll_child.events = POLLIN;
989 ret = poll(&poll_child, 1, t->timeout * 1000);
990 if (ret == -1) {
991 t->exit_code = KSFT_FAIL;
992 fprintf(TH_LOG_STREAM,
993 "# %s: unable to wait on child pidfd\n",
994 t->name);
995 return;
996 } else if (ret == 0) {
997 timed_out = true;
998 /* signal process group */
999 kill(-(t->pid), SIGKILL);
1000 }
1001 child = waitpid(t->pid, &status, WNOHANG);
1002 if (child == -1 && errno != EINTR) {
1003 t->exit_code = KSFT_FAIL;
1004 fprintf(TH_LOG_STREAM,
1005 "# %s: Failed to wait for PID %d (errno: %d)\n",
1006 t->name, t->pid, errno);
1007 return;
1008 }
1009
1010 if (timed_out) {
1011 t->exit_code = KSFT_FAIL;
1012 fprintf(TH_LOG_STREAM,
1013 "# %s: Test terminated by timeout\n", t->name);
1014 } else if (WIFEXITED(status)) {
1015 if (WEXITSTATUS(status) == KSFT_SKIP ||
1016 WEXITSTATUS(status) == KSFT_XPASS ||
1017 WEXITSTATUS(status) == KSFT_XFAIL) {
1018 t->exit_code = WEXITSTATUS(status);
1019 } else if (t->termsig != -1) {
1020 t->exit_code = KSFT_FAIL;
1021 fprintf(TH_LOG_STREAM,
1022 "# %s: Test exited normally instead of by signal (code: %d)\n",
1023 t->name,
1024 WEXITSTATUS(status));
1025 } else {
1026 switch (WEXITSTATUS(status)) {
1027 /* Success */
1028 case KSFT_PASS:
1029 t->exit_code = KSFT_PASS;
1030 break;
1031 /* Failure */
1032 default:
1033 t->exit_code = KSFT_FAIL;
1034 fprintf(TH_LOG_STREAM,
1035 "# %s: Test failed\n",
1036 t->name);
1037 }
1038 }
1039 } else if (WIFSIGNALED(status)) {
1040 t->exit_code = KSFT_FAIL;
1041 if (WTERMSIG(status) == SIGABRT) {
1042 fprintf(TH_LOG_STREAM,
1043 "# %s: Test terminated by assertion\n",
1044 t->name);
1045 } else if (WTERMSIG(status) == t->termsig) {
1046 t->exit_code = KSFT_PASS;
1047 } else {
1048 fprintf(TH_LOG_STREAM,
1049 "# %s: Test terminated unexpectedly by signal %d\n",
1050 t->name,
1051 WTERMSIG(status));
1052 }
1053 } else {
1054 t->exit_code = KSFT_FAIL;
1055 fprintf(TH_LOG_STREAM,
1056 "# %s: Test ended in some other way [%u]\n",
1057 t->name,
1058 status);
1059 }
1060 }
1061
test_harness_list_tests(void)1062 static void test_harness_list_tests(void)
1063 {
1064 struct __fixture_variant_metadata *v;
1065 struct __fixture_metadata *f;
1066 struct __test_metadata *t;
1067
1068 for (f = __fixture_list; f; f = f->next) {
1069 v = f->variant;
1070 t = f->tests;
1071
1072 if (f == __fixture_list)
1073 fprintf(stderr, "%-20s %-25s %s\n",
1074 "# FIXTURE", "VARIANT", "TEST");
1075 else
1076 fprintf(stderr, "--------------------------------------------------------------------------------\n");
1077
1078 do {
1079 fprintf(stderr, "%-20s %-25s %s\n",
1080 t == f->tests ? f->name : "",
1081 v ? v->name : "",
1082 t ? t->name : "");
1083
1084 v = v ? v->next : NULL;
1085 t = t ? t->next : NULL;
1086 } while (v || t);
1087 }
1088 }
1089
test_harness_argv_check(int argc,char ** argv)1090 static int test_harness_argv_check(int argc, char **argv)
1091 {
1092 int opt;
1093
1094 while ((opt = getopt(argc, argv, "hlF:f:V:v:t:T:r:")) != -1) {
1095 switch (opt) {
1096 case 'f':
1097 case 'F':
1098 case 'v':
1099 case 'V':
1100 case 't':
1101 case 'T':
1102 case 'r':
1103 break;
1104 case 'l':
1105 test_harness_list_tests();
1106 return KSFT_SKIP;
1107 case 'h':
1108 default:
1109 fprintf(stderr,
1110 "Usage: %s [-h|-l] [-t|-T|-v|-V|-f|-F|-r name]\n"
1111 "\t-h print help\n"
1112 "\t-l list all tests\n"
1113 "\n"
1114 "\t-t name include test\n"
1115 "\t-T name exclude test\n"
1116 "\t-v name include variant\n"
1117 "\t-V name exclude variant\n"
1118 "\t-f name include fixture\n"
1119 "\t-F name exclude fixture\n"
1120 "\t-r name run specified test\n"
1121 "\n"
1122 "Test filter options can be specified "
1123 "multiple times. The filtering stops\n"
1124 "at the first match. For example to "
1125 "include all tests from variant 'bla'\n"
1126 "but not test 'foo' specify '-T foo -v bla'.\n"
1127 "", argv[0]);
1128 return opt == 'h' ? KSFT_SKIP : KSFT_FAIL;
1129 }
1130 }
1131
1132 return KSFT_PASS;
1133 }
1134
test_enabled(int argc,char ** argv,struct __fixture_metadata * f,struct __fixture_variant_metadata * v,struct __test_metadata * t)1135 static bool test_enabled(int argc, char **argv,
1136 struct __fixture_metadata *f,
1137 struct __fixture_variant_metadata *v,
1138 struct __test_metadata *t)
1139 {
1140 unsigned int flen = 0, vlen = 0, tlen = 0;
1141 bool has_positive = false;
1142 int opt;
1143
1144 optind = 1;
1145 while ((opt = getopt(argc, argv, "F:f:V:v:t:T:r:")) != -1) {
1146 has_positive |= islower(opt);
1147
1148 switch (tolower(opt)) {
1149 case 't':
1150 if (!strcmp(t->name, optarg))
1151 return islower(opt);
1152 break;
1153 case 'f':
1154 if (!strcmp(f->name, optarg))
1155 return islower(opt);
1156 break;
1157 case 'v':
1158 if (!strcmp(v->name, optarg))
1159 return islower(opt);
1160 break;
1161 case 'r':
1162 if (!tlen) {
1163 flen = strlen(f->name);
1164 vlen = strlen(v->name);
1165 tlen = strlen(t->name);
1166 }
1167 if (strlen(optarg) == flen + 1 + vlen + !!vlen + tlen &&
1168 !strncmp(f->name, &optarg[0], flen) &&
1169 !strncmp(v->name, &optarg[flen + 1], vlen) &&
1170 !strncmp(t->name, &optarg[flen + 1 + vlen + !!vlen], tlen))
1171 return true;
1172 break;
1173 }
1174 }
1175
1176 /*
1177 * If there are no positive tests then we assume user just wants
1178 * exclusions and everything else is a pass.
1179 */
1180 return !has_positive;
1181 }
1182
__run_test(struct __fixture_metadata * f,struct __fixture_variant_metadata * variant,struct __test_metadata * t)1183 static void __run_test(struct __fixture_metadata *f,
1184 struct __fixture_variant_metadata *variant,
1185 struct __test_metadata *t)
1186 {
1187 struct __test_xfail *xfail;
1188 char test_name[1024];
1189 const char *diagnostic;
1190 int child;
1191
1192 /* reset test struct */
1193 t->exit_code = KSFT_PASS;
1194 t->trigger = 0;
1195 t->aborted = false;
1196 t->no_teardown = NULL;
1197 memset(t->results->reason, 0, sizeof(t->results->reason));
1198
1199 snprintf(test_name, sizeof(test_name), "%s%s%s.%s",
1200 f->name, variant->name[0] ? "." : "", variant->name, t->name);
1201
1202 ksft_print_msg(" RUN %s ...\n", test_name);
1203
1204 /* Make sure output buffers are flushed before fork */
1205 fflush(stdout);
1206 fflush(stderr);
1207
1208 child = fork();
1209 if (child < 0) {
1210 ksft_print_msg("ERROR SPAWNING TEST CHILD\n");
1211 t->exit_code = KSFT_FAIL;
1212 } else if (child == 0) {
1213 setpgrp();
1214 t->fn(t, variant);
1215 _exit(t->exit_code);
1216 } else {
1217 t->pid = child;
1218 __wait_for_test(t);
1219 }
1220 ksft_print_msg(" %4s %s\n",
1221 __test_passed(t) ? "OK" : "FAIL", test_name);
1222
1223 /* Check if we're expecting this test to fail */
1224 for (xfail = variant->xfails; xfail; xfail = xfail->next)
1225 if (xfail->test == t)
1226 break;
1227 if (xfail)
1228 t->exit_code = __test_passed(t) ? KSFT_XPASS : KSFT_XFAIL;
1229
1230 if (t->results->reason[0])
1231 diagnostic = t->results->reason;
1232 else if (t->exit_code == KSFT_PASS || t->exit_code == KSFT_FAIL)
1233 diagnostic = NULL;
1234 else
1235 diagnostic = "unknown";
1236
1237 ksft_test_result_code(t->exit_code, test_name,
1238 diagnostic ? "%s" : NULL, diagnostic);
1239 }
1240
test_harness_run(int argc,char ** argv)1241 static int test_harness_run(int argc, char **argv)
1242 {
1243 struct __fixture_variant_metadata no_variant = { .name = "", };
1244 struct __fixture_variant_metadata *v;
1245 struct __fixture_metadata *f;
1246 struct __test_results *results;
1247 struct __test_metadata *t;
1248 int ret;
1249 unsigned int case_count = 0, test_count = 0;
1250 unsigned int count = 0;
1251 unsigned int pass_count = 0;
1252
1253 ret = test_harness_argv_check(argc, argv);
1254 if (ret != KSFT_PASS)
1255 return ret;
1256
1257 for (f = __fixture_list; f; f = f->next) {
1258 for (v = f->variant ?: &no_variant; v; v = v->next) {
1259 unsigned int old_tests = test_count;
1260
1261 for (t = f->tests; t; t = t->next)
1262 if (test_enabled(argc, argv, f, v, t))
1263 test_count++;
1264
1265 if (old_tests != test_count)
1266 case_count++;
1267 }
1268 }
1269
1270 results = mmap(NULL, sizeof(*results), PROT_READ | PROT_WRITE,
1271 MAP_SHARED | MAP_ANONYMOUS, -1, 0);
1272
1273 ksft_print_header();
1274 ksft_set_plan(test_count);
1275 ksft_print_msg("Starting %u tests from %u test cases.\n",
1276 test_count, case_count);
1277 for (f = __fixture_list; f; f = f->next) {
1278 for (v = f->variant ?: &no_variant; v; v = v->next) {
1279 for (t = f->tests; t; t = t->next) {
1280 if (!test_enabled(argc, argv, f, v, t))
1281 continue;
1282 count++;
1283 t->results = results;
1284 __run_test(f, v, t);
1285 t->results = NULL;
1286 if (__test_passed(t))
1287 pass_count++;
1288 else
1289 ret = 1;
1290 }
1291 }
1292 }
1293 munmap(results, sizeof(*results));
1294
1295 ksft_print_msg("%s: %u / %u tests passed.\n", ret ? "FAILED" : "PASSED",
1296 pass_count, count);
1297 ksft_exit(ret == 0);
1298
1299 /* unreachable */
1300 return KSFT_FAIL;
1301 }
1302
__constructor_order_first(void)1303 static void __attribute__((constructor)) __constructor_order_first(void)
1304 {
1305 __constructor_order_forward = true;
1306 }
1307
1308 #endif /* __KSELFTEST_HARNESS_H */
1309