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