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., 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 (@CHECK_MAJOR_VERSION@)
  79 #define CHECK_MINOR_VERSION (@CHECK_MINOR_VERSION@)
  80 #define CHECK_MICRO_VERSION (@CHECK_MICRO_VERSION@)
  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 functins 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 functins 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  * 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@
 432 CK_DLL_EXP void CK_EXPORT
 433 _ck_assert_failed (const char *file, int line, const char *expr, ...)
 434     CK_ATTRIBUTE_NORETURN;
 435 #else
 436 CK_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 */
 797 CK_DLL_EXP void CK_EXPORT _mark_point (const char *file, int line);
 798
 799 /**
 800  * Enum describing the possible results of a test
 801  */
 802 enum 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  */
 814 enum 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  */
 834 typedef struct SRunner SRunner;
 835
 836 /**
 837  * Opaque type for a test failure
 838  */
 839 typedef struct TestResult TestResult;
 840
 841 /**
 842  * Enum representing the types of contexts for a test
 843  */
 844 enum 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  */
 864 CK_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  */
 878 CK_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  */
 887 CK_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  */
 897 CK_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  */
 908 CK_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  */
 919 CK_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  */
 935 CK_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  */
 948 CK_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  */
 961 CK_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  */
 979 CK_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  */
1010 CK_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  */
1048 CK_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  */
1064 CK_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  */
1075 CK_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  */
1094 CK_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 */
1114 CK_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  */
1125 CK_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 */
1144 CK_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  */
1156 CK_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  */
1166 CK_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 */
1184 CK_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  */
1196 CK_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  */
1206 CK_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 */
1224 CK_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  */
1236 CK_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  */
1246 CK_DLL_EXP const char *CK_EXPORT srunner_tap_fname (SRunner * sr);
1247
1248 /**
1249  * Enum describing the current fork usage.
1250  */
1251 enum 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  */
1265 CK_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  */
1287 CK_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)
1311 CK_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)
1330 CK_DLL_EXP void CK_EXPORT
1331 check_waitpid_and_exit (pid_t pid)
1332     CK_ATTRIBUTE_NORETURN;
1333 #endif
1334
1335 #ifdef __cplusplus
1336 CK_CPPEND
1337 #endif
1338 #endif /* CHECK_H */