libs/gst/check/libcheck/check.h.in

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