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 } 37CK_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 (@CHECK_MAJOR_VERSION@) 79#define CHECK_MINOR_VERSION (@CHECK_MINOR_VERSION@) 80#define CHECK_MICRO_VERSION (@CHECK_MICRO_VERSION@) 81CK_DLL_EXP /*extern*/ int CK_EXPORT check_major_version; 82CK_DLL_EXP /*extern*/ int CK_EXPORT check_minor_version; 83CK_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*/ 100typedef struct TCase TCase; 101 102/** 103 * Type for a test function 104 */ 105typedef void (*TFun) (int); 106 107/** 108 * Type for a setup/teardown function 109 */ 110typedef void (*SFun) (void); 111 112/** 113 * Type for a test suite 114 */ 115typedef 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 */ 131CK_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 */ 145CK_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 */ 158CK_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 * */ 173CK_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 * */ 186CK_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*/ 289CK_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 */ 317CK_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*/ 346CK_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 */ 369CK_DLL_EXP void CK_EXPORT tcase_set_timeout (TCase * tc, double timeout); 370 371/* Internal function to mark the start of a test function */ 372CK_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)\ 383static 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 * Note that it only has the noreturn modifier when 426 * using fork. If fork is unavailable, the function 427 * calls longjmp() when a test assertion fails. Marking 428 * the function as noreturn causes gcc to make assumptions 429 * which are not valid, as longjmp() is like a return. 430 */ 431#if @HAVE_FORK@ 432CK_DLL_EXP void CK_EXPORT 433_ck_assert_failed (const char *file, int line, const char *expr, ...) 434 CK_ATTRIBUTE_NORETURN; 435#else 436CK_DLL_EXP void CK_EXPORT _ck_assert_failed (const char *file, int line, 437 const char *expr, ...); 438#endif 439 440/** 441 * Fail the test if expression is false 442 * 443 * @param expr expression to evaluate 444 * 445 * @note If the check fails, the remaining of the test is aborted 446 * 447 * @since 0.9.6 448 */ 449#define ck_assert(expr) ck_assert_msg(expr, NULL) 450 451/* The space before the comma sign before ## is essential to be compatible 452 with gcc 2.95.3 and earlier. 453*/ 454/** 455 * Fail the test if the expression is false; print message on failure 456 * 457 * @param expr expression to evaluate 458 * @param ... message to print (in printf format) if expression is false 459 * 460 * @note If the check fails, the remaining of the test is aborted 461 * 462 * @since 0.9.6 463 */ 464#define ck_assert_msg(expr, ...) \ 465 (expr) ? \ 466 _mark_point(__FILE__, __LINE__) : \ 467 _ck_assert_failed(__FILE__, __LINE__, "Assertion '"#expr"' failed" , ## __VA_ARGS__, NULL) 468 469/** 470 * Unconditionally fail the test 471 * 472 * @note Once called, the remaining of the test is aborted 473 * 474 * @since 0.9.6 475 */ 476#define ck_abort() ck_abort_msg(NULL) 477/** 478 * Unconditionally fail the test; print a message 479 * 480 * @param ... message to print (in printf format) 481 * 482 * @note Once called, the remaining of the test is aborted 483 * 484 * @since 0.9.6 485 */ 486#define ck_abort_msg(...) _ck_assert_failed(__FILE__, __LINE__, "Failed" , ## __VA_ARGS__, NULL) 487 488/* Signed and unsigned integer comparison macros with improved output compared to ck_assert(). */ 489/* OP may be any comparison operator. */ 490#define _ck_assert_int(X, OP, Y) do { \ 491 gint64 _ck_x = (X); \ 492 gint64 _ck_y = (Y); \ 493 ck_assert_msg(_ck_x OP _ck_y, "Assertion '%s' failed: " \ 494 "%s==%" G_GINT64_FORMAT ", %s==%" G_GINT64_FORMAT, #X#OP#Y, #X, _ck_x, #Y, _ck_y); \ 495} while (0) 496 497/** 498 * Check two signed integers to determine if X==Y 499 * 500 * If not X==Y, the test fails. 501 * 502 * @param X signed integer 503 * @param Y signed integer to compare against X 504 * 505 * @note If the check fails, the remaining of the test is aborted 506 * 507 * @since 0.9.6 508 */ 509#define ck_assert_int_eq(X, Y) _ck_assert_int(X, ==, Y) 510/** 511 * Check two signed integers to determine if X!=Y 512 * 513 * If not X!=Y, the test fails. 514 * 515 * @param X signed integer 516 * @param Y signed integer to compare against X 517 * 518 * @note If the check fails, the remaining of the test is aborted 519 * 520 * @since 0.9.6 521 */ 522#define ck_assert_int_ne(X, Y) _ck_assert_int(X, !=, Y) 523/** 524 * Check two signed integers to determine if X<Y 525 * 526 * If not X<Y, the test fails. 527 * 528 * @param X signed integer 529 * @param Y signed integer to compare against X 530 * 531 * @note If the check fails, the remaining of the test is aborted 532 * 533 * @since 0.9.10 534 */ 535#define ck_assert_int_lt(X, Y) _ck_assert_int(X, <, Y) 536/** 537 * Check two signed integers to determine if X<=Y 538 * 539 * If not X<=Y, the test fails. 540 * 541 * @param X signed integer 542 * @param Y signed integer to compare against X 543 * 544 * @note If the check fails, the remaining of the test is aborted 545 * 546 * @since 0.9.10 547 */ 548#define ck_assert_int_le(X, Y) _ck_assert_int(X, <=, Y) 549/** 550 * Check two signed integers to determine if X>Y 551 * 552 * If not X>Y, the test fails. 553 * 554 * @param X signed integer 555 * @param Y signed integer to compare against X 556 * 557 * @note If the check fails, the remaining of the test is aborted 558 * 559 * @since 0.9.10 560 */ 561#define ck_assert_int_gt(X, Y) _ck_assert_int(X, >, Y) 562/** 563 * Check two signed integers to determine if X>=Y 564 * 565 * If not X>=Y, the test fails. 566 * 567 * @param X signed integer 568 * @param Y signed integer to compare against X 569 * 570 * @note If the check fails, the remaining of the test is aborted 571 * 572 * @since 0.9.10 573 */ 574#define ck_assert_int_ge(X, Y) _ck_assert_int(X, >=, Y) 575 576#define _ck_assert_uint(X, OP, Y) do { \ 577 guint64 _ck_x = (X); \ 578 guint64 _ck_y = (Y); \ 579 ck_assert_msg(_ck_x OP _ck_y, "Assertion '%s' failed: " \ 580 "%s==%" G_GUINT64_FORMAT ", %s==%" G_GUINT64_FORMAT, #X#OP#Y, #X, _ck_x, #Y, _ck_y); \ 581} while (0) 582/** 583 * Check two unsigned integers to determine if X==Y 584 * 585 * If not X==Y, the test fails. 586 * 587 * @param X signed integer 588 * @param Y signed integer to compare against X 589 * 590 * @note If the check fails, the remaining of the test is aborted 591 * 592 * @since 0.9.10 593 */ 594#define ck_assert_uint_eq(X, Y) _ck_assert_uint(X, ==, Y) 595/** 596 * Check two unsigned integers to determine if X!=Y 597 * 598 * If not X!=Y, the test fails. 599 * 600 * @param X signed integer 601 * @param Y signed integer to compare against X 602 * 603 * @note If the check fails, the remaining of the test is aborted 604 * 605 * @since 0.9.10 606 */ 607#define ck_assert_uint_ne(X, Y) _ck_assert_uint(X, !=, Y) 608/** 609 * Check two unsigned integers to determine if X<Y 610 * 611 * If not X<Y, the test fails. 612 * 613 * @param X signed integer 614 * @param Y signed integer to compare against X 615 * 616 * @note If the check fails, the remaining of the test is aborted 617 * 618 * @since 0.9.10 619 */ 620#define ck_assert_uint_lt(X, Y) _ck_assert_uint(X, <, Y) 621/** 622 * Check two unsigned integers to determine if X<=Y 623 * 624 * If not X<=Y, the test fails. 625 * 626 * @param X signed integer 627 * @param Y signed integer to compare against X 628 * 629 * @note If the check fails, the remaining of the test is aborted 630 * 631 * @since 0.9.10 632 */ 633#define ck_assert_uint_le(X, Y) _ck_assert_uint(X, <=, Y) 634/** 635 * Check two unsigned integers to determine if X>Y 636 * 637 * If not X>Y, the test fails. 638 * 639 * @param X signed integer 640 * @param Y signed integer to compare against X 641 * 642 * @note If the check fails, the remaining of the test is aborted 643 * 644 * @since 0.9.10 645 */ 646#define ck_assert_uint_gt(X, Y) _ck_assert_uint(X, >, Y) 647/** 648 * Check two unsigned integers to determine if X>=Y 649 * 650 * If not X>=Y, the test fails. 651 * 652 * @param X signed integer 653 * @param Y signed integer to compare against X 654 * 655 * @note If the check fails, the remaining of the test is aborted 656 * 657 * @since 0.9.10 658 */ 659#define ck_assert_uint_ge(X, Y) _ck_assert_uint(X, >=, Y) 660 661/* String comparison macros with improved output compared to ck_assert() */ 662/* OP might be any operator that can be used in '0 OP strcmp(X,Y)' comparison */ 663/* The x and y parameter swap in strcmp() is needed to handle >, >=, <, <= operators */ 664#define _ck_assert_str(X, OP, Y) do { \ 665 const char* _ck_x = (X); \ 666 const char* _ck_y = (Y); \ 667 ck_assert_msg(0 OP strcmp(_ck_y, _ck_x), \ 668 "Assertion '%s' failed: %s==\"%s\", %s==\"%s\"", #X#OP#Y, #X, _ck_x, #Y, _ck_y); \ 669} while (0) 670/** 671 * Check two strings to determine if 0==strcmp(X,Y) 672 * 673 * If not 0==strcmp(X,Y), the test fails. 674 * 675 * @param X string 676 * @param Y string to compare against X 677 * 678 * @note If the check fails, the remaining of the test is aborted 679 * 680 * @since 0.9.6 681 */ 682#define ck_assert_str_eq(X, Y) _ck_assert_str(X, ==, Y) 683/** 684 * Check two strings to determine if 0!=strcmp(X,Y) 685 * 686 * If not 0!=strcmp(X,Y), the test fails. 687 * 688 * @param X string 689 * @param Y string to compare against X 690 * 691 * @note If the check fails, the remaining of the test is aborted 692 * 693 * @since 0.9.6 694 */ 695#define ck_assert_str_ne(X, Y) _ck_assert_str(X, !=, Y) 696/** 697 * Check two strings to determine if 0<strcmp(X,Y), (e.g. strcmp(X,Y)>0) 698 * 699 * If not 0<strcmp(X,Y), the test fails. 700 * 701 * @param X string 702 * @param Y string to compare against X 703 * 704 * @note If the check fails, the remaining of the test is aborted 705 * 706 * @since 0.9.10 707 */ 708#define ck_assert_str_lt(X, Y) _ck_assert_str(X, <, Y) 709/** 710 * Check two strings to determine if 0<=strcmp(X,Y) (e.g. strcmp(X,Y)>=0) 711 * 712 * If not 0<=strcmp(X,Y), the test fails. 713 * 714 * @param X string 715 * @param Y string to compare against X 716 * 717 * @note If the check fails, the remaining of the test is aborted 718 * 719 * @since 0.9.10 720 */ 721#define ck_assert_str_le(X, Y) _ck_assert_str(X, <=, Y) 722/** 723 * Check two strings to determine if 0<strcmp(X,Y) (e.g. strcmp(X,Y)>0) 724 * 725 * If not 0<strcmp(X,Y), the test fails. 726 * 727 * @param X string 728 * @param Y string to compare against X 729 * 730 * @note If the check fails, the remaining of the test is aborted 731 * 732 * @since 0.9.10 733 */ 734#define ck_assert_str_gt(X, Y) _ck_assert_str(X, >, Y) 735/** 736 * Check two strings to determine if 0>=strcmp(X,Y) (e.g. strcmp(X,Y)<=0) 737 * 738 * If not 0>=strcmp(X,Y), the test fails. 739 * 740 * @param X string 741 * @param Y string to compare against X 742 * 743 * @note If the check fails, the remaining of the test is aborted 744 * 745 * @since 0.9.10 746 */ 747#define ck_assert_str_ge(X, Y) _ck_assert_str(X, >=, Y) 748 749/* Pointer comparison macros with improved output compared to ck_assert(). */ 750/* OP may only be == or != */ 751#define _ck_assert_ptr(X, OP, Y) do { \ 752 const void* _ck_x = (X); \ 753 const void* _ck_y = (Y); \ 754 ck_assert_msg(_ck_x OP _ck_y, "Assertion '%s' failed: %s==%#x, %s==%#x", #X#OP#Y, #X, _ck_x, #Y, _ck_y); \ 755} while (0) 756 757/** 758 * Check if two pointers are equal. 759 * 760 * If the two passed pointers are not equal, the test 761 * fails. 762 * 763 * @param X pointer 764 * @param Y pointer to compare against X 765 * 766 * @note If the check fails, the remaining of the test is aborted 767 * 768 * @since 0.9.10 769 */ 770#define ck_assert_ptr_eq(X, Y) _ck_assert_ptr(X, ==, Y) 771 772/** 773 * Check if two pointers are not. 774 * 775 * If the two passed pointers are equal, the test fails. 776 * 777 * @param X pointer 778 * @param Y pointer to compare against X 779 * 780 * @since 0.9.10 781 */ 782#define ck_assert_ptr_ne(X, Y) _ck_assert_ptr(X, !=, Y) 783 784/** 785 * Mark the last point reached in a unit test. 786 * 787 * If the test throws a signal or exits, the location noted with the 788 * failure is the last location of a ck_assert*() or ck_abort() call. 789 * Use mark_point() to record intermediate locations (useful for tracking down 790 * crashes or exits). 791 * 792 * @since 0.6.0 793*/ 794#define mark_point() _mark_point(__FILE__,__LINE__) 795 796/* Non macro version of #mark_point */ 797CK_DLL_EXP void CK_EXPORT _mark_point (const char *file, int line); 798 799/** 800 * Enum describing the possible results of a test 801 */ 802enum test_result 803{ 804 CK_TEST_RESULT_INVALID, /**< Default value; should not encounter this */ 805 CK_PASS, /**< Test passed */ 806 CK_FAILURE, /**< Test completed but failed */ 807 CK_ERROR /**< Test failed to complete 808 (unexpected signal or non-zero early exit) */ 809}; 810 811/** 812 * Enum specifying the verbosity of output a SRunner should produce 813 */ 814enum print_output 815{ 816 CK_SILENT, /**< No output */ 817 CK_MINIMAL, /**< Only summary output */ 818 CK_NORMAL, /**< All failed tests */ 819 CK_VERBOSE, /**< All tests */ 820 CK_ENV, /**< Look at environment var CK_VERBOSITY 821 for what verbosity to use, which can be 822 either "silent", "minimal", "normal", 823 or "verbose". If the environment variable 824 is not set, then CK_NORMAL will be used.*/ 825#if @ENABLE_SUBUNIT@ 826 CK_SUBUNIT, /**< Run as a subunit child process */ 827#endif 828 CK_LAST /**< Not a valid option */ 829}; 830 831/** 832 * Holds state for a running of a test suite 833 */ 834typedef struct SRunner SRunner; 835 836/** 837 * Opaque type for a test failure 838 */ 839typedef struct TestResult TestResult; 840 841/** 842 * Enum representing the types of contexts for a test 843 */ 844enum ck_result_ctx 845{ 846 CK_CTX_INVALID, /**< Default value; should not encounter this */ 847 CK_CTX_SETUP, /**< Setup before a test */ 848 CK_CTX_TEST, /**< Body of test itself */ 849 CK_CTX_TEARDOWN /**< Teardown after a test */ 850}; 851 852/** 853 * Retrieve type of result that the given test result represents. 854 * 855 * This is a member of test_result, and can represent a 856 * pass, failure, or error. 857 * 858 * @param tr test result to retrieve result from 859 * 860 * @return result of given test 861 * 862 * @since 0.6.0 863 */ 864CK_DLL_EXP int CK_EXPORT tr_rtype (TestResult * tr); 865 866/** 867 * Retrieve context in which the result occurred for the given test result. 868 * 869 * The types of contents include the test setup, teardown, or the 870 * body of the test itself. 871 * 872 * @param tr test result to retrieve context from 873 * 874 * @return context to which the given test result applies 875 * 876 * @since 0.8.0 877 */ 878CK_DLL_EXP enum ck_result_ctx CK_EXPORT tr_ctx (TestResult * tr); 879 880/** 881 * Retrieve failure message from test result, if applicable. 882 * 883 * @return pointer to a message, if one exists. NULL otherwise. 884 * 885 * @since 0.6.0 886 */ 887CK_DLL_EXP const char *CK_EXPORT tr_msg (TestResult * tr); 888 889/** 890 * Retrieve line number at which a failure occurred, if applicable. 891 * 892 * @return If the test resulted in a failure, returns the line number 893 * that the failure occurred on; otherwise returns -1. 894 * 895 * @since 0.6.0 896 */ 897CK_DLL_EXP int CK_EXPORT tr_lno (TestResult * tr); 898 899/** 900 * Retrieve file name at which a failure occurred, if applicable. 901 * 902 * @return If the test resulted in a failure, returns a string 903 * containing the name of the file where the failure 904 * occurred; otherwise returns NULL. 905 * 906 * @since 0.6.0 907 */ 908CK_DLL_EXP const char *CK_EXPORT tr_lfile (TestResult * tr); 909 910/** 911 * Retrieve test case name in which a failure occurred, if applicable. 912 * 913 * @return If the test resulted in a failure, returns a string 914 * containing the name of the test suite where the failure 915 * occurred; otherwise returns NULL. 916 * 917 * @since 0.6.0 918 */ 919CK_DLL_EXP const char *CK_EXPORT tr_tcname (TestResult * tr); 920 921/** 922 * Creates a suite runner for the given suite. 923 * 924 * Once created, additional suites can be added to the 925 * suite runner using srunner_add_suite(), and the suite runner can be 926 * run with srunner_run_all(). Once finished, the suite runner 927 * must be freed with srunner_free(). 928 * 929 * @param s suite to generate a suite runner for 930 * 931 * @return suite runner for the given suite 932 * 933 * @since 0.6.0 934 */ 935CK_DLL_EXP SRunner *CK_EXPORT srunner_create (Suite * s); 936 937/** 938 * Add an additional suite to a suite runner. 939 * 940 * The first suite in a suite runner is always added in srunner_create(). 941 * This call adds additional suites to a suite runner. 942 * 943 * @param sr suite runner to add the given suite 944 * @param s suite to add to the given suite runner 945 * 946 * @since 0.7.0 947 */ 948CK_DLL_EXP void CK_EXPORT srunner_add_suite (SRunner * sr, Suite * s); 949 950/** 951 * Frees a suite runner, including all contained suite and test cases. 952 * 953 * This call is responsible for freeing all resources related to a 954 * suite runner and all contained suites and test cases. Suite and 955 * test cases need not be freed individually, as this call handles that. 956 * 957 * @param sr suite runner to free 958 * 959 * @since 0.6.0 960 */ 961CK_DLL_EXP void CK_EXPORT srunner_free (SRunner * sr); 962 963/** 964 * Runs a suite runner and all contained suite, printing results to 965 * stdout as specified by the print_mode. 966 * 967 * In addition to running all suites, if the suite runner has been 968 * configured to output to a log, that is also performed. 969 * 970 * Note that if the CK_RUN_CASE, CK_RUN_SUITE, CK_INCLUDE_TAGS and/or 971 * CK_EXCLUDE_TAGS environment variables are defined, then only the 972 * named suites or test cases will run. 973 * 974 * @param sr suite runner to run all suites from 975 * @param print_mode the verbosity in which to report results to stdout 976 * 977 * @since 0.6.0 978 */ 979CK_DLL_EXP void CK_EXPORT srunner_run_all (SRunner * sr, 980 enum print_output print_mode); 981 982/** 983 * Run a specific suite or test case from a suite runner, printing results 984 * to stdout as specified by the print_mode. 985 * 986 * In addition to running any applicable suites or test cases, if the 987 * suite runner has been configured to output to a log, that is also 988 * performed. 989 * 990 * Note that if the sname and tcname parameters are passed as null 991 * then the function will fallback to using the environment variables 992 * CK_RUN_SUITE and CK_RUN_CASE respectively in order to select the 993 * suite/cases. 994 * 995 * Similarly if the CK_INCLUDE_TAGS and/or CK_EXCLUDE_TAGS environment 996 * variables are defined then these will further filter the test cases 997 * (see srunner_run_tagged, below). 998 * 999 * @param sr suite runner where the given suite or test case must be 1000 * @param sname suite name to run. A NULL means use the value of the 1001 * environment variable CK_RUN_SUITE if set, otherwise run "any/every 1002 * suite". 1003 * @param tcname test case name to run. A NULL means use the value of 1004 * the environment variable CK_RUN_CASE if set, otherwise run 1005 * "any/every case". 1006 * @param print_mode the verbosity in which to report results to stdout 1007 * 1008 * @since 0.9.9 1009 */ 1010CK_DLL_EXP void CK_EXPORT srunner_run (SRunner * sr, const char *sname, 1011 const char *tcname, enum print_output print_mode); 1012 1013 1014/** 1015 * Run a specific suite or test case or testcases with specific tags 1016 * from a suite runner, printing results to stdout as specified by the 1017 * print_mode. 1018 * 1019 * In addition to running any applicable suites or test cases, if the 1020 * suite runner has been configured to output to a log, that is also 1021 * performed. 1022 * 1023 * Note that if sname, tcname, include_tags, exclude_tags parameters 1024 * are passed as NULL then if the environment variables CK_RUN_SUITE, 1025 * CK_RUN_CASE, CK_INCLUDE_TAGS, CK_EXCLUDE_TAGS are defined then these 1026 * values will be used instead. 1027 * 1028 * @param sr suite runner where the given suite or test case must be 1029 * @param sname suite name to run. A NULL means use the value of the 1030 * environment variable CK_RUN_SUITE if set, otherwise run "any/every 1031 * suite". 1032 * @param tcname test case name to run. A NULL means use the value of 1033 * the environment variable CK_RUN_CASE if set, otherwise run 1034 * "any/every case". 1035 * @param include_tags space separate list of tags. Only run test 1036 * cases that share one of these tags. A NULL means use the value of 1037 * the environment variable CK_INCLUDE_TAGS if set, otherwise run 1038 * "any/every test case". 1039 * @param exclude_tags space separate list of tags. Only run test 1040 * cases that do not share one of these tags even if they are selected 1041 * by an included tag. A NULL means use the value of the environment 1042 * variable CK_EXCLUDE_TAGS if set, otherwise run "any/every test 1043 * case". 1044 * @param print_mode the verbosity in which to report results to stdout 1045 * 1046 * @since 0.11.0 1047 */ 1048CK_DLL_EXP void CK_EXPORT srunner_run_tagged (SRunner * sr, const char *sname, 1049 const char *tcname, 1050 const char *include_tags, 1051 const char *exclude_tags, enum print_output print_mode); 1052 1053/** 1054 * Retrieve the number of failed tests executed by a suite runner. 1055 * 1056 * This value represents both test failures and errors. 1057 * 1058 * @param sr suite runner to query for all failed tests 1059 * 1060 * @return number of test failures and errors found by the suite runner 1061 * 1062 * @since 0.6.1 1063 */ 1064CK_DLL_EXP int CK_EXPORT srunner_ntests_failed (SRunner * sr); 1065 1066/** 1067 * Retrieve the total number of tests run by a suite runner. 1068 * 1069 * @param sr suite runner to query for all tests run 1070 * 1071 * @return number of all tests run by the suite runner 1072 * 1073 * @since 0.6.1 1074 */ 1075CK_DLL_EXP int CK_EXPORT srunner_ntests_run (SRunner * sr); 1076 1077/** 1078 * Return an array of results for all failures found by a suite runner. 1079 * 1080 * Number of results is equal to srunner_nfailed_tests(). 1081 * 1082 * Information about individual results can be queried using: 1083 * tr_rtype(), tr_ctx(), tr_msg(), tr_lno(), tr_lfile(), and tr_tcname(). 1084 * 1085 * Memory is malloc'ed and must be freed; however free the entire structure 1086 * instead of individual test cases. 1087 * 1088 * @param sr suite runner to retrieve results from 1089 * 1090 * @return array of TestResult objects 1091 * 1092 * @since 0.6.0 1093 */ 1094CK_DLL_EXP TestResult **CK_EXPORT srunner_failures (SRunner * sr); 1095 1096/** 1097 * Return an array of results for all tests run by a suite runner. 1098 * 1099 * Number of results is equal to srunner_ntests_run(), and excludes 1100 * failures due to setup function failure. 1101 * 1102 * Information about individual results can be queried using: 1103 * tr_rtype(), tr_ctx(), tr_msg(), tr_lno(), tr_lfile(), and tr_tcname(). 1104 * 1105 * Memory is malloc'ed and must be freed; however free the entire structure 1106 * instead of individual test cases. 1107 * 1108 * @param sr suite runner to retrieve results from 1109 * 1110 * @return array of TestResult objects 1111 * 1112 * @since 0.6.1 1113*/ 1114CK_DLL_EXP TestResult **CK_EXPORT srunner_results (SRunner * sr); 1115 1116/** 1117 * Print the results contained in an SRunner to stdout. 1118 * 1119 * @param sr suite runner to print results for to stdout 1120 * @param print_mode the print_output (verbosity) to use to report 1121 * the result 1122 * 1123 * @since 0.7.0 1124 */ 1125CK_DLL_EXP void CK_EXPORT srunner_print (SRunner * sr, 1126 enum print_output print_mode); 1127 1128/** 1129 * Set the suite runner to output the result in log format to the 1130 * given file. 1131 * 1132 * Note: log file setting is an initialize only operation -- it should 1133 * be done immediately after SRunner creation, and the log file can't be 1134 * changed after being set. 1135 * 1136 * This setting does not conflict with the other log output types; 1137 * all logging types can occur concurrently if configured. 1138 * 1139 * @param sr suite runner to log results of in log format 1140 * @param fname file name to output log results to 1141 * 1142 * @since 0.7.1 1143*/ 1144CK_DLL_EXP void CK_EXPORT srunner_set_log (SRunner * sr, const char *fname); 1145 1146/** 1147 * Checks if the suite runner is assigned a file for log output. 1148 * 1149 * @param sr suite runner to check 1150 * 1151 * @return 1 iff the suite runner currently is configured to output 1152 * in log format; 0 otherwise 1153 * 1154 * @since 0.7.1 1155 */ 1156CK_DLL_EXP int CK_EXPORT srunner_has_log (SRunner * sr); 1157 1158/** 1159 * Retrieves the name of the currently assigned file 1160 * for log output, if any exists. 1161 * 1162 * @return the name of the log file, or NULL if none is configured 1163 * 1164 * @since 0.7.1 1165 */ 1166CK_DLL_EXP const char *CK_EXPORT srunner_log_fname (SRunner * sr); 1167 1168/** 1169 * Set the suite runner to output the result in XML format to the 1170 * given file. 1171 * 1172 * Note: XML file setting is an initialize only operation -- it should 1173 * be done immediately after SRunner creation, and the XML file can't be 1174 * changed after being set. 1175 * 1176 * This setting does not conflict with the other log output types; 1177 * all logging types can occur concurrently if configured. 1178 * 1179 * @param sr suite runner to log results of in XML format 1180 * @param fname file name to output XML results to 1181 * 1182 * @since 0.9.1 1183*/ 1184CK_DLL_EXP void CK_EXPORT srunner_set_xml (SRunner * sr, const char *fname); 1185 1186/** 1187 * Checks if the suite runner is assigned a file for XML output. 1188 * 1189 * @param sr suite runner to check 1190 * 1191 * @return 1 iff the suite runner currently is configured to output 1192 * in XML format; 0 otherwise 1193 * 1194 * @since 0.9.1 1195 */ 1196CK_DLL_EXP int CK_EXPORT srunner_has_xml (SRunner * sr); 1197 1198/** 1199 * Retrieves the name of the currently assigned file 1200 * for XML output, if any exists. 1201 * 1202 * @return the name of the XML file, or NULL if none is configured 1203 * 1204 * @since 0.9.1 1205 */ 1206CK_DLL_EXP const char *CK_EXPORT srunner_xml_fname (SRunner * sr); 1207 1208/** 1209 * Set the suite runner to output the result in TAP format to the 1210 * given file. 1211 * 1212 * Note: TAP file setting is an initialize only operation -- it should 1213 * be done immediately after SRunner creation, and the TAP file can't be 1214 * changed after being set. 1215 * 1216 * This setting does not conflict with the other log output types; 1217 * all logging types can occur concurrently if configured. 1218 * 1219 * @param sr suite runner to log results of in TAP format 1220 * @param fname file name to output TAP results to 1221 * 1222 * @since 0.9.12 1223*/ 1224CK_DLL_EXP void CK_EXPORT srunner_set_tap (SRunner * sr, const char *fname); 1225 1226/** 1227 * Checks if the suite runner is assigned a file for TAP output. 1228 * 1229 * @param sr suite runner to check 1230 * 1231 * @return 1 iff the suite runner currently is configured to output 1232 * in TAP format; 0 otherwise 1233 * 1234 * @since 0.9.12 1235 */ 1236CK_DLL_EXP int CK_EXPORT srunner_has_tap (SRunner * sr); 1237 1238/** 1239 * Retrieves the name of the currently assigned file 1240 * for TAP output, if any exists. 1241 * 1242 * @return the name of the TAP file, or NULL if none is configured 1243 * 1244 * @since 0.9.12 1245 */ 1246CK_DLL_EXP const char *CK_EXPORT srunner_tap_fname (SRunner * sr); 1247 1248/** 1249 * Enum describing the current fork usage. 1250 */ 1251enum fork_status 1252{ 1253 CK_FORK_GETENV, /**< look in the environment for CK_FORK */ 1254 CK_FORK, /**< call fork to run tests */ 1255 CK_NOFORK /**< don't call fork */ 1256}; 1257 1258/** 1259 * Retrieve the current fork status for the given suite runner 1260 * 1261 * @param sr suite runner to check fork status of 1262 * 1263 * @since 0.8.0 1264 */ 1265CK_DLL_EXP enum fork_status CK_EXPORT srunner_fork_status (SRunner * sr); 1266 1267/** 1268 * Set the fork status for a given suite runner. 1269 * 1270 * The default fork status is CK_FORK_GETENV, which will look 1271 * for the CK_FORK environment variable, which can be set to 1272 * "yes" or "no". If the environment variable is not present, 1273 * CK_FORK will be used if fork() is available on the system, 1274 * otherwise CK_NOFORK is used. 1275 * 1276 * If set to CK_FORK or CK_NOFORK, the environment variable 1277 * if defined is ignored. 1278 * 1279 * If Check is compiled without support for fork(), attempting 1280 * to set the status to CK_FORK is ignored. 1281 * 1282 * @param sr suite runner to assign the fork status to 1283 * @param fstat fork status to assign 1284 * 1285 * @since 0.8.0 1286 */ 1287CK_DLL_EXP void CK_EXPORT srunner_set_fork_status (SRunner * sr, 1288 enum fork_status fstat); 1289 1290/** 1291 * Invoke fork() during a test and assign the child to the same 1292 * process group that the rest of the test case uses. 1293 * 1294 * One can invoke fork() directly during a test; however doing so 1295 * may not guarantee that any children processes are destroyed once 1296 * the test finishes. Once a test has completed, all processes in 1297 * the process group will be killed; using this wrapper will prevent 1298 * orphan processes. 1299 * 1300 * If Check is compiled without fork() support this call simply 1301 * return -1 and does nothing. 1302 * 1303 * @return On success, the PID of the child process is returned in 1304 * the parent, and 0 is returned in the child. On failure, 1305 * a value of -1 is returned to the parent process and no 1306 * child process is created. 1307 * 1308 * @since 0.9.3 1309 */ 1310#if !defined(_MSC_VER) 1311CK_DLL_EXP pid_t CK_EXPORT check_fork (void); 1312#endif 1313 1314/** 1315 * Wait for the pid and exit. 1316 * 1317 * This is to be used in conjunction with check_fork(). When called, 1318 * will wait for the given process to terminate. If the process 1319 * exited without error, exit(EXIT_SUCCESS) is invoked; otherwise 1320 * exit(EXIT_FAILURE) is invoked. 1321 * 1322 * If Check is compiled without support for fork(), this invokes 1323 * exit(EXIT_FAILURE). 1324 * 1325 * @param pid process to wait for, created by check_fork() 1326 * 1327 * @since 0.9.3 1328 */ 1329#if !defined(_MSC_VER) 1330CK_DLL_EXP void CK_EXPORT 1331check_waitpid_and_exit (pid_t pid) 1332 CK_ATTRIBUTE_NORETURN; 1333#endif 1334 1335#ifdef __cplusplus 1336CK_CPPEND 1337#endif 1338#endif /* CHECK_H */ 1339