1 /*-*- mode:C; -*- */ 2 /* 3 * Check: a unit test framework for C 4 * Copyright (C) 2001, 2002 Arien Malec 5 * 6 * This library is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Lesser General Public 8 * License as published by the Free Software Foundation; either 9 * version 2.1 of the License, or (at your option) any later version. 10 * 11 * This library is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * Lesser General Public License for more details. 15 * 16 * You should have received a copy of the GNU Lesser General Public 17 * License along with this library; if not, write to the 18 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, 19 * MA 02110-1301, USA. 20 */ 21 22 #ifndef CHECK_H 23 #define CHECK_H 24 25 #include <stddef.h> 26 #include <string.h> 27 28 /* 29 Macros and functions starting with _ (underscore) are internal and 30 may change without notice. You have been warned!. 31 */ 32 33 34 #ifdef __cplusplus 35 #define CK_CPPSTART extern "C" { 36 #define CK_CPPEND } 37 CK_CPPSTART 38 #endif 39 #if defined(__GNUC__) && defined(__GNUC_MINOR__) 40 #define GCC_VERSION_AT_LEAST(major, minor) \ 41 ((__GNUC__ > (major)) || \ 42 (__GNUC__ == (major) && __GNUC_MINOR__ >= (minor))) 43 #else 44 #define GCC_VERSION_AT_LEAST(major, minor) 0 45 #endif 46 #if GCC_VERSION_AT_LEAST(2,95) 47 #define CK_ATTRIBUTE_UNUSED __attribute__ ((unused)) 48 #else 49 #define CK_ATTRIBUTE_UNUSED 50 #endif /* GCC 2.95 */ 51 #if GCC_VERSION_AT_LEAST(2,5) 52 #define CK_ATTRIBUTE_NORETURN __attribute__ ((noreturn)) 53 #else 54 #define CK_ATTRIBUTE_NORETURN 55 #endif /* GCC 2.5 */ 56 #include <sys/types.h> 57 58 /* 59 * Used to create the linker script for hiding lib-local symbols. Shall 60 * be put directly in front of the exported symbol. 61 */ 62 #define CK_EXPORT 63 64 /* 65 * Used for MSVC to create the export attribute 66 * CK_DLL_EXP is defined during the compilation of the library 67 * on the command line. 68 */ 69 #ifndef CK_DLL_EXP 70 # if defined(_MSC_VER) 71 # define CK_DLL_EXP __declspec(dllimport) 72 # else 73 # define CK_DLL_EXP extern 74 # endif 75 #endif 76 77 /* check version numbers */ 78 #define CHECK_MAJOR_VERSION (0) 79 #define CHECK_MINOR_VERSION (9) 80 #define CHECK_MICRO_VERSION (14) 81 CK_DLL_EXP /*extern*/ int CK_EXPORT check_major_version; 82 CK_DLL_EXP /*extern*/ int CK_EXPORT check_minor_version; 83 CK_DLL_EXP /*extern*/ int CK_EXPORT check_micro_version; 84 85 #ifndef NULL 86 #define NULL ((void*)0) 87 #endif 88 89 #if defined(_MSC_VER) 90 #define pid_t int 91 #endif 92 93 /** 94 * Type for a test case 95 * 96 * A TCase represents a test case. Create with tcase_create, free 97 * with tcase_free. For the moment, test cases can only be run 98 * through a suite 99 */ 100 typedef struct TCase TCase; 101 102 /** 103 * Type for a test function 104 */ 105 typedef void (*TFun) (int); 106 107 /** 108 * Type for a setup/teardown function 109 */ 110 typedef void (*SFun) (void); 111 112 /** 113 * Type for a test suite 114 */ 115 typedef struct Suite Suite; 116 117 /** 118 * Creates a test suite with the given name. 119 * 120 * Create a suite, which will contain test cases. Once 121 * created, use suite_add_tcase() to add test cases. 122 * When finished, create a suite runner from the 123 * suite using srunner_create() 124 * 125 * @param name name of the suite 126 * 127 * @return suite 128 * 129 * @since 0.6.0 130 */ 131 CK_DLL_EXP Suite *CK_EXPORT suite_create (const char *name); 132 133 /** 134 * Determines whether a given test suite contains a case named after a 135 * given string. 136 * 137 * @param s suite to check 138 * @param tcname test case to look for 139 * 140 * @return 1 iff the given test case is within the given suite; 141 * 0 otherwise 142 * 143 * @since 0.9.9 144 */ 145 CK_DLL_EXP int CK_EXPORT suite_tcase (Suite * s, const char *tcname); 146 147 /** 148 * Add a test case to a suite. 149 * 150 * Note that if the TCase has already been added attempting 151 * to add it again will be ignored. 152 * 153 * @param s suite to add test case to 154 * @param tc test case to add to suite 155 * 156 * @since 0.6.0 157 */ 158 CK_DLL_EXP void CK_EXPORT suite_add_tcase (Suite * s, TCase * tc); 159 160 /** 161 * Create a test case. 162 * 163 * Once created, tests can be added with the tcase_add_test() 164 * function, and the test case assigned to a suite with the 165 * suite_add_tcase() function. 166 * 167 * @param name name of the test case 168 * 169 * @return test case containing no tests 170 * 171 * @since 0.6.0 172 * */ 173 CK_DLL_EXP TCase *CK_EXPORT tcase_create (const char *name); 174 175 /** 176 * Associate a test case with certain tags. 177 * Replaces any existing tags with the new set. 178 * 179 * @param tc the test case 180 * 181 * @param tags string containing arbitrary tags separated by spaces. 182 * This will be copied. Passing NULL clears all tags. 183 * 184 * @since 0.11.0 185 * */ 186 CK_DLL_EXP void CK_EXPORT tcase_set_tags (TCase * tc, const char *tags); 187 /** 188 * Add a test function to a test case 189 * 190 * @param tc test case to add test to 191 * @param tf test function to add to test case 192 * 193 * @since 0.6.0 194 * */ 195 #define tcase_add_test(tc,tf) tcase_add_test_raise_signal(tc,tf,0) 196 197 /** 198 * Add a test function with signal handling to a test case 199 * 200 * The added test is expected to terminate by throwing the given signal 201 * 202 * @param tc test case to add test to 203 * @param tf test function to add to test case 204 * @param signal expected signal for test function to throw in order for 205 * the test to be considered passing 206 * 207 * @since 0.9.2 208 * */ 209 #define tcase_add_test_raise_signal(tc,tf,signal) \ 210 _tcase_add_test((tc),(tf),"" # tf "",(signal), 0, 0, 1) 211 212 /** 213 * Add a test function with an expected exit value to a test case 214 * 215 * The added test is expected to terminate by exiting with the given value 216 * 217 * @param tc test case to add test to 218 * @param tf test function to add to test case 219 * @param expected_exit_value exit value for test function to return in 220 * order for the test to be considered passing 221 * 222 * @since 0.9.7 223 */ 224 #define tcase_add_exit_test(tc, tf, expected_exit_value) \ 225 _tcase_add_test((tc),(tf),"" # tf "",0,(expected_exit_value),0,1) 226 227 /** 228 * Add a looping test function to a test case 229 * 230 * The test will be called in a for(i = s; i < e; i++) loop with each 231 * iteration being executed in a new context. The loop variable 'i' is 232 * available in the test. 233 * 234 * @param tc test case to add test to 235 * @param tf function to add to test case 236 * @param s starting index for value "i" in test 237 * @param e ending index for value "i" in test 238 * 239 * @since 0.9.4 240 */ 241 #define tcase_add_loop_test(tc,tf,s,e) \ 242 _tcase_add_test((tc),(tf),"" # tf "",0,0,(s),(e)) 243 244 /** 245 * Add a looping test function with signal handling to a test case 246 * 247 * The test will be called in a for(i = s; i < e; i++) loop with each 248 * iteration being executed in a new context. The loop variable 'i' is 249 * available in the test. 250 * 251 * The added test is expected to terminate by throwing the given signal 252 * 253 * @param tc test case to add test to 254 * @param tf function to add to test case 255 * @param signal expected signal for test function to throw in order for 256 * the test to be considered passing 257 * @param s starting index for value "i" in test 258 * @param e ending index for value "i" in test 259 * 260 * @since 0.9.5 261 */ 262 #define tcase_add_loop_test_raise_signal(tc,tf,signal,s,e) \ 263 _tcase_add_test((tc),(tf),"" # tf "",(signal),0,(s),(e)) 264 265 /** 266 * Add a looping test function with an expected exit value to a test case 267 * 268 * The test will be called in a for(i = s; i < e; i++) loop with each 269 * iteration being executed in a new context. The loop variable 'i' is 270 * available in the test. 271 * 272 * The added test is expected to terminate by exiting with the given value 273 * 274 * @param tc test case to add test to 275 * @param tf function to add to test case 276 * @param expected_exit_value exit value for test function to return in 277 * order for the test to be considered passing 278 * @param s starting index for value "i" in test 279 * @param e ending index for value "i" in test 280 * 281 * @since 0.9.7 282 */ 283 #define tcase_add_loop_exit_test(tc,tf,expected_exit_value,s,e) \ 284 _tcase_add_test((tc),(tf),"" # tf "",0,(expected_exit_value),(s),(e)) 285 286 /* Add a test function to a test case 287 (function version -- use this when the macro won't work 288 */ 289 CK_DLL_EXP void CK_EXPORT _tcase_add_test (TCase * tc, TFun tf, 290 const char *fname, int _signal, int allowed_exit_value, int start, int end); 291 292 /** 293 * Add unchecked fixture setup/teardown functions to a test case 294 * 295 * Unchecked fixture functions are run at the start and end of the 296 * test case, and not before and after unit tests. Further, 297 * unchecked fixture functions are not run in a separate address space, 298 * like test functions, and so must not exit or signal (e.g., 299 * segfault). 300 * 301 * Also, when run in CK_NOFORK mode, unchecked fixture functions may 302 * lead to different unit test behavior if unit tests change data 303 * setup by the fixture functions. 304 * 305 * Note that if a setup function fails, the remaining setup functions 306 * will be omitted, as will the test case and the teardown functions. 307 * If a teardown function fails the remaining teardown functions will be 308 * omitted. 309 * 310 * @param tc test case to add unchecked fixture setup/teardown to 311 * @param setup function to add to be executed before the test case; 312 * if NULL no setup function is added 313 * @param teardown function to add to be executed after the test case; 314 * if NULL no teardown function is added 315 * @since 0.8.0 316 */ 317 CK_DLL_EXP void CK_EXPORT tcase_add_unchecked_fixture (TCase * tc, SFun setup, 318 SFun teardown); 319 320 /** 321 * Add checked fixture setup/teardown functions to a test case 322 * 323 * Checked fixture functions are run before and after each unit test inside 324 * of the address space of the test. Thus, if using CK_FORK 325 * mode the separate process running the unit test will survive signals 326 * or unexpected exits in the fixture function. Also, if the setup 327 * function is idempotent, unit test behavior will be the same in 328 * CK_FORK and CK_NOFORK modes. 329 * 330 * However, since fixture functions are run before and after each unit 331 * test, they should not be expensive code. 332 * 333 * Note that if a setup function fails, the remaining setup functions 334 * will be omitted, as will the test and the teardown functions. If a 335 * teardown function fails the remaining teardown functions will be 336 * omitted. 337 * 338 * @param tc test case to add checked fixture setup/teardown to 339 * @param setup function to add to be executed before each unit test in 340 * the test case; if NULL no setup function is added 341 * @param teardown function to add to be executed after each unit test in 342 * the test case; if NULL no teardown function is added 343 * 344 * @since 0.8.0 345 */ 346 CK_DLL_EXP void CK_EXPORT tcase_add_checked_fixture (TCase * tc, SFun setup, 347 SFun teardown); 348 349 /** 350 * Set the timeout for all tests in a test case. 351 * 352 * A test that lasts longer than the timeout (in seconds) will be killed 353 * and thus fail with an error. 354 * 355 * If not set, the default timeout is one assigned at compile time. If 356 * the environment variable CK_DEFAULT_TIMEOUT is defined and no timeout 357 * is set, the value in the environment variable is used. 358 * 359 * If Check is compile without fork() support this call is ignored, 360 * as timeouts are not possible. 361 * 362 * @param tc test case to assign timeout to 363 * @param timeout to use, in seconds. If the value contains a decimal 364 * portion, but no high resolution timer is available, 365 * the value is rounded up to the nearest second. 366 * 367 * @since 0.9.2 368 */ 369 CK_DLL_EXP void CK_EXPORT tcase_set_timeout (TCase * tc, double timeout); 370 371 /* Internal function to mark the start of a test function */ 372 CK_DLL_EXP void CK_EXPORT tcase_fn_start (const char *fname, const char *file, 373 int line); 374 375 /** 376 * Start a unit test with START_TEST(unit_name), end with END_TEST. 377 * 378 * One must use braces within a START_/END_ pair to declare new variables 379 * 380 * @since 0.6.0 381 */ 382 #define START_TEST(__testname)\ 383 static void __testname (int _i CK_ATTRIBUTE_UNUSED)\ 384 {\ 385 tcase_fn_start (""# __testname, __FILE__, __LINE__); 386 387 /** 388 * End a unit test 389 * 390 * @since 0.6.0 391 */ 392 #define END_TEST } 393 394 /* 395 * Fail the test case unless expr is false 396 * 397 * This call is deprecated. 398 */ 399 #define fail_unless ck_assert_msg 400 401 /* 402 * Fail the test case if expr is false 403 * 404 * This call is deprecated. 405 * 406 * NOTE: The space before the comma sign before ## is essential to be compatible 407 * with gcc 2.95.3 and earlier. 408 * FIXME: these macros may conflict with C89 if expr is 409 * FIXME: strcmp (str1, str2) due to excessive string length. 410 */ 411 #define fail_if(expr, ...)\ 412 (expr) ? \ 413 _ck_assert_failed(__FILE__, __LINE__, "Failure '"#expr"' occurred" , ## __VA_ARGS__, NULL) \ 414 : _mark_point(__FILE__, __LINE__) 415 416 /* 417 * Fail the test 418 * 419 * This call is deprecated. 420 */ 421 #define fail ck_abort_msg 422 423 /* 424 * This is called whenever an assertion fails. 425 */ 426 CK_DLL_EXP void CK_EXPORT 427 _ck_assert_failed (const char *file, int line, const char *expr, ...) 428 CK_ATTRIBUTE_NORETURN; 429 430 /** 431 * Fail the test if expression is false 432 * 433 * @param expr expression to evaluate 434 * 435 * @note If the check fails, the remaining of the test is aborted 436 * 437 * @since 0.9.6 438 */ 439 #define ck_assert(expr) ck_assert_msg(expr, NULL) 440 441 /* The space before the comma sign before ## is essential to be compatible 442 with gcc 2.95.3 and earlier. 443 */ 444 /** 445 * Fail the test if the expression is false; print message on failure 446 * 447 * @param expr expression to evaluate 448 * @param ... message to print (in printf format) if expression is false 449 * 450 * @note If the check fails, the remaining of the test is aborted 451 * 452 * @since 0.9.6 453 */ 454 #define ck_assert_msg(expr, ...) \ 455 (expr) ? \ 456 _mark_point(__FILE__, __LINE__) : \ 457 _ck_assert_failed(__FILE__, __LINE__, "Assertion '"#expr"' failed" , ## __VA_ARGS__, NULL) 458 459 /** 460 * Unconditionally fail the test 461 * 462 * @note Once called, the remaining of the test is aborted 463 * 464 * @since 0.9.6 465 */ 466 #define ck_abort() ck_abort_msg(NULL) 467 /** 468 * Unconditionally fail the test; print a message 469 * 470 * @param ... message to print (in printf format) 471 * 472 * @note Once called, the remaining of the test is aborted 473 * 474 * @since 0.9.6 475 */ 476 #define ck_abort_msg(...) _ck_assert_failed(__FILE__, __LINE__, "Failed" , ## __VA_ARGS__, NULL) 477 478 /* Signed and unsigned integer comparison macros with improved output compared to ck_assert(). */ 479 /* OP may be any comparison operator. */ 480 #define _ck_assert_int(X, OP, Y) do { \ 481 gint64 _ck_x = (X); \ 482 gint64 _ck_y = (Y); \ 483 ck_assert_msg(_ck_x OP _ck_y, "Assertion '%s' failed: " \ 484 "%s==%" G_GINT64_FORMAT ", %s==%" G_GINT64_FORMAT, #X#OP#Y, #X, _ck_x, #Y, _ck_y); \ 485 } while (0) 486 487 /** 488 * Check two signed integers to determine if X==Y 489 * 490 * If not X==Y, the test fails. 491 * 492 * @param X signed integer 493 * @param Y signed integer to compare against X 494 * 495 * @note If the check fails, the remaining of the test is aborted 496 * 497 * @since 0.9.6 498 */ 499 #define ck_assert_int_eq(X, Y) _ck_assert_int(X, ==, Y) 500 /** 501 * Check two signed integers to determine if X!=Y 502 * 503 * If not X!=Y, the test fails. 504 * 505 * @param X signed integer 506 * @param Y signed integer to compare against X 507 * 508 * @note If the check fails, the remaining of the test is aborted 509 * 510 * @since 0.9.6 511 */ 512 #define ck_assert_int_ne(X, Y) _ck_assert_int(X, !=, Y) 513 /** 514 * Check two signed integers to determine if X<Y 515 * 516 * If not X<Y, the test fails. 517 * 518 * @param X signed integer 519 * @param Y signed integer to compare against X 520 * 521 * @note If the check fails, the remaining of the test is aborted 522 * 523 * @since 0.9.10 524 */ 525 #define ck_assert_int_lt(X, Y) _ck_assert_int(X, <, Y) 526 /** 527 * Check two signed integers to determine if X<=Y 528 * 529 * If not X<=Y, the test fails. 530 * 531 * @param X signed integer 532 * @param Y signed integer to compare against X 533 * 534 * @note If the check fails, the remaining of the test is aborted 535 * 536 * @since 0.9.10 537 */ 538 #define ck_assert_int_le(X, Y) _ck_assert_int(X, <=, Y) 539 /** 540 * Check two signed integers to determine if X>Y 541 * 542 * If not X>Y, the test fails. 543 * 544 * @param X signed integer 545 * @param Y signed integer to compare against X 546 * 547 * @note If the check fails, the remaining of the test is aborted 548 * 549 * @since 0.9.10 550 */ 551 #define ck_assert_int_gt(X, Y) _ck_assert_int(X, >, Y) 552 /** 553 * Check two signed integers to determine if X>=Y 554 * 555 * If not X>=Y, the test fails. 556 * 557 * @param X signed integer 558 * @param Y signed integer to compare against X 559 * 560 * @note If the check fails, the remaining of the test is aborted 561 * 562 * @since 0.9.10 563 */ 564 #define ck_assert_int_ge(X, Y) _ck_assert_int(X, >=, Y) 565 566 #define _ck_assert_uint(X, OP, Y) do { \ 567 guint64 _ck_x = (X); \ 568 guint64 _ck_y = (Y); \ 569 ck_assert_msg(_ck_x OP _ck_y, "Assertion '%s' failed: " \ 570 "%s==%" G_GUINT64_FORMAT ", %s==%" G_GUINT64_FORMAT, #X#OP#Y, #X, _ck_x, #Y, _ck_y); \ 571 } while (0) 572 /** 573 * Check two unsigned integers to determine if X==Y 574 * 575 * If not X==Y, the test fails. 576 * 577 * @param X signed integer 578 * @param Y signed integer to compare against X 579 * 580 * @note If the check fails, the remaining of the test is aborted 581 * 582 * @since 0.9.10 583 */ 584 #define ck_assert_uint_eq(X, Y) _ck_assert_uint(X, ==, Y) 585 /** 586 * Check two unsigned integers to determine if X!=Y 587 * 588 * If not X!=Y, the test fails. 589 * 590 * @param X signed integer 591 * @param Y signed integer to compare against X 592 * 593 * @note If the check fails, the remaining of the test is aborted 594 * 595 * @since 0.9.10 596 */ 597 #define ck_assert_uint_ne(X, Y) _ck_assert_uint(X, !=, Y) 598 /** 599 * Check two unsigned integers to determine if X<Y 600 * 601 * If not X<Y, the test fails. 602 * 603 * @param X signed integer 604 * @param Y signed integer to compare against X 605 * 606 * @note If the check fails, the remaining of the test is aborted 607 * 608 * @since 0.9.10 609 */ 610 #define ck_assert_uint_lt(X, Y) _ck_assert_uint(X, <, Y) 611 /** 612 * Check two unsigned integers to determine if X<=Y 613 * 614 * If not X<=Y, the test fails. 615 * 616 * @param X signed integer 617 * @param Y signed integer to compare against X 618 * 619 * @note If the check fails, the remaining of the test is aborted 620 * 621 * @since 0.9.10 622 */ 623 #define ck_assert_uint_le(X, Y) _ck_assert_uint(X, <=, Y) 624 /** 625 * Check two unsigned integers to determine if X>Y 626 * 627 * If not X>Y, the test fails. 628 * 629 * @param X signed integer 630 * @param Y signed integer to compare against X 631 * 632 * @note If the check fails, the remaining of the test is aborted 633 * 634 * @since 0.9.10 635 */ 636 #define ck_assert_uint_gt(X, Y) _ck_assert_uint(X, >, Y) 637 /** 638 * Check two unsigned integers to determine if X>=Y 639 * 640 * If not X>=Y, the test fails. 641 * 642 * @param X signed integer 643 * @param Y signed integer to compare against X 644 * 645 * @note If the check fails, the remaining of the test is aborted 646 * 647 * @since 0.9.10 648 */ 649 #define ck_assert_uint_ge(X, Y) _ck_assert_uint(X, >=, Y) 650 651 /* String comparison macros with improved output compared to ck_assert() */ 652 /* OP might be any operator that can be used in '0 OP strcmp(X,Y)' comparison */ 653 /* The x and y parameter swap in strcmp() is needed to handle >, >=, <, <= operators */ 654 #define _ck_assert_str(X, OP, Y) do { \ 655 const char* _ck_x = (X); \ 656 const char* _ck_y = (Y); \ 657 ck_assert_msg(0 OP strcmp(_ck_y, _ck_x), \ 658 "Assertion '%s' failed: %s==\"%s\", %s==\"%s\"", #X#OP#Y, #X, _ck_x, #Y, _ck_y); \ 659 } while (0) 660 /** 661 * Check two strings to determine if 0==strcmp(X,Y) 662 * 663 * If not 0==strcmp(X,Y), the test fails. 664 * 665 * @param X string 666 * @param Y string to compare against X 667 * 668 * @note If the check fails, the remaining of the test is aborted 669 * 670 * @since 0.9.6 671 */ 672 #define ck_assert_str_eq(X, Y) _ck_assert_str(X, ==, Y) 673 /** 674 * Check two strings to determine if 0!=strcmp(X,Y) 675 * 676 * If not 0!=strcmp(X,Y), the test fails. 677 * 678 * @param X string 679 * @param Y string to compare against X 680 * 681 * @note If the check fails, the remaining of the test is aborted 682 * 683 * @since 0.9.6 684 */ 685 #define ck_assert_str_ne(X, Y) _ck_assert_str(X, !=, Y) 686 /** 687 * Check two strings to determine if 0<strcmp(X,Y), (e.g. strcmp(X,Y)>0) 688 * 689 * If not 0<strcmp(X,Y), the test fails. 690 * 691 * @param X string 692 * @param Y string to compare against X 693 * 694 * @note If the check fails, the remaining of the test is aborted 695 * 696 * @since 0.9.10 697 */ 698 #define ck_assert_str_lt(X, Y) _ck_assert_str(X, <, Y) 699 /** 700 * Check two strings to determine if 0<=strcmp(X,Y) (e.g. strcmp(X,Y)>=0) 701 * 702 * If not 0<=strcmp(X,Y), the test fails. 703 * 704 * @param X string 705 * @param Y string to compare against X 706 * 707 * @note If the check fails, the remaining of the test is aborted 708 * 709 * @since 0.9.10 710 */ 711 #define ck_assert_str_le(X, Y) _ck_assert_str(X, <=, Y) 712 /** 713 * Check two strings to determine if 0<strcmp(X,Y) (e.g. strcmp(X,Y)>0) 714 * 715 * If not 0<strcmp(X,Y), the test fails. 716 * 717 * @param X string 718 * @param Y string to compare against X 719 * 720 * @note If the check fails, the remaining of the test is aborted 721 * 722 * @since 0.9.10 723 */ 724 #define ck_assert_str_gt(X, Y) _ck_assert_str(X, >, Y) 725 /** 726 * Check two strings to determine if 0>=strcmp(X,Y) (e.g. strcmp(X,Y)<=0) 727 * 728 * If not 0>=strcmp(X,Y), the test fails. 729 * 730 * @param X string 731 * @param Y string to compare against X 732 * 733 * @note If the check fails, the remaining of the test is aborted 734 * 735 * @since 0.9.10 736 */ 737 #define ck_assert_str_ge(X, Y) _ck_assert_str(X, >=, Y) 738 739 /* Pointer comparison macros with improved output compared to ck_assert(). */ 740 /* OP may only be == or != */ 741 #define _ck_assert_ptr(X, OP, Y) do { \ 742 const void* _ck_x = (X); \ 743 const void* _ck_y = (Y); \ 744 ck_assert_msg(_ck_x OP _ck_y, "Assertion '%s' failed: %s==%#x, %s==%#x", #X#OP#Y, #X, _ck_x, #Y, _ck_y); \ 745 } while (0) 746 747 /** 748 * Check if two pointers are equal. 749 * 750 * If the two passed pointers are not equal, the test 751 * fails. 752 * 753 * @param X pointer 754 * @param Y pointer to compare against X 755 * 756 * @note If the check fails, the remaining of the test is aborted 757 * 758 * @since 0.9.10 759 */ 760 #define ck_assert_ptr_eq(X, Y) _ck_assert_ptr(X, ==, Y) 761 762 /** 763 * Check if two pointers are not. 764 * 765 * If the two passed pointers are equal, the test fails. 766 * 767 * @param X pointer 768 * @param Y pointer to compare against X 769 * 770 * @since 0.9.10 771 */ 772 #define ck_assert_ptr_ne(X, Y) _ck_assert_ptr(X, !=, Y) 773 774 /** 775 * Mark the last point reached in a unit test. 776 * 777 * If the test throws a signal or exits, the location noted with the 778 * failure is the last location of a ck_assert*() or ck_abort() call. 779 * Use mark_point() to record intermediate locations (useful for tracking down 780 * crashes or exits). 781 * 782 * @since 0.6.0 783 */ 784 #define mark_point() _mark_point(__FILE__,__LINE__) 785 786 /* Non macro version of #mark_point */ 787 CK_DLL_EXP void CK_EXPORT _mark_point (const char *file, int line); 788 789 /** 790 * Enum describing the possible results of a test 791 */ 792 enum test_result 793 { 794 CK_TEST_RESULT_INVALID, /**< Default value; should not encounter this */ 795 CK_PASS, /**< Test passed */ 796 CK_FAILURE, /**< Test completed but failed */ 797 CK_ERROR /**< Test failed to complete 798 (unexpected signal or non-zero early exit) */ 799 }; 800 801 /** 802 * Enum specifying the verbosity of output a SRunner should produce 803 */ 804 enum print_output 805 { 806 CK_SILENT, /**< No output */ 807 CK_MINIMAL, /**< Only summary output */ 808 CK_NORMAL, /**< All failed tests */ 809 CK_VERBOSE, /**< All tests */ 810 CK_ENV, /**< Look at environment var CK_VERBOSITY 811 for what verbosity to use, which can be 812 either "silent", "minimal", "normal", 813 or "verbose". If the environment variable 814 is not set, then CK_NORMAL will be used.*/ 815 #if 0 816 CK_SUBUNIT, /**< Run as a subunit child process */ 817 #endif 818 CK_LAST /**< Not a valid option */ 819 }; 820 821 /** 822 * Holds state for a running of a test suite 823 */ 824 typedef struct SRunner SRunner; 825 826 /** 827 * Opaque type for a test failure 828 */ 829 typedef struct TestResult TestResult; 830 831 /** 832 * Enum representing the types of contexts for a test 833 */ 834 enum ck_result_ctx 835 { 836 CK_CTX_INVALID, /**< Default value; should not encounter this */ 837 CK_CTX_SETUP, /**< Setup before a test */ 838 CK_CTX_TEST, /**< Body of test itself */ 839 CK_CTX_TEARDOWN /**< Teardown after a test */ 840 }; 841 842 /** 843 * Retrieve type of result that the given test result represents. 844 * 845 * This is a member of test_result, and can represent a 846 * pass, failure, or error. 847 * 848 * @param tr test result to retrieve result from 849 * 850 * @return result of given test 851 * 852 * @since 0.6.0 853 */ 854 CK_DLL_EXP int CK_EXPORT tr_rtype (TestResult * tr); 855 856 /** 857 * Retrieve context in which the result occurred for the given test result. 858 * 859 * The types of contents include the test setup, teardown, or the 860 * body of the test itself. 861 * 862 * @param tr test result to retrieve context from 863 * 864 * @return context to which the given test result applies 865 * 866 * @since 0.8.0 867 */ 868 CK_DLL_EXP enum ck_result_ctx CK_EXPORT tr_ctx (TestResult * tr); 869 870 /** 871 * Retrieve failure message from test result, if applicable. 872 * 873 * @return pointer to a message, if one exists. NULL otherwise. 874 * 875 * @since 0.6.0 876 */ 877 CK_DLL_EXP const char *CK_EXPORT tr_msg (TestResult * tr); 878 879 /** 880 * Retrieve line number at which a failure occurred, if applicable. 881 * 882 * @return If the test resulted in a failure, returns the line number 883 * that the failure occurred on; otherwise returns -1. 884 * 885 * @since 0.6.0 886 */ 887 CK_DLL_EXP int CK_EXPORT tr_lno (TestResult * tr); 888 889 /** 890 * Retrieve file name at which a failure occurred, if applicable. 891 * 892 * @return If the test resulted in a failure, returns a string 893 * containing the name of the file where the failure 894 * occurred; otherwise returns NULL. 895 * 896 * @since 0.6.0 897 */ 898 CK_DLL_EXP const char *CK_EXPORT tr_lfile (TestResult * tr); 899 900 /** 901 * Retrieve test case name in which a failure occurred, if applicable. 902 * 903 * @return If the test resulted in a failure, returns a string 904 * containing the name of the test suite where the failure 905 * occurred; otherwise returns NULL. 906 * 907 * @since 0.6.0 908 */ 909 CK_DLL_EXP const char *CK_EXPORT tr_tcname (TestResult * tr); 910 911 /** 912 * Creates a suite runner for the given suite. 913 * 914 * Once created, additional suites can be added to the 915 * suite runner using srunner_add_suite(), and the suite runner can be 916 * run with srunner_run_all(). Once finished, the suite runner 917 * must be freed with srunner_free(). 918 * 919 * @param s suite to generate a suite runner for 920 * 921 * @return suite runner for the given suite 922 * 923 * @since 0.6.0 924 */ 925 CK_DLL_EXP SRunner *CK_EXPORT srunner_create (Suite * s); 926 927 /** 928 * Add an additional suite to a suite runner. 929 * 930 * The first suite in a suite runner is always added in srunner_create(). 931 * This call adds additional suites to a suite runner. 932 * 933 * @param sr suite runner to add the given suite 934 * @param s suite to add to the given suite runner 935 * 936 * @since 0.7.0 937 */ 938 CK_DLL_EXP void CK_EXPORT srunner_add_suite (SRunner * sr, Suite * s); 939 940 /** 941 * Frees a suite runner, including all contained suite and test cases. 942 * 943 * This call is responsible for freeing all resources related to a 944 * suite runner and all contained suites and test cases. Suite and 945 * test cases need not be freed individually, as this call handles that. 946 * 947 * @param sr suite runner to free 948 * 949 * @since 0.6.0 950 */ 951 CK_DLL_EXP void CK_EXPORT srunner_free (SRunner * sr); 952 953 /** 954 * Runs a suite runner and all contained suite, printing results to 955 * stdout as specified by the print_mode. 956 * 957 * In addition to running all suites, if the suite runner has been 958 * configured to output to a log, that is also performed. 959 * 960 * Note that if the CK_RUN_CASE, CK_RUN_SUITE, CK_INCLUDE_TAGS and/or 961 * CK_EXCLUDE_TAGS environment variables are defined, then only the 962 * named suites or test cases will run. 963 * 964 * @param sr suite runner to run all suites from 965 * @param print_mode the verbosity in which to report results to stdout 966 * 967 * @since 0.6.0 968 */ 969 CK_DLL_EXP void CK_EXPORT srunner_run_all (SRunner * sr, 970 enum print_output print_mode); 971 972 /** 973 * Run a specific suite or test case from a suite runner, printing results 974 * to stdout as specified by the print_mode. 975 * 976 * In addition to running any applicable suites or test cases, if the 977 * suite runner has been configured to output to a log, that is also 978 * performed. 979 * 980 * Note that if the sname and tcname parameters are passed as null 981 * then the function will fallback to using the environment variables 982 * CK_RUN_SUITE and CK_RUN_CASE respectively in order to select the 983 * suite/cases. 984 * 985 * Similarly if the CK_INCLUDE_TAGS and/or CK_EXCLUDE_TAGS environment 986 * variables are defined then these will further filter the test cases 987 * (see srunner_run_tagged, below). 988 * 989 * @param sr suite runner where the given suite or test case must be 990 * @param sname suite name to run. A NULL means use the value of the 991 * environment variable CK_RUN_SUITE if set, otherwise run "any/every 992 * suite". 993 * @param tcname test case name to run. A NULL means use the value of 994 * the environment variable CK_RUN_CASE if set, otherwise run 995 * "any/every case". 996 * @param print_mode the verbosity in which to report results to stdout 997 * 998 * @since 0.9.9 999 */ 1000 CK_DLL_EXP void CK_EXPORT srunner_run (SRunner * sr, const char *sname, 1001 const char *tcname, enum print_output print_mode); 1002 1003 1004 /** 1005 * Run a specific suite or test case or testcases with specific tags 1006 * from a suite runner, printing results to stdout as specified by the 1007 * print_mode. 1008 * 1009 * In addition to running any applicable suites or test cases, if the 1010 * suite runner has been configured to output to a log, that is also 1011 * performed. 1012 * 1013 * Note that if sname, tcname, include_tags, exclude_tags parameters 1014 * are passed as NULL then if the environment variables CK_RUN_SUITE, 1015 * CK_RUN_CASE, CK_INCLUDE_TAGS, CK_EXCLUDE_TAGS are defined then these 1016 * values will be used instead. 1017 * 1018 * @param sr suite runner where the given suite or test case must be 1019 * @param sname suite name to run. A NULL means use the value of the 1020 * environment variable CK_RUN_SUITE if set, otherwise run "any/every 1021 * suite". 1022 * @param tcname test case name to run. A NULL means use the value of 1023 * the environment variable CK_RUN_CASE if set, otherwise run 1024 * "any/every case". 1025 * @param include_tags space separate list of tags. Only run test 1026 * cases that share one of these tags. A NULL means use the value of 1027 * the environment variable CK_INCLUDE_TAGS if set, otherwise run 1028 * "any/every test case". 1029 * @param exclude_tags space separate list of tags. Only run test 1030 * cases that do not share one of these tags even if they are selected 1031 * by an included tag. A NULL means use the value of the environment 1032 * variable CK_EXCLUDE_TAGS if set, otherwise run "any/every test 1033 * case". 1034 * @param print_mode the verbosity in which to report results to stdout 1035 * 1036 * @since 0.11.0 1037 */ 1038 CK_DLL_EXP void CK_EXPORT srunner_run_tagged (SRunner * sr, const char *sname, 1039 const char *tcname, 1040 const char *include_tags, 1041 const char *exclude_tags, enum print_output print_mode); 1042 1043 /** 1044 * Retrieve the number of failed tests executed by a suite runner. 1045 * 1046 * This value represents both test failures and errors. 1047 * 1048 * @param sr suite runner to query for all failed tests 1049 * 1050 * @return number of test failures and errors found by the suite runner 1051 * 1052 * @since 0.6.1 1053 */ 1054 CK_DLL_EXP int CK_EXPORT srunner_ntests_failed (SRunner * sr); 1055 1056 /** 1057 * Retrieve the total number of tests run by a suite runner. 1058 * 1059 * @param sr suite runner to query for all tests run 1060 * 1061 * @return number of all tests run by the suite runner 1062 * 1063 * @since 0.6.1 1064 */ 1065 CK_DLL_EXP int CK_EXPORT srunner_ntests_run (SRunner * sr); 1066 1067 /** 1068 * Return an array of results for all failures found by a suite runner. 1069 * 1070 * Number of results is equal to srunner_nfailed_tests(). 1071 * 1072 * Information about individual results can be queried using: 1073 * tr_rtype(), tr_ctx(), tr_msg(), tr_lno(), tr_lfile(), and tr_tcname(). 1074 * 1075 * Memory is malloc'ed and must be freed; however free the entire structure 1076 * instead of individual test cases. 1077 * 1078 * @param sr suite runner to retrieve results from 1079 * 1080 * @return array of TestResult objects 1081 * 1082 * @since 0.6.0 1083 */ 1084 CK_DLL_EXP TestResult **CK_EXPORT srunner_failures (SRunner * sr); 1085 1086 /** 1087 * Return an array of results for all tests run by a suite runner. 1088 * 1089 * Number of results is equal to srunner_ntests_run(), and excludes 1090 * failures due to setup function failure. 1091 * 1092 * Information about individual results can be queried using: 1093 * tr_rtype(), tr_ctx(), tr_msg(), tr_lno(), tr_lfile(), and tr_tcname(). 1094 * 1095 * Memory is malloc'ed and must be freed; however free the entire structure 1096 * instead of individual test cases. 1097 * 1098 * @param sr suite runner to retrieve results from 1099 * 1100 * @return array of TestResult objects 1101 * 1102 * @since 0.6.1 1103 */ 1104 CK_DLL_EXP TestResult **CK_EXPORT srunner_results (SRunner * sr); 1105 1106 /** 1107 * Print the results contained in an SRunner to stdout. 1108 * 1109 * @param sr suite runner to print results for to stdout 1110 * @param print_mode the print_output (verbosity) to use to report 1111 * the result 1112 * 1113 * @since 0.7.0 1114 */ 1115 CK_DLL_EXP void CK_EXPORT srunner_print (SRunner * sr, 1116 enum print_output print_mode); 1117 1118 /** 1119 * Set the suite runner to output the result in log format to the 1120 * given file. 1121 * 1122 * Note: log file setting is an initialize only operation -- it should 1123 * be done immediately after SRunner creation, and the log file can't be 1124 * changed after being set. 1125 * 1126 * This setting does not conflict with the other log output types; 1127 * all logging types can occur concurrently if configured. 1128 * 1129 * @param sr suite runner to log results of in log format 1130 * @param fname file name to output log results to 1131 * 1132 * @since 0.7.1 1133 */ 1134 CK_DLL_EXP void CK_EXPORT srunner_set_log (SRunner * sr, const char *fname); 1135 1136 /** 1137 * Checks if the suite runner is assigned a file for log output. 1138 * 1139 * @param sr suite runner to check 1140 * 1141 * @return 1 iff the suite runner currently is configured to output 1142 * in log format; 0 otherwise 1143 * 1144 * @since 0.7.1 1145 */ 1146 CK_DLL_EXP int CK_EXPORT srunner_has_log (SRunner * sr); 1147 1148 /** 1149 * Retrieves the name of the currently assigned file 1150 * for log output, if any exists. 1151 * 1152 * @return the name of the log file, or NULL if none is configured 1153 * 1154 * @since 0.7.1 1155 */ 1156 CK_DLL_EXP const char *CK_EXPORT srunner_log_fname (SRunner * sr); 1157 1158 /** 1159 * Set the suite runner to output the result in XML format to the 1160 * given file. 1161 * 1162 * Note: XML file setting is an initialize only operation -- it should 1163 * be done immediately after SRunner creation, and the XML file can't be 1164 * changed after being set. 1165 * 1166 * This setting does not conflict with the other log output types; 1167 * all logging types can occur concurrently if configured. 1168 * 1169 * @param sr suite runner to log results of in XML format 1170 * @param fname file name to output XML results to 1171 * 1172 * @since 0.9.1 1173 */ 1174 CK_DLL_EXP void CK_EXPORT srunner_set_xml (SRunner * sr, const char *fname); 1175 1176 /** 1177 * Checks if the suite runner is assigned a file for XML output. 1178 * 1179 * @param sr suite runner to check 1180 * 1181 * @return 1 iff the suite runner currently is configured to output 1182 * in XML format; 0 otherwise 1183 * 1184 * @since 0.9.1 1185 */ 1186 CK_DLL_EXP int CK_EXPORT srunner_has_xml (SRunner * sr); 1187 1188 /** 1189 * Retrieves the name of the currently assigned file 1190 * for XML output, if any exists. 1191 * 1192 * @return the name of the XML file, or NULL if none is configured 1193 * 1194 * @since 0.9.1 1195 */ 1196 CK_DLL_EXP const char *CK_EXPORT srunner_xml_fname (SRunner * sr); 1197 1198 /** 1199 * Set the suite runner to output the result in TAP format to the 1200 * given file. 1201 * 1202 * Note: TAP file setting is an initialize only operation -- it should 1203 * be done immediately after SRunner creation, and the TAP file can't be 1204 * changed after being set. 1205 * 1206 * This setting does not conflict with the other log output types; 1207 * all logging types can occur concurrently if configured. 1208 * 1209 * @param sr suite runner to log results of in TAP format 1210 * @param fname file name to output TAP results to 1211 * 1212 * @since 0.9.12 1213 */ 1214 CK_DLL_EXP void CK_EXPORT srunner_set_tap (SRunner * sr, const char *fname); 1215 1216 /** 1217 * Checks if the suite runner is assigned a file for TAP output. 1218 * 1219 * @param sr suite runner to check 1220 * 1221 * @return 1 iff the suite runner currently is configured to output 1222 * in TAP format; 0 otherwise 1223 * 1224 * @since 0.9.12 1225 */ 1226 CK_DLL_EXP int CK_EXPORT srunner_has_tap (SRunner * sr); 1227 1228 /** 1229 * Retrieves the name of the currently assigned file 1230 * for TAP output, if any exists. 1231 * 1232 * @return the name of the TAP file, or NULL if none is configured 1233 * 1234 * @since 0.9.12 1235 */ 1236 CK_DLL_EXP const char *CK_EXPORT srunner_tap_fname (SRunner * sr); 1237 1238 /** 1239 * Enum describing the current fork usage. 1240 */ 1241 enum fork_status 1242 { 1243 CK_FORK_GETENV, /**< look in the environment for CK_FORK */ 1244 CK_FORK, /**< call fork to run tests */ 1245 CK_NOFORK /**< don't call fork */ 1246 }; 1247 1248 /** 1249 * Retrieve the current fork status for the given suite runner 1250 * 1251 * @param sr suite runner to check fork status of 1252 * 1253 * @since 0.8.0 1254 */ 1255 CK_DLL_EXP enum fork_status CK_EXPORT srunner_fork_status (SRunner * sr); 1256 1257 /** 1258 * Set the fork status for a given suite runner. 1259 * 1260 * The default fork status is CK_FORK_GETENV, which will look 1261 * for the CK_FORK environment variable, which can be set to 1262 * "yes" or "no". If the environment variable is not present, 1263 * CK_FORK will be used if fork() is available on the system, 1264 * otherwise CK_NOFORK is used. 1265 * 1266 * If set to CK_FORK or CK_NOFORK, the environment variable 1267 * if defined is ignored. 1268 * 1269 * If Check is compiled without support for fork(), attempting 1270 * to set the status to CK_FORK is ignored. 1271 * 1272 * @param sr suite runner to assign the fork status to 1273 * @param fstat fork status to assign 1274 * 1275 * @since 0.8.0 1276 */ 1277 CK_DLL_EXP void CK_EXPORT srunner_set_fork_status (SRunner * sr, 1278 enum fork_status fstat); 1279 1280 /** 1281 * Invoke fork() during a test and assign the child to the same 1282 * process group that the rest of the test case uses. 1283 * 1284 * One can invoke fork() directly during a test; however doing so 1285 * may not guarantee that any children processes are destroyed once 1286 * the test finishes. Once a test has completed, all processes in 1287 * the process group will be killed; using this wrapper will prevent 1288 * orphan processes. 1289 * 1290 * If Check is compiled without fork() support this call simply 1291 * return -1 and does nothing. 1292 * 1293 * @return On success, the PID of the child process is returned in 1294 * the parent, and 0 is returned in the child. On failure, 1295 * a value of -1 is returned to the parent process and no 1296 * child process is created. 1297 * 1298 * @since 0.9.3 1299 */ 1300 #if !defined(_MSC_VER) 1301 CK_DLL_EXP pid_t CK_EXPORT check_fork (void); 1302 #endif 1303 1304 /** 1305 * Wait for the pid and exit. 1306 * 1307 * This is to be used in conjunction with check_fork(). When called, 1308 * will wait for the given process to terminate. If the process 1309 * exited without error, exit(EXIT_SUCCESS) is invoked; otherwise 1310 * exit(EXIT_FAILURE) is invoked. 1311 * 1312 * If Check is compiled without support for fork(), this invokes 1313 * exit(EXIT_FAILURE). 1314 * 1315 * @param pid process to wait for, created by check_fork() 1316 * 1317 * @since 0.9.3 1318 */ 1319 #if !defined(_MSC_VER) 1320 CK_DLL_EXP void CK_EXPORT 1321 check_waitpid_and_exit (pid_t pid) 1322 CK_ATTRIBUTE_NORETURN; 1323 #endif 1324 1325 #ifdef __cplusplus 1326 CK_CPPEND 1327 #endif 1328 #endif /* CHECK_H */ 1329