1 /* 2 * Copyright (c) 2012 The Chromium OS Authors. All rights reserved. 3 * Use of this source code is governed by the GPLv2 license. 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 #define _GNU_SOURCE 54 #include <stdint.h> 55 #include <stdio.h> 56 #include <stdlib.h> 57 #include <string.h> 58 #include <sys/types.h> 59 #include <sys/wait.h> 60 #include <unistd.h> 61 62 63 /* Utilities exposed to the test definitions */ 64 #ifndef TH_LOG_STREAM 65 # define TH_LOG_STREAM stderr 66 #endif 67 68 #ifndef TH_LOG_ENABLED 69 # define TH_LOG_ENABLED 1 70 #endif 71 72 /** 73 * TH_LOG(fmt, ...) 74 * 75 * @fmt: format string 76 * @...: optional arguments 77 * 78 * .. code-block:: c 79 * 80 * TH_LOG(format, ...) 81 * 82 * Optional debug logging function available for use in tests. 83 * Logging may be enabled or disabled by defining TH_LOG_ENABLED. 84 * E.g., #define TH_LOG_ENABLED 1 85 * 86 * If no definition is provided, logging is enabled by default. 87 */ 88 #define TH_LOG(fmt, ...) do { \ 89 if (TH_LOG_ENABLED) \ 90 __TH_LOG(fmt, ##__VA_ARGS__); \ 91 } while (0) 92 93 /* Unconditional logger for internal use. */ 94 #define __TH_LOG(fmt, ...) \ 95 fprintf(TH_LOG_STREAM, "%s:%d:%s:" fmt "\n", \ 96 __FILE__, __LINE__, _metadata->name, ##__VA_ARGS__) 97 98 /** 99 * TEST(test_name) - Defines the test function and creates the registration 100 * stub 101 * 102 * @test_name: test name 103 * 104 * .. code-block:: c 105 * 106 * TEST(name) { implementation } 107 * 108 * Defines a test by name. 109 * Names must be unique and tests must not be run in parallel. The 110 * implementation containing block is a function and scoping should be treated 111 * as such. Returning early may be performed with a bare "return;" statement. 112 * 113 * EXPECT_* and ASSERT_* are valid in a TEST() { } context. 114 */ 115 #define TEST(test_name) __TEST_IMPL(test_name, -1) 116 117 /** 118 * TEST_SIGNAL(test_name, signal) 119 * 120 * @test_name: test name 121 * @signal: signal number 122 * 123 * .. code-block:: c 124 * 125 * TEST_SIGNAL(name, signal) { implementation } 126 * 127 * Defines a test by name and the expected term signal. 128 * Names must be unique and tests must not be run in parallel. The 129 * implementation containing block is a function and scoping should be treated 130 * as such. Returning early may be performed with a bare "return;" statement. 131 * 132 * EXPECT_* and ASSERT_* are valid in a TEST() { } context. 133 */ 134 #define TEST_SIGNAL(test_name, signal) __TEST_IMPL(test_name, signal) 135 136 #define __TEST_IMPL(test_name, _signal) \ 137 static void test_name(struct __test_metadata *_metadata); \ 138 static struct __test_metadata _##test_name##_object = \ 139 { name: "global." #test_name, \ 140 fn: &test_name, termsig: _signal }; \ 141 static void __attribute__((constructor)) _register_##test_name(void) \ 142 { \ 143 __register_test(&_##test_name##_object); \ 144 } \ 145 static void test_name( \ 146 struct __test_metadata __attribute__((unused)) *_metadata) 147 148 /** 149 * FIXTURE_DATA(datatype_name) - Wraps the struct name so we have one less 150 * argument to pass around 151 * 152 * @datatype_name: datatype name 153 * 154 * .. code-block:: c 155 * 156 * FIXTURE_DATA(datatype name) 157 * 158 * This call may be used when the type of the fixture data 159 * is needed. In general, this should not be needed unless 160 * the *self* is being passed to a helper directly. 161 */ 162 #define FIXTURE_DATA(datatype_name) struct _test_data_##datatype_name 163 164 /** 165 * FIXTURE(fixture_name) - Called once per fixture to setup the data and 166 * register 167 * 168 * @fixture_name: fixture name 169 * 170 * .. code-block:: c 171 * 172 * FIXTURE(datatype name) { 173 * type property1; 174 * ... 175 * }; 176 * 177 * Defines the data provided to TEST_F()-defined tests as *self*. It should be 178 * populated and cleaned up using FIXTURE_SETUP() and FIXTURE_TEARDOWN(). 179 */ 180 #define FIXTURE(fixture_name) \ 181 static void __attribute__((constructor)) \ 182 _register_##fixture_name##_data(void) \ 183 { \ 184 __fixture_count++; \ 185 } \ 186 FIXTURE_DATA(fixture_name) 187 188 /** 189 * FIXTURE_SETUP(fixture_name) - Prepares the setup function for the fixture. 190 * *_metadata* is included so that ASSERT_* work as a convenience 191 * 192 * @fixture_name: fixture name 193 * 194 * .. code-block:: c 195 * 196 * FIXTURE_SETUP(fixture name) { implementation } 197 * 198 * Populates the required "setup" function for a fixture. An instance of the 199 * datatype defined with FIXTURE_DATA() will be exposed as *self* for the 200 * implementation. 201 * 202 * ASSERT_* are valid for use in this context and will prempt the execution 203 * of any dependent fixture tests. 204 * 205 * A bare "return;" statement may be used to return early. 206 */ 207 #define FIXTURE_SETUP(fixture_name) \ 208 void fixture_name##_setup( \ 209 struct __test_metadata __attribute__((unused)) *_metadata, \ 210 FIXTURE_DATA(fixture_name) __attribute__((unused)) *self) 211 /** 212 * FIXTURE_TEARDOWN(fixture_name) 213 * 214 * @fixture_name: fixture name 215 * 216 * .. code-block:: c 217 * 218 * FIXTURE_TEARDOWN(fixture name) { implementation } 219 * 220 * Populates the required "teardown" function for a fixture. An instance of the 221 * datatype defined with FIXTURE_DATA() will be exposed as *self* for the 222 * implementation to clean up. 223 * 224 * A bare "return;" statement may be used to return early. 225 */ 226 #define FIXTURE_TEARDOWN(fixture_name) \ 227 void fixture_name##_teardown( \ 228 struct __test_metadata __attribute__((unused)) *_metadata, \ 229 FIXTURE_DATA(fixture_name) __attribute__((unused)) *self) 230 231 /** 232 * TEST_F(fixture_name, test_name) - Emits test registration and helpers for 233 * fixture-based test cases 234 * 235 * @fixture_name: fixture name 236 * @test_name: test name 237 * 238 * .. code-block:: c 239 * 240 * TEST_F(fixture, name) { implementation } 241 * 242 * Defines a test that depends on a fixture (e.g., is part of a test case). 243 * Very similar to TEST() except that *self* is the setup instance of fixture's 244 * datatype exposed for use by the implementation. 245 */ 246 /* TODO(wad) register fixtures on dedicated test lists. */ 247 #define TEST_F(fixture_name, test_name) \ 248 __TEST_F_IMPL(fixture_name, test_name, -1) 249 250 #define TEST_F_SIGNAL(fixture_name, test_name, signal) \ 251 __TEST_F_IMPL(fixture_name, test_name, signal) 252 253 #define __TEST_F_IMPL(fixture_name, test_name, signal) \ 254 static void fixture_name##_##test_name( \ 255 struct __test_metadata *_metadata, \ 256 FIXTURE_DATA(fixture_name) *self); \ 257 static inline void wrapper_##fixture_name##_##test_name( \ 258 struct __test_metadata *_metadata) \ 259 { \ 260 /* fixture data is alloced, setup, and torn down per call. */ \ 261 FIXTURE_DATA(fixture_name) self; \ 262 memset(&self, 0, sizeof(FIXTURE_DATA(fixture_name))); \ 263 fixture_name##_setup(_metadata, &self); \ 264 /* Let setup failure terminate early. */ \ 265 if (!_metadata->passed) \ 266 return; \ 267 fixture_name##_##test_name(_metadata, &self); \ 268 fixture_name##_teardown(_metadata, &self); \ 269 } \ 270 static struct __test_metadata \ 271 _##fixture_name##_##test_name##_object = { \ 272 name: #fixture_name "." #test_name, \ 273 fn: &wrapper_##fixture_name##_##test_name, \ 274 termsig: signal, \ 275 }; \ 276 static void __attribute__((constructor)) \ 277 _register_##fixture_name##_##test_name(void) \ 278 { \ 279 __register_test(&_##fixture_name##_##test_name##_object); \ 280 } \ 281 static void fixture_name##_##test_name( \ 282 struct __test_metadata __attribute__((unused)) *_metadata, \ 283 FIXTURE_DATA(fixture_name) __attribute__((unused)) *self) 284 285 /** 286 * TEST_HARNESS_MAIN - Simple wrapper to run the test harness 287 * 288 * .. code-block:: c 289 * 290 * TEST_HARNESS_MAIN 291 * 292 * Use once to append a main() to the test file. 293 */ 294 #define TEST_HARNESS_MAIN \ 295 static void __attribute__((constructor)) \ 296 __constructor_order_last(void) \ 297 { \ 298 if (!__constructor_order) \ 299 __constructor_order = _CONSTRUCTOR_ORDER_BACKWARD; \ 300 } \ 301 int main(int argc, char **argv) { \ 302 return test_harness_run(argc, argv); \ 303 } 304 305 /** 306 * DOC: operators 307 * 308 * Operators for use in TEST() and TEST_F(). 309 * ASSERT_* calls will stop test execution immediately. 310 * EXPECT_* calls will emit a failure warning, note it, and continue. 311 */ 312 313 /** 314 * ASSERT_EQ(expected, seen) 315 * 316 * @expected: expected value 317 * @seen: measured value 318 * 319 * ASSERT_EQ(expected, measured): expected == measured 320 */ 321 #define ASSERT_EQ(expected, seen) \ 322 __EXPECT(expected, seen, ==, 1) 323 324 /** 325 * ASSERT_NE(expected, seen) 326 * 327 * @expected: expected value 328 * @seen: measured value 329 * 330 * ASSERT_NE(expected, measured): expected != measured 331 */ 332 #define ASSERT_NE(expected, seen) \ 333 __EXPECT(expected, seen, !=, 1) 334 335 /** 336 * ASSERT_LT(expected, seen) 337 * 338 * @expected: expected value 339 * @seen: measured value 340 * 341 * ASSERT_LT(expected, measured): expected < measured 342 */ 343 #define ASSERT_LT(expected, seen) \ 344 __EXPECT(expected, seen, <, 1) 345 346 /** 347 * ASSERT_LE(expected, seen) 348 * 349 * @expected: expected value 350 * @seen: measured value 351 * 352 * ASSERT_LE(expected, measured): expected <= measured 353 */ 354 #define ASSERT_LE(expected, seen) \ 355 __EXPECT(expected, seen, <=, 1) 356 357 /** 358 * ASSERT_GT(expected, seen) 359 * 360 * @expected: expected value 361 * @seen: measured value 362 * 363 * ASSERT_GT(expected, measured): expected > measured 364 */ 365 #define ASSERT_GT(expected, seen) \ 366 __EXPECT(expected, seen, >, 1) 367 368 /** 369 * ASSERT_GE(expected, seen) 370 * 371 * @expected: expected value 372 * @seen: measured value 373 * 374 * ASSERT_GE(expected, measured): expected >= measured 375 */ 376 #define ASSERT_GE(expected, seen) \ 377 __EXPECT(expected, seen, >=, 1) 378 379 /** 380 * ASSERT_NULL(seen) 381 * 382 * @seen: measured value 383 * 384 * ASSERT_NULL(measured): NULL == measured 385 */ 386 #define ASSERT_NULL(seen) \ 387 __EXPECT(NULL, seen, ==, 1) 388 389 /** 390 * ASSERT_TRUE(seen) 391 * 392 * @seen: measured value 393 * 394 * ASSERT_TRUE(measured): measured != 0 395 */ 396 #define ASSERT_TRUE(seen) \ 397 ASSERT_NE(0, seen) 398 399 /** 400 * ASSERT_FALSE(seen) 401 * 402 * @seen: measured value 403 * 404 * ASSERT_FALSE(measured): measured == 0 405 */ 406 #define ASSERT_FALSE(seen) \ 407 ASSERT_EQ(0, seen) 408 409 /** 410 * ASSERT_STREQ(expected, seen) 411 * 412 * @expected: expected value 413 * @seen: measured value 414 * 415 * ASSERT_STREQ(expected, measured): !strcmp(expected, measured) 416 */ 417 #define ASSERT_STREQ(expected, seen) \ 418 __EXPECT_STR(expected, seen, ==, 1) 419 420 /** 421 * ASSERT_STRNE(expected, seen) 422 * 423 * @expected: expected value 424 * @seen: measured value 425 * 426 * ASSERT_STRNE(expected, measured): strcmp(expected, measured) 427 */ 428 #define ASSERT_STRNE(expected, seen) \ 429 __EXPECT_STR(expected, seen, !=, 1) 430 431 /** 432 * EXPECT_EQ(expected, seen) 433 * 434 * @expected: expected value 435 * @seen: measured value 436 * 437 * EXPECT_EQ(expected, measured): expected == measured 438 */ 439 #define EXPECT_EQ(expected, seen) \ 440 __EXPECT(expected, seen, ==, 0) 441 442 /** 443 * EXPECT_NE(expected, seen) 444 * 445 * @expected: expected value 446 * @seen: measured value 447 * 448 * EXPECT_NE(expected, measured): expected != measured 449 */ 450 #define EXPECT_NE(expected, seen) \ 451 __EXPECT(expected, seen, !=, 0) 452 453 /** 454 * EXPECT_LT(expected, seen) 455 * 456 * @expected: expected value 457 * @seen: measured value 458 * 459 * EXPECT_LT(expected, measured): expected < measured 460 */ 461 #define EXPECT_LT(expected, seen) \ 462 __EXPECT(expected, seen, <, 0) 463 464 /** 465 * EXPECT_LE(expected, seen) 466 * 467 * @expected: expected value 468 * @seen: measured value 469 * 470 * EXPECT_LE(expected, measured): expected <= measured 471 */ 472 #define EXPECT_LE(expected, seen) \ 473 __EXPECT(expected, seen, <=, 0) 474 475 /** 476 * EXPECT_GT(expected, seen) 477 * 478 * @expected: expected value 479 * @seen: measured value 480 * 481 * EXPECT_GT(expected, measured): expected > measured 482 */ 483 #define EXPECT_GT(expected, seen) \ 484 __EXPECT(expected, seen, >, 0) 485 486 /** 487 * EXPECT_GE(expected, seen) 488 * 489 * @expected: expected value 490 * @seen: measured value 491 * 492 * EXPECT_GE(expected, measured): expected >= measured 493 */ 494 #define EXPECT_GE(expected, seen) \ 495 __EXPECT(expected, seen, >=, 0) 496 497 /** 498 * EXPECT_NULL(seen) 499 * 500 * @seen: measured value 501 * 502 * EXPECT_NULL(measured): NULL == measured 503 */ 504 #define EXPECT_NULL(seen) \ 505 __EXPECT(NULL, seen, ==, 0) 506 507 /** 508 * EXPECT_TRUE(seen) 509 * 510 * @seen: measured value 511 * 512 * EXPECT_TRUE(measured): 0 != measured 513 */ 514 #define EXPECT_TRUE(seen) \ 515 EXPECT_NE(0, seen) 516 517 /** 518 * EXPECT_FALSE(seen) 519 * 520 * @seen: measured value 521 * 522 * EXPECT_FALSE(measured): 0 == measured 523 */ 524 #define EXPECT_FALSE(seen) \ 525 EXPECT_EQ(0, seen) 526 527 /** 528 * EXPECT_STREQ(expected, seen) 529 * 530 * @expected: expected value 531 * @seen: measured value 532 * 533 * EXPECT_STREQ(expected, measured): !strcmp(expected, measured) 534 */ 535 #define EXPECT_STREQ(expected, seen) \ 536 __EXPECT_STR(expected, seen, ==, 0) 537 538 /** 539 * EXPECT_STRNE(expected, seen) 540 * 541 * @expected: expected value 542 * @seen: measured value 543 * 544 * EXPECT_STRNE(expected, measured): strcmp(expected, measured) 545 */ 546 #define EXPECT_STRNE(expected, seen) \ 547 __EXPECT_STR(expected, seen, !=, 0) 548 549 #define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0])) 550 551 /* Support an optional handler after and ASSERT_* or EXPECT_*. The approach is 552 * not thread-safe, but it should be fine in most sane test scenarios. 553 * 554 * Using __bail(), which optionally abort()s, is the easiest way to early 555 * return while still providing an optional block to the API consumer. 556 */ 557 #define OPTIONAL_HANDLER(_assert) \ 558 for (; _metadata->trigger; _metadata->trigger = __bail(_assert)) 559 560 #define __EXPECT(_expected, _seen, _t, _assert) do { \ 561 /* Avoid multiple evaluation of the cases */ \ 562 __typeof__(_expected) __exp = (_expected); \ 563 __typeof__(_seen) __seen = (_seen); \ 564 if (!(__exp _t __seen)) { \ 565 unsigned long long __exp_print = (uintptr_t)__exp; \ 566 unsigned long long __seen_print = (uintptr_t)__seen; \ 567 __TH_LOG("Expected %s (%llu) %s %s (%llu)", \ 568 #_expected, __exp_print, #_t, \ 569 #_seen, __seen_print); \ 570 _metadata->passed = 0; \ 571 /* Ensure the optional handler is triggered */ \ 572 _metadata->trigger = 1; \ 573 } \ 574 } while (0); OPTIONAL_HANDLER(_assert) 575 576 #define __EXPECT_STR(_expected, _seen, _t, _assert) do { \ 577 const char *__exp = (_expected); \ 578 const char *__seen = (_seen); \ 579 if (!(strcmp(__exp, __seen) _t 0)) { \ 580 __TH_LOG("Expected '%s' %s '%s'.", __exp, #_t, __seen); \ 581 _metadata->passed = 0; \ 582 _metadata->trigger = 1; \ 583 } \ 584 } while (0); OPTIONAL_HANDLER(_assert) 585 586 /* Contains all the information for test execution and status checking. */ 587 struct __test_metadata { 588 const char *name; 589 void (*fn)(struct __test_metadata *); 590 int termsig; 591 int passed; 592 int trigger; /* extra handler after the evaluation */ 593 struct __test_metadata *prev, *next; 594 }; 595 596 /* Storage for the (global) tests to be run. */ 597 static struct __test_metadata *__test_list; 598 static unsigned int __test_count; 599 static unsigned int __fixture_count; 600 static int __constructor_order; 601 602 #define _CONSTRUCTOR_ORDER_FORWARD 1 603 #define _CONSTRUCTOR_ORDER_BACKWARD -1 604 605 /* 606 * Since constructors are called in reverse order, reverse the test 607 * list so tests are run in source declaration order. 608 * https://gcc.gnu.org/onlinedocs/gccint/Initialization.html 609 * However, it seems not all toolchains do this correctly, so use 610 * __constructor_order to detect which direction is called first 611 * and adjust list building logic to get things running in the right 612 * direction. 613 */ 614 static inline void __register_test(struct __test_metadata *t) 615 { 616 __test_count++; 617 /* Circular linked list where only prev is circular. */ 618 if (__test_list == NULL) { 619 __test_list = t; 620 t->next = NULL; 621 t->prev = t; 622 return; 623 } 624 if (__constructor_order == _CONSTRUCTOR_ORDER_FORWARD) { 625 t->next = NULL; 626 t->prev = __test_list->prev; 627 t->prev->next = t; 628 __test_list->prev = t; 629 } else { 630 t->next = __test_list; 631 t->next->prev = t; 632 t->prev = t; 633 __test_list = t; 634 } 635 } 636 637 static inline int __bail(int for_realz) 638 { 639 if (for_realz) 640 abort(); 641 return 0; 642 } 643 644 void __run_test(struct __test_metadata *t) 645 { 646 pid_t child_pid; 647 int status; 648 649 t->passed = 1; 650 t->trigger = 0; 651 printf("[ RUN ] %s\n", t->name); 652 child_pid = fork(); 653 if (child_pid < 0) { 654 printf("ERROR SPAWNING TEST CHILD\n"); 655 t->passed = 0; 656 } else if (child_pid == 0) { 657 t->fn(t); 658 _exit(t->passed); 659 } else { 660 /* TODO(wad) add timeout support. */ 661 waitpid(child_pid, &status, 0); 662 if (WIFEXITED(status)) { 663 t->passed = t->termsig == -1 ? WEXITSTATUS(status) : 0; 664 if (t->termsig != -1) { 665 fprintf(TH_LOG_STREAM, 666 "%s: Test exited normally " 667 "instead of by signal (code: %d)\n", 668 t->name, 669 WEXITSTATUS(status)); 670 } 671 } else if (WIFSIGNALED(status)) { 672 t->passed = 0; 673 if (WTERMSIG(status) == SIGABRT) { 674 fprintf(TH_LOG_STREAM, 675 "%s: Test terminated by assertion\n", 676 t->name); 677 } else if (WTERMSIG(status) == t->termsig) { 678 t->passed = 1; 679 } else { 680 fprintf(TH_LOG_STREAM, 681 "%s: Test terminated unexpectedly " 682 "by signal %d\n", 683 t->name, 684 WTERMSIG(status)); 685 } 686 } else { 687 fprintf(TH_LOG_STREAM, 688 "%s: Test ended in some other way [%u]\n", 689 t->name, 690 status); 691 } 692 } 693 printf("[ %4s ] %s\n", (t->passed ? "OK" : "FAIL"), t->name); 694 } 695 696 static int test_harness_run(int __attribute__((unused)) argc, 697 char __attribute__((unused)) **argv) 698 { 699 struct __test_metadata *t; 700 int ret = 0; 701 unsigned int count = 0; 702 unsigned int pass_count = 0; 703 704 /* TODO(wad) add optional arguments similar to gtest. */ 705 printf("[==========] Running %u tests from %u test cases.\n", 706 __test_count, __fixture_count + 1); 707 for (t = __test_list; t; t = t->next) { 708 count++; 709 __run_test(t); 710 if (t->passed) 711 pass_count++; 712 else 713 ret = 1; 714 } 715 printf("[==========] %u / %u tests passed.\n", pass_count, count); 716 printf("[ %s ]\n", (ret ? "FAILED" : "PASSED")); 717 return ret; 718 } 719 720 static void __attribute__((constructor)) __constructor_order_first(void) 721 { 722 if (!__constructor_order) 723 __constructor_order = _CONSTRUCTOR_ORDER_FORWARD; 724 } 725 726 #endif /* __KSELFTEST_HARNESS_H */ 727