include/cmocka.h

   1 /*
   2  * Copyright 2008 Google Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 #ifndef CMOCKA_H_
  17 #define CMOCKA_H_
  18
  19 #ifdef _WIN32
  20 # ifdef _MSC_VER
  21
  22 # ifndef inline
  23 #define inline __inline
  24 # endif /* inline */
  25
  26 #  if _MSC_VER < 1500
  27 #   ifdef __cplusplus
  28 extern "C" {
  29 #   endif   /* __cplusplus */
  30 int __stdcall IsDebuggerPresent();
  31 #   ifdef __cplusplus
  32 } /* extern "C" */
  33 #   endif   /* __cplusplus */
  34 #  endif  /* _MSC_VER < 1500 */
  35 # endif /* _MSC_VER */
  36 #endif  /* _WIN32 */
  37
  38 /*
  39  * These headers or their equivalents should be included prior to including
  40  * this header file.
  41  *
  42  * #include <stdarg.h>
  43  * #include <stddef.h>
  44  * #include <setjmp.h>
  45  *
  46  * This allows test applications to use custom definitions of C standard
  47  * library functions and types.
  48  */
  49
  50 /* For those who are used to __func__ from gcc. */
  51 #ifndef __func__
  52 #define __func__ __FUNCTION__
  53 #endif
  54
  55 /* GCC have printf type attribute check.  */
  56 #ifdef __GNUC__
  57 #define CMOCKA_PRINTF_ATTRIBUTE(a,b) \
  58     __attribute__ ((__format__ (__printf__, a, b)))
  59 #else
  60 #define CMOCKA_PRINTF_ATTRIBUTE(a,b)
  61 #endif /* __GNUC__ */
  62
  63 /**
  64  * @defgroup cmocka The CMocka API
  65  *
  66  * TODO Describe cmocka.
  67  *
  68  * @{
  69  */
  70
  71 /*
  72  * Largest integral type.  This type should be large enough to hold any
  73  * pointer or integer supported by the compiler.
  74  */
  75 #ifndef LargestIntegralType
  76 #define LargestIntegralType unsigned long long
  77 #endif /* LargestIntegralType */
  78
  79 /* Printf format used to display LargestIntegralType. */
  80 #ifndef LargestIntegralTypePrintfFormat
  81 #ifdef _WIN32
  82 #define LargestIntegralTypePrintfFormat "0x%I64x"
  83 #else
  84 #define LargestIntegralTypePrintfFormat "%#llx"
  85 #endif /* _WIN32 */
  86 #endif /* LargestIntegralTypePrintfFormat */
  87
  88 /* Perform an unsigned cast to LargestIntegralType. */
  89 #define cast_to_largest_integral_type(value) \
  90     ((LargestIntegralType)((size_t)(value)))
  91
  92 /* Smallest integral type capable of holding a pointer. */
  93 #if !defined(_UINTPTR_T) && !defined(_UINTPTR_T_DEFINED)
  94 # if defined(_WIN32)
  95     /* WIN32 is an ILP32 platform */
  96     typedef unsigned int uintptr_t;
  97 # elif defined(_WIN64)
  98     typedef unsigned long int uintptr_t
  99 # else /* _WIN32 */
 100
 101 /* ILP32 and LP64 platforms */
 102 #  ifdef __WORDSIZE /* glibc */
 103 #   if __WORDSIZE == 64
 104       typedef unsigned long int uintptr_t;
 105 #   else
 106       typedef unsigned int uintptr_t;
 107 #   endif /* __WORDSIZE == 64 */
 108 #  else /* __WORDSIZE */
 109 #   if defined(_LP64) || defined(_I32LPx)
 110       typedef unsigned long int uintptr_t;
 111 #   else
 112       typedef unsigned int uintptr_t;
 113 #   endif
 114 #  endif /* __WORDSIZE */
 115 # endif /* _WIN32 */
 116
 117 # define _UINTPTR_T
 118 # define _UINTPTR_T_DEFINED
 119 #endif /* !defined(_UINTPTR_T) || !defined(_UINTPTR_T_DEFINED) */
 120
 121 /* Perform an unsigned cast to uintptr_t. */
 122 #define cast_to_pointer_integral_type(value) \
 123     ((uintptr_t)(value))
 124
 125 /* Perform a cast of a pointer to uintmax_t */
 126 #define cast_ptr_to_largest_integral_type(value) \
 127 cast_to_largest_integral_type(cast_to_pointer_integral_type(value))
 128
 129 /**
 130  * @defgroup cmocka_mock Mock Objects
 131  * @ingroup cmocka
 132  *
 133  * Mock objects mock objects are simulated objects that mimic the behavior of
 134  * real objects. Instead of calling the real objects, the tested object calls a
 135  * mock object that merely asserts that the correct methods were called, with
 136  * the expected parameters, in the correct order.
 137  *
 138  * <ul>
 139  * <li><strong>will_return(function, value)</strong> - The will_return() macro
 140  * pushes a value onto a stack of mock values. This macro is intended to be
 141  * used by the unit test itself, while programming the behaviour of the mocked
 142  * object.</li>
 143  *
 144  * <li><strong>mock()</strong> - the mock macro pops a value from a stack of
 145  * test values. The user of the mock() macro is the mocked object that uses it
 146  * to learn how it should behave.</li>
 147  * </ul>
 148  *
 149  * Because the will_return() and mock() are intended to be used in pairs, the
 150  * cmocka library would fail the test if there are more values pushed onto the
 151  * stack using will_return() than consumed with mock() and vice-versa.
 152  *
 153  * The following unit test stub illustrates how would a unit test instruct the
 154  * mock object to return a particular value:
 155  *
 156  * @code
 157  * will_return(chef_cook, "hotdog");
 158  * will_return(chef_cook, 0);
 159  * @endcode
 160  *
 161  * Now the mock object can check if the parameter it received is the parameter
 162  * which is expected by the test driver. This can be done the following way:
 163  *
 164  * @code
 165  * int chef_cook(const char *order, char **dish_out)
 166  * {
 167  *     check_expected(order);
 168  * }
 169  * @endcode
 170  *
 171  * For a complete example please at a look
 172  * <a href="http://git.cryptomilk.org/projects/cmocka.git/tree/example/chef_wrap/waiter_test_wrap.c">here</a>.
 173  *
 174  * @{
 175  */
 176
 177 #ifdef DOXYGEN
 178 /**
 179  * @brief Retrieve a return value of the current function.
 180  *
 181  * @return The value which was stored to return by this function.
 182  *
 183  * @see will_return()
 184  */
 185 void *mock(void);
 186 #else
 187 #define mock() _mock(__func__, __FILE__, __LINE__)
 188 #endif
 189
 190 #ifdef DOXYGEN
 191 /**
 192  * @brief Retrieve a typed return value of the current function.
 193  *
 194  * The value would be casted to type internally to avoid having the
 195  * caller to do the cast manually.
 196  *
 197  * @param[in]  #type  The expected type of the return value
 198  *
 199  * @return The value which was stored to return by this function.
 200  *
 201  * @code
 202  * int param;
 203  *
 204  * param = mock_type(int);
 205  * @endcode
 206  *
 207  * @see will_return()
 208  * @see mock()
 209  * @see mock_ptr_type()
 210  */
 211 void *mock_type(#type);
 212 #else
 213 #define mock_type(type) ((type) mock())
 214 #endif
 215
 216 #ifdef DOXYGEN
 217 /**
 218  * @brief Retrieve a typed return value of the current function.
 219  *
 220  * The value would be casted to type internally to avoid having the
 221  * caller to do the cast manually but also casted to uintptr_t to make
 222  * sure the result has a valid size to be used as a pointer.
 223  *
 224  * @param[in]  #type  The expected type of the return value
 225  *
 226  * @return The value which was stored to return by this function.
 227  *
 228  * @code
 229  * char *param;
 230  *
 231  * param = mock_ptr_type(char *);
 232  * @endcode
 233  *
 234  * @see will_return()
 235  * @see mock()
 236  * @see mock_type()
 237  */
 238 void *mock_ptr_type(#type);
 239 #else
 240 #define mock_ptr_type(type) ((type) (uintptr_t) mock())
 241 #endif
 242
 243
 244 #ifdef DOXYGEN
 245 /**
 246  * @brief Store a value to be returned by mock() later.
 247  *
 248  * @param[in]  #function  The function which should return the given value.
 249  *
 250  * @param[in]  value The value to be returned by mock().
 251  *
 252  * @code
 253  * int return_integer(void)
 254  * {
 255  *      return (int)mock();
 256  * }
 257  *
 258  * static void test_integer_return(void **state)
 259  * {
 260  *      will_return(return_integer, 42);
 261  *
 262  *      assert_int_equal(my_function_calling_return_integer(), 42);
 263  * }
 264  * @endcode
 265  *
 266  * @see mock()
 267  * @see will_return_count()
 268  */
 269 void will_return(#function, void *value);
 270 #else
 271 #define will_return(function, value) \
 272     _will_return(#function, __FILE__, __LINE__, \
 273                  cast_to_largest_integral_type(value), 1)
 274 #endif
 275
 276 #ifdef DOXYGEN
 277 /**
 278  * @brief Store a value to be returned by mock() later.
 279  *
 280  * @param[in]  #function  The function which should return the given value.
 281  *
 282  * @param[in]  value The value to be returned by mock().
 283  *
 284  * @param[in]  count The parameter returns the number of times the value should
 285  *                   be returned by mock(). If count is set to -1 the value will
 286  *                   always be returned.
 287  *
 288  * @see mock()
 289  */
 290 void will_return_count(#function, void *value, int count);
 291 #else
 292 #define will_return_count(function, value, count) \
 293     _will_return(#function, __FILE__, __LINE__, \
 294                  cast_to_largest_integral_type(value), count)
 295 #endif
 296
 297 #ifdef DOXYGEN
 298 /**
 299  * @brief Store a value that will be always returned by mock().
 300  *
 301  * @param[in]  #function  The function which should return the given value.
 302  *
 303  * @param[in]  value The value to be returned by mock().
 304  *
 305  * This is equivalent to:
 306  * @code
 307  * will_return_count(function, value, -1);
 308  * @endcode
 309  *
 310  * @see will_return_count()
 311  * @see mock()
 312  */
 313 void will_return_always(#function, void *value);
 314 #else
 315 #define will_return_always(function, value) \
 316     will_return_count(function, (value), -1)
 317 #endif
 318
 319 /** @} */
 320
 321 /**
 322  * @defgroup cmocka_param Checking Parameters
 323  * @ingroup cmocka
 324  *
 325  * Functionality to store expected values for mock function parameters.
 326  *
 327  * In addition to storing the return values of mock functions, cmocka provides
 328  * functionality to store expected values for mock function parameters using
 329  * the expect_*() functions provided. A mock function parameter can then be
 330  * validated using the check_expected() macro.
 331  *
 332  * Successive calls to expect_*() macros for a parameter queues values to check
 333  * the specified parameter. check_expected() checks a function parameter
 334  * against the next value queued using expect_*(), if the parameter check fails
 335  * a test failure is signalled. In addition if check_expected() is called and
 336  * no more parameter values are queued a test failure occurs.
 337  *
 338  * The following test stub illustrates how to do this. First is the the function
 339  * we call in the test driver:
 340  *
 341  * @code
 342  * static void test_driver(void **state)
 343  * {
 344  *     expect_string(chef_cook, order, "hotdog");
 345  * }
 346  * @endcode
 347  *
 348  * Now the chef_cook function can check if the parameter we got passed is the
 349  * parameter which is expected by the test driver. This can be done the
 350  * following way:
 351  *
 352  * @code
 353  * int chef_cook(const char *order, char **dish_out)
 354  * {
 355  *     check_expected(order);
 356  * }
 357  * @endcode
 358  *
 359  * For a complete example please at a look at
 360  * <a href="http://git.cryptomilk.org/projects/cmocka.git/tree/example/chef_wrap/waiter_test_wrap.c">here</a>
 361  *
 362  * @{
 363  */
 364
 365 /*
 366  * Add a custom parameter checking function.  If the event parameter is NULL
 367  * the event structure is allocated internally by this function.  If event
 368  * parameter is provided it must be allocated on the heap and doesn't need to
 369  * be deallocated by the caller.
 370  */
 371 #ifdef DOXYGEN
 372 /**
 373  * @brief Add a custom parameter checking function.
 374  *
 375  * If the event parameter is NULL the event structure is allocated internally
 376  * by this function. If the parameter is provided it must be allocated on the
 377  * heap and doesn't need to be deallocated by the caller.
 378  *
 379  * @param[in]  #function  The function to add a custom parameter checking
 380  *                        function for.
 381  *
 382  * @param[in]  #parameter The parameters passed to the function.
 383  *
 384  * @param[in]  #check_function  The check function to call.
 385  *
 386  * @param[in]  check_data       The data to pass to the check function.
 387  */
 388 void expect_check(#function, #parameter, #check_function, const void *check_data);
 389 #else
 390 #define expect_check(function, parameter, check_function, check_data) \
 391     _expect_check(#function, #parameter, __FILE__, __LINE__, check_function, \
 392                   cast_to_largest_integral_type(check_data), NULL, 1)
 393 #endif
 394
 395 #ifdef DOXYGEN
 396 /**
 397  * @brief Add an event to check if the parameter value is part of the provided
 398  *        array.
 399  *
 400  * The event is triggered by calling check_expected() in the mocked function.
 401  *
 402  * @param[in]  #function  The function to add the check for.
 403  *
 404  * @param[in]  #parameter The name of the parameter passed to the function.
 405  *
 406  * @param[in]  value_array[] The array to check for the value.
 407  *
 408  * @see check_expected().
 409  */
 410 void expect_in_set(#function, #parameter, uintmax_t value_array[]);
 411 #else
 412 #define expect_in_set(function, parameter, value_array) \
 413     expect_in_set_count(function, parameter, value_array, 1)
 414 #endif
 415
 416 #ifdef DOXYGEN
 417 /**
 418  * @brief Add an event to check if the parameter value is part of the provided
 419  *        array.
 420  *
 421  * The event is triggered by calling check_expected() in the mocked function.
 422  *
 423  * @param[in]  #function  The function to add the check for.
 424  *
 425  * @param[in]  #parameter The name of the parameter passed to the function.
 426  *
 427  * @param[in]  value_array[] The array to check for the value.
 428  *
 429  * @param[in]  count  The count parameter returns the number of times the value
 430  *                    should be returned by check_expected(). If count is set
 431  *                    to -1 the value will always be returned.
 432  *
 433  * @see check_expected().
 434  */
 435 void expect_in_set_count(#function, #parameter, uintmax_t value_array[], size_t count);
 436 #else
 437 #define expect_in_set_count(function, parameter, value_array, count) \
 438     _expect_in_set(#function, #parameter, __FILE__, __LINE__, value_array, \
 439                    sizeof(value_array) / sizeof((value_array)[0]), count)
 440 #endif
 441
 442 #ifdef DOXYGEN
 443 /**
 444  * @brief Add an event to check if the parameter value is not part of the
 445  *        provided array.
 446  *
 447  * The event is triggered by calling check_expected() in the mocked function.
 448  *
 449  * @param[in]  #function  The function to add the check for.
 450  *
 451  * @param[in]  #parameter The name of the parameter passed to the function.
 452  *
 453  * @param[in]  value_array[] The array to check for the value.
 454  *
 455  * @see check_expected().
 456  */
 457 void expect_not_in_set(#function, #parameter, uintmax_t value_array[]);
 458 #else
 459 #define expect_not_in_set(function, parameter, value_array) \
 460     expect_not_in_set_count(function, parameter, value_array, 1)
 461 #endif
 462
 463 #ifdef DOXYGEN
 464 /**
 465  * @brief Add an event to check if the parameter value is not part of the
 466  *        provided array.
 467  *
 468  * The event is triggered by calling check_expected() in the mocked function.
 469  *
 470  * @param[in]  #function  The function to add the check for.
 471  *
 472  * @param[in]  #parameter The name of the parameter passed to the function.
 473  *
 474  * @param[in]  value_array[] The array to check for the value.
 475  *
 476  * @param[in]  count  The count parameter returns the number of times the value
 477  *                    should be returned by check_expected(). If count is set
 478  *                    to -1 the value will always be returned.
 479  *
 480  * @see check_expected().
 481  */
 482 void expect_not_in_set_count(#function, #parameter, uintmax_t value_array[], size_t count);
 483 #else
 484 #define expect_not_in_set_count(function, parameter, value_array, count) \
 485     _expect_not_in_set( \
 486         #function, #parameter, __FILE__, __LINE__, value_array, \
 487         sizeof(value_array) / sizeof((value_array)[0]), count)
 488 #endif
 489
 490
 491 #ifdef DOXYGEN
 492 /**
 493  * @brief Add an event to check a parameter is inside a numerical range.
 494  * The check would succeed if minimum <= value <= maximum.
 495  *
 496  * The event is triggered by calling check_expected() in the mocked function.
 497  *
 498  * @param[in]  #function  The function to add the check for.
 499  *
 500  * @param[in]  #parameter The name of the parameter passed to the function.
 501  *
 502  * @param[in]  minimum  The lower boundary of the interval to check against.
 503  *
 504  * @param[in]  maximum  The upper boundary of the interval to check against.
 505  *
 506  * @see check_expected().
 507  */
 508 void expect_in_range(#function, #parameter, uintmax_t minimum, uintmax_t maximum);
 509 #else
 510 #define expect_in_range(function, parameter, minimum, maximum) \
 511     expect_in_range_count(function, parameter, minimum, maximum, 1)
 512 #endif
 513
 514 #ifdef DOXYGEN
 515 /**
 516  * @brief Add an event to repeatedly check a parameter is inside a
 517  * numerical range. The check would succeed if minimum <= value <= maximum.
 518  *
 519  * The event is triggered by calling check_expected() in the mocked function.
 520  *
 521  * @param[in]  #function  The function to add the check for.
 522  *
 523  * @param[in]  #parameter The name of the parameter passed to the function.
 524  *
 525  * @param[in]  minimum  The lower boundary of the interval to check against.
 526  *
 527  * @param[in]  maximum  The upper boundary of the interval to check against.
 528  *
 529  * @param[in]  count  The count parameter returns the number of times the value
 530  *                    should be returned by check_expected(). If count is set
 531  *                    to -1 the value will always be returned.
 532  *
 533  * @see check_expected().
 534  */
 535 void expect_in_range_count(#function, #parameter, uintmax_t minimum, uintmax_t maximum, size_t count);
 536 #else
 537 #define expect_in_range_count(function, parameter, minimum, maximum, count) \
 538     _expect_in_range(#function, #parameter, __FILE__, __LINE__, minimum, \
 539                      maximum, count)
 540 #endif
 541
 542 #ifdef DOXYGEN
 543 /**
 544  * @brief Add an event to check a parameter is outside a numerical range.
 545  * The check would succeed if minimum > value > maximum.
 546  *
 547  * The event is triggered by calling check_expected() in the mocked function.
 548  *
 549  * @param[in]  #function  The function to add the check for.
 550  *
 551  * @param[in]  #parameter The name of the parameter passed to the function.
 552  *
 553  * @param[in]  minimum  The lower boundary of the interval to check against.
 554  *
 555  * @param[in]  maximum  The upper boundary of the interval to check against.
 556  *
 557  * @see check_expected().
 558  */
 559 void expect_not_in_range(#function, #parameter, uintmax_t minimum, uintmax_t maximum);
 560 #else
 561 #define expect_not_in_range(function, parameter, minimum, maximum) \
 562     expect_not_in_range_count(function, parameter, minimum, maximum, 1)
 563 #endif
 564
 565 #ifdef DOXYGEN
 566 /**
 567  * @brief Add an event to repeatedly check a parameter is outside a
 568  * numerical range. The check would succeed if minimum > value > maximum.
 569  *
 570  * The event is triggered by calling check_expected() in the mocked function.
 571  *
 572  * @param[in]  #function  The function to add the check for.
 573  *
 574  * @param[in]  #parameter The name of the parameter passed to the function.
 575  *
 576  * @param[in]  minimum  The lower boundary of the interval to check against.
 577  *
 578  * @param[in]  maximum  The upper boundary of the interval to check against.
 579  *
 580  * @param[in]  count  The count parameter returns the number of times the value
 581  *                    should be returned by check_expected(). If count is set
 582  *                    to -1 the value will always be returned.
 583  *
 584  * @see check_expected().
 585  */
 586 void expect_not_in_range_count(#function, #parameter, uintmax_t minimum, uintmax_t maximum, size_t count);
 587 #else
 588 #define expect_not_in_range_count(function, parameter, minimum, maximum, \
 589                                   count) \
 590     _expect_not_in_range(#function, #parameter, __FILE__, __LINE__, \
 591                          minimum, maximum, count)
 592 #endif
 593
 594 #ifdef DOXYGEN
 595 /**
 596  * @brief Add an event to check if a parameter is the given value.
 597  *
 598  * The event is triggered by calling check_expected() in the mocked function.
 599  *
 600  * @param[in]  #function  The function to add the check for.
 601  *
 602  * @param[in]  #parameter The name of the parameter passed to the function.
 603  *
 604  * @param[in]  value  The value to check.
 605  *
 606  * @see check_expected().
 607  */
 608 void expect_value(#function, #parameter, uintmax_t value);
 609 #else
 610 #define expect_value(function, parameter, value) \
 611     expect_value_count(function, parameter, value, 1)
 612 #endif
 613
 614 #ifdef DOXYGEN
 615 /**
 616  * @brief Add an event to repeatedly check if a parameter is the given value.
 617  *
 618  * The event is triggered by calling check_expected() in the mocked function.
 619  *
 620  * @param[in]  #function  The function to add the check for.
 621  *
 622  * @param[in]  #parameter The name of the parameter passed to the function.
 623  *
 624  * @param[in]  value  The value to check.
 625  *
 626  * @param[in]  count  The count parameter returns the number of times the value
 627  *                    should be returned by check_expected(). If count is set
 628  *                    to -1 the value will always be returned.
 629  *
 630  * @see check_expected().
 631  */
 632 void expect_value_count(#function, #parameter, uintmax_t value, size_t count);
 633 #else
 634 #define expect_value_count(function, parameter, value, count) \
 635     _expect_value(#function, #parameter, __FILE__, __LINE__, \
 636                   cast_to_largest_integral_type(value), count)
 637 #endif
 638
 639 #ifdef DOXYGEN
 640 /**
 641  * @brief Add an event to check if a parameter isn't the given value.
 642  *
 643  * The event is triggered by calling check_expected() in the mocked function.
 644  *
 645  * @param[in]  #function  The function to add the check for.
 646  *
 647  * @param[in]  #parameter The name of the parameter passed to the function.
 648  *
 649  * @param[in]  value  The value to check.
 650  *
 651  * @see check_expected().
 652  */
 653 void expect_not_value(#function, #parameter, uintmax_t value);
 654 #else
 655 #define expect_not_value(function, parameter, value) \
 656     expect_not_value_count(function, parameter, value, 1)
 657 #endif
 658
 659 #ifdef DOXYGEN
 660 /**
 661  * @brief Add an event to repeatedly check if a parameter isn't the given value.
 662  *
 663  * The event is triggered by calling check_expected() in the mocked function.
 664  *
 665  * @param[in]  #function  The function to add the check for.
 666  *
 667  * @param[in]  #parameter The name of the parameter passed to the function.
 668  *
 669  * @param[in]  value  The value to check.
 670  *
 671  * @param[in]  count  The count parameter returns the number of times the value
 672  *                    should be returned by check_expected(). If count is set
 673  *                    to -1 the value will always be returned.
 674  *
 675  * @see check_expected().
 676  */
 677 void expect_not_value_count(#function, #parameter, uintmax_t value, size_t count);
 678 #else
 679 #define expect_not_value_count(function, parameter, value, count) \
 680     _expect_not_value(#function, #parameter, __FILE__, __LINE__, \
 681                       cast_to_largest_integral_type(value), count)
 682 #endif
 683
 684 #ifdef DOXYGEN
 685 /**
 686  * @brief Add an event to check if the parameter value is equal to the
 687  *        provided string.
 688  *
 689  * The event is triggered by calling check_expected() in the mocked function.
 690  *
 691  * @param[in]  #function  The function to add the check for.
 692  *
 693  * @param[in]  #parameter The name of the parameter passed to the function.
 694  *
 695  * @param[in]  string   The string value to compare.
 696  *
 697  * @see check_expected().
 698  */
 699 void expect_string(#function, #parameter, const char *string);
 700 #else
 701 #define expect_string(function, parameter, string) \
 702     expect_string_count(function, parameter, string, 1)
 703 #endif
 704
 705 #ifdef DOXYGEN
 706 /**
 707  * @brief Add an event to check if the parameter value is equal to the
 708  *        provided string.
 709  *
 710  * The event is triggered by calling check_expected() in the mocked function.
 711  *
 712  * @param[in]  #function  The function to add the check for.
 713  *
 714  * @param[in]  #parameter The name of the parameter passed to the function.
 715  *
 716  * @param[in]  string   The string value to compare.
 717  *
 718  * @param[in]  count  The count parameter returns the number of times the value
 719  *                    should be returned by check_expected(). If count is set
 720  *                    to -1 the value will always be returned.
 721  *
 722  * @see check_expected().
 723  */
 724 void expect_string_count(#function, #parameter, const char *string, size_t count);
 725 #else
 726 #define expect_string_count(function, parameter, string, count) \
 727     _expect_string(#function, #parameter, __FILE__, __LINE__, \
 728                    (const char*)(string), count)
 729 #endif
 730
 731 #ifdef DOXYGEN
 732 /**
 733  * @brief Add an event to check if the parameter value isn't equal to the
 734  *        provided string.
 735  *
 736  * The event is triggered by calling check_expected() in the mocked function.
 737  *
 738  * @param[in]  #function  The function to add the check for.
 739  *
 740  * @param[in]  #parameter The name of the parameter passed to the function.
 741  *
 742  * @param[in]  string   The string value to compare.
 743  *
 744  * @see check_expected().
 745  */
 746 void expect_not_string(#function, #parameter, const char *string);
 747 #else
 748 #define expect_not_string(function, parameter, string) \
 749     expect_not_string_count(function, parameter, string, 1)
 750 #endif
 751
 752 #ifdef DOXYGEN
 753 /**
 754  * @brief Add an event to check if the parameter value isn't equal to the
 755  *        provided string.
 756  *
 757  * The event is triggered by calling check_expected() in the mocked function.
 758  *
 759  * @param[in]  #function  The function to add the check for.
 760  *
 761  * @param[in]  #parameter The name of the parameter passed to the function.
 762  *
 763  * @param[in]  string   The string value to compare.
 764  *
 765  * @param[in]  count  The count parameter returns the number of times the value
 766  *                    should be returned by check_expected(). If count is set
 767  *                    to -1 the value will always be returned.
 768  *
 769  * @see check_expected().
 770  */
 771 void expect_not_string_count(#function, #parameter, const char *string, size_t count);
 772 #else
 773 #define expect_not_string_count(function, parameter, string, count) \
 774     _expect_not_string(#function, #parameter, __FILE__, __LINE__, \
 775                        (const char*)(string), count)
 776 #endif
 777
 778 #ifdef DOXYGEN
 779 /**
 780  * @brief Add an event to check if the parameter does match an area of memory.
 781  *
 782  * The event is triggered by calling check_expected() in the mocked function.
 783  *
 784  * @param[in]  #function  The function to add the check for.
 785  *
 786  * @param[in]  #parameter The name of the parameter passed to the function.
 787  *
 788  * @param[in]  memory  The memory to compare.
 789  *
 790  * @param[in]  size  The size of the memory to compare.
 791  *
 792  * @see check_expected().
 793  */
 794 void expect_memory(#function, #parameter, void *memory, size_t size);
 795 #else
 796 #define expect_memory(function, parameter, memory, size) \
 797     expect_memory_count(function, parameter, memory, size, 1)
 798 #endif
 799
 800 #ifdef DOXYGEN
 801 /**
 802  * @brief Add an event to repeatedly check if the parameter does match an area
 803  *        of memory.
 804  *
 805  * The event is triggered by calling check_expected() in the mocked function.
 806  *
 807  * @param[in]  #function  The function to add the check for.
 808  *
 809  * @param[in]  #parameter The name of the parameter passed to the function.
 810  *
 811  * @param[in]  memory  The memory to compare.
 812  *
 813  * @param[in]  size  The size of the memory to compare.
 814  *
 815  * @param[in]  count  The count parameter returns the number of times the value
 816  *                    should be returned by check_expected(). If count is set
 817  *                    to -1 the value will always be returned.
 818  *
 819  * @see check_expected().
 820  */
 821 void expect_memory_count(#function, #parameter, void *memory, size_t size, size_t count);
 822 #else
 823 #define expect_memory_count(function, parameter, memory, size, count) \
 824     _expect_memory(#function, #parameter, __FILE__, __LINE__, \
 825                    (const void*)(memory), size, count)
 826 #endif
 827
 828 #ifdef DOXYGEN
 829 /**
 830  * @brief Add an event to check if the parameter doesn't match an area of
 831  *        memory.
 832  *
 833  * The event is triggered by calling check_expected() in the mocked function.
 834  *
 835  * @param[in]  #function  The function to add the check for.
 836  *
 837  * @param[in]  #parameter The name of the parameter passed to the function.
 838  *
 839  * @param[in]  memory  The memory to compare.
 840  *
 841  * @param[in]  size  The size of the memory to compare.
 842  *
 843  * @see check_expected().
 844  */
 845 void expect_not_memory(#function, #parameter, void *memory, size_t size);
 846 #else
 847 #define expect_not_memory(function, parameter, memory, size) \
 848     expect_not_memory_count(function, parameter, memory, size, 1)
 849 #endif
 850
 851 #ifdef DOXYGEN
 852 /**
 853  * @brief Add an event to repeatedly check if the parameter doesn't match an
 854  *        area of memory.
 855  *
 856  * The event is triggered by calling check_expected() in the mocked function.
 857  *
 858  * @param[in]  #function  The function to add the check for.
 859  *
 860  * @param[in]  #parameter The name of the parameter passed to the function.
 861  *
 862  * @param[in]  memory  The memory to compare.
 863  *
 864  * @param[in]  size  The size of the memory to compare.
 865  *
 866  * @param[in]  count  The count parameter returns the number of times the value
 867  *                    should be returned by check_expected(). If count is set
 868  *                    to -1 the value will always be returned.
 869  *
 870  * @see check_expected().
 871  */
 872 void expect_not_memory_count(#function, #parameter, void *memory, size_t size, size_t count);
 873 #else
 874 #define expect_not_memory_count(function, parameter, memory, size, count) \
 875     _expect_not_memory(#function, #parameter, __FILE__, __LINE__, \
 876                        (const void*)(memory), size, count)
 877 #endif
 878
 879
 880 #ifdef DOXYGEN
 881 /**
 882  * @brief Add an event to check if a parameter (of any value) has been passed.
 883  *
 884  * The event is triggered by calling check_expected() in the mocked function.
 885  *
 886  * @param[in]  #function  The function to add the check for.
 887  *
 888  * @param[in]  #parameter The name of the parameter passed to the function.
 889  *
 890  * @see check_expected().
 891  */
 892 void expect_any(#function, #parameter);
 893 #else
 894 #define expect_any(function, parameter) \
 895     expect_any_count(function, parameter, 1)
 896 #endif
 897
 898 #ifdef DOXYGEN
 899 /**
 900  * @brief Add an event to repeatedly check if a parameter (of any value) has
 901  *        been passed.
 902  *
 903  * The event is triggered by calling check_expected() in the mocked function.
 904  *
 905  * @param[in]  #function  The function to add the check for.
 906  *
 907  * @param[in]  #parameter The name of the parameter passed to the function.
 908  *
 909  * @param[in]  count  The count parameter returns the number of times the value
 910  *                    should be returned by check_expected(). If count is set
 911  *                    to -1 the value will always be returned.
 912  *
 913  * @see check_expected().
 914  */
 915 void expect_any_count(#function, #parameter, size_t count);
 916 #else
 917 #define expect_any_count(function, parameter, count) \
 918     _expect_any(#function, #parameter, __FILE__, __LINE__, count)
 919 #endif
 920
 921 #ifdef DOXYGEN
 922 /**
 923  * @brief Determine whether a function parameter is correct.
 924  *
 925  * This ensures the next value queued by one of the expect_*() macros matches
 926  * the specified variable.
 927  *
 928  * This function needs to be called in the mock object.
 929  *
 930  * @param[in]  #parameter  The parameter to check.
 931  */
 932 void check_expected(#parameter);
 933 #else
 934 #define check_expected(parameter) \
 935     _check_expected(__func__, #parameter, __FILE__, __LINE__, \
 936                     cast_to_largest_integral_type(parameter))
 937 #endif
 938
 939 /** @} */
 940
 941 /**
 942  * @defgroup cmocka_asserts Assert Macros
 943  * @ingroup cmocka
 944  *
 945  * This is a set of useful assert macros like the standard C libary's
 946  * assert(3) macro.
 947  *
 948  * On an assertion failure a cmocka assert macro will write the failure to the
 949  * standard error stream and signal a test failure. Due to limitations of the C
 950  * language the general C standard library assert() and cmocka's assert_true()
 951  * and assert_false() macros can only display the expression that caused the
 952  * assert failure. cmocka's type specific assert macros, assert_{type}_equal()
 953  * and assert_{type}_not_equal(), display the data that caused the assertion
 954  * failure which increases data visibility aiding debugging of failing test
 955  * cases.
 956  *
 957  * @{
 958  */
 959
 960 #ifdef DOXYGEN
 961 /**
 962  * @brief Assert that the given expression is true.
 963  *
 964  * The function prints an error message to standard error and terminates the
 965  * test by calling fail() if expression is false (i.e., compares equal to
 966  * zero).
 967  *
 968  * @param[in]  expression  The expression to evaluate.
 969  *
 970  * @see assert_int_equal()
 971  * @see assert_string_equal()
 972  */
 973 void assert_true(scalar expression);
 974 #else
 975 #define assert_true(c) _assert_true(cast_to_largest_integral_type(c), #c, \
 976                                     __FILE__, __LINE__)
 977 #endif
 978
 979 #ifdef DOXYGEN
 980 /**
 981  * @brief Assert that the given expression is false.
 982  *
 983  * The function prints an error message to standard error and terminates the
 984  * test by calling fail() if expression is true.
 985  *
 986  * @param[in]  expression  The expression to evaluate.
 987  *
 988  * @see assert_int_equal()
 989  * @see assert_string_equal()
 990  */
 991 void assert_false(scalar expression);
 992 #else
 993 #define assert_false(c) _assert_true(!(cast_to_largest_integral_type(c)), #c, \
 994                                      __FILE__, __LINE__)
 995 #endif
 996
 997 #ifdef DOXYGEN
 998 /**
 999  * @brief Assert if the return_code is smaller than 0.
1000  *
1001  * The function prints an error message to standard error and terminates the
1002  * test by calling fail() if the return code is smaller than 0. If the function
1003  * you check sets an errno if it fails you can pass it to the function and
1004  * it will be printed as part of the error message.
1005  *
1006  * @param[in]  rc       The return code to evaluate.
1007  *
1008  * @param[in]  error    Pass errno here or 0.
1009  */
1010 void assert_return_code(int rc, int error);
1011 #else
1012 #define assert_return_code(rc, error) \
1013     _assert_return_code(cast_to_largest_integral_type(rc), \
1014                         sizeof(rc), \
1015                         cast_to_largest_integral_type(error), \
1016                         #rc, __FILE__, __LINE__)
1017 #endif
1018
1019 #ifdef DOXYGEN
1020 /**
1021  * @brief Assert that the given pointer is non-NULL.
1022  *
1023  * The function prints an error message to standard error and terminates the
1024  * test by calling fail() if the pointer is non-NULL.
1025  *
1026  * @param[in]  pointer  The pointer to evaluate.
1027  *
1028  * @see assert_null()
1029  */
1030 void assert_non_null(void *pointer);
1031 #else
1032 #define assert_non_null(c) _assert_true(cast_ptr_to_largest_integral_type(c), #c, \
1033                                         __FILE__, __LINE__)
1034 #endif
1035
1036 #ifdef DOXYGEN
1037 /**
1038  * @brief Assert that the given pointer is NULL.
1039  *
1040  * The function prints an error message to standard error and terminates the
1041  * test by calling fail() if the pointer is non-NULL.
1042  *
1043  * @param[in]  pointer  The pointer to evaluate.
1044  *
1045  * @see assert_non_null()
1046  */
1047 void assert_null(void *pointer);
1048 #else
1049 #define assert_null(c) _assert_true(!(cast_ptr_to_largest_integral_type(c)), #c, \
1050 __FILE__, __LINE__)
1051 #endif
1052
1053 #ifdef DOXYGEN
1054 /**
1055  * @brief Assert that the two given integers are equal.
1056  *
1057  * The function prints an error message to standard error and terminates the
1058  * test by calling fail() if the integers are not equal.
1059  *
1060  * @param[in]  a  The first integer to compare.
1061  *
1062  * @param[in]  b  The integer to compare against the first one.
1063  */
1064 void assert_int_equal(int a, int b);
1065 #else
1066 #define assert_int_equal(a, b) \
1067     _assert_int_equal(cast_to_largest_integral_type(a), \
1068                       cast_to_largest_integral_type(b), \
1069                       __FILE__, __LINE__)
1070 #endif
1071
1072 #ifdef DOXYGEN
1073 /**
1074  * @brief Assert that the two given integers are not equal.
1075  *
1076  * The function prints an error message to standard error and terminates the
1077  * test by calling fail() if the integers are equal.
1078  *
1079  * @param[in]  a  The first integer to compare.
1080  *
1081  * @param[in]  b  The integer to compare against the first one.
1082  *
1083  * @see assert_int_equal()
1084  */
1085 void assert_int_not_equal(int a, int b);
1086 #else
1087 #define assert_int_not_equal(a, b) \
1088     _assert_int_not_equal(cast_to_largest_integral_type(a), \
1089                           cast_to_largest_integral_type(b), \
1090                           __FILE__, __LINE__)
1091 #endif
1092
1093 #ifdef DOXYGEN
1094 /**
1095  * @brief Assert that the two given strings are equal.
1096  *
1097  * The function prints an error message to standard error and terminates the
1098  * test by calling fail() if the strings are not equal.
1099  *
1100  * @param[in]  a  The string to check.
1101  *
1102  * @param[in]  b  The other string to compare.
1103  */
1104 void assert_string_equal(const char *a, const char *b);
1105 #else
1106 #define assert_string_equal(a, b) \
1107     _assert_string_equal((const char*)(a), (const char*)(b), __FILE__, \
1108                          __LINE__)
1109 #endif
1110
1111 #ifdef DOXYGEN
1112 /**
1113  * @brief Assert that the two given strings are not equal.
1114  *
1115  * The function prints an error message to standard error and terminates the
1116  * test by calling fail() if the strings are equal.
1117  *
1118  * @param[in]  a  The string to check.
1119  *
1120  * @param[in]  b  The other string to compare.
1121  */
1122 void assert_string_not_equal(const char *a, const char *b);
1123 #else
1124 #define assert_string_not_equal(a, b) \
1125     _assert_string_not_equal((const char*)(a), (const char*)(b), __FILE__, \
1126                              __LINE__)
1127 #endif
1128
1129 #ifdef DOXYGEN
1130 /**
1131  * @brief Assert that the two given areas of memory are equal, otherwise fail.
1132  *
1133  * The function prints an error message to standard error and terminates the
1134  * test by calling fail() if the memory is not equal.
1135  *
1136  * @param[in]  a  The first memory area to compare
1137  *                (interpreted as unsigned char).
1138  *
1139  * @param[in]  b  The second memory area to compare
1140  *                (interpreted as unsigned char).
1141  *
1142  * @param[in]  size  The first n bytes of the memory areas to compare.
1143  */
1144 void assert_memory_equal(const void *a, const void *b, size_t size);
1145 #else
1146 #define assert_memory_equal(a, b, size) \
1147     _assert_memory_equal((const void*)(a), (const void*)(b), size, __FILE__, \
1148                          __LINE__)
1149 #endif
1150
1151 #ifdef DOXYGEN
1152 /**
1153  * @brief Assert that the two given areas of memory are not equal.
1154  *
1155  * The function prints an error message to standard error and terminates the
1156  * test by calling fail() if the memory is equal.
1157  *
1158  * @param[in]  a  The first memory area to compare
1159  *                (interpreted as unsigned char).
1160  *
1161  * @param[in]  b  The second memory area to compare
1162  *                (interpreted as unsigned char).
1163  *
1164  * @param[in]  size  The first n bytes of the memory areas to compare.
1165  */
1166 void assert_memory_not_equal(const void *a, const void *b, size_t size);
1167 #else
1168 #define assert_memory_not_equal(a, b, size) \
1169     _assert_memory_not_equal((const void*)(a), (const void*)(b), size, \
1170                              __FILE__, __LINE__)
1171 #endif
1172
1173 #ifdef DOXYGEN
1174 /**
1175  * @brief Assert that the specified value is bigger than the minimum and
1176  * smaller than the maximum.
1177  *
1178  * The function prints an error message to standard error and terminates the
1179  * test by calling fail() if value is not in range.
1180  *
1181  * @param[in]  value  The value to check.
1182  *
1183  * @param[in]  minimum  The minimum value allowed.
1184  *
1185  * @param[in]  maximum  The maximum value allowed.
1186  */
1187 void assert_in_range(uintmax_t value, uintmax_t minimum, uintmax_t maximum);
1188 #else
1189 #define assert_in_range(value, minimum, maximum) \
1190     _assert_in_range( \
1191         cast_to_largest_integral_type(value), \
1192         cast_to_largest_integral_type(minimum), \
1193         cast_to_largest_integral_type(maximum), __FILE__, __LINE__)
1194 #endif
1195
1196 #ifdef DOXYGEN
1197 /**
1198  * @brief Assert that the specified value is smaller than the minimum and
1199  * bigger than the maximum.
1200  *
1201  * The function prints an error message to standard error and terminates the
1202  * test by calling fail() if value is in range.
1203  *
1204  * @param[in]  value  The value to check.
1205  *
1206  * @param[in]  minimum  The minimum value to compare.
1207  *
1208  * @param[in]  maximum  The maximum value to compare.
1209  */
1210 void assert_not_in_range(uintmax_t value, uintmax_t minimum, uintmax_t maximum);
1211 #else
1212 #define assert_not_in_range(value, minimum, maximum) \
1213     _assert_not_in_range( \
1214         cast_to_largest_integral_type(value), \
1215         cast_to_largest_integral_type(minimum), \
1216         cast_to_largest_integral_type(maximum), __FILE__, __LINE__)
1217 #endif
1218
1219 #ifdef DOXYGEN
1220 /**
1221  * @brief Assert that the specified value is within a set.
1222  *
1223  * The function prints an error message to standard error and terminates the
1224  * test by calling fail() if value is not within a set.
1225  *
1226  * @param[in]  value  The value to look up
1227  *
1228  * @param[in]  values[]  The array to check for the value.
1229  *
1230  * @param[in]  count  The size of the values array.
1231  */
1232 void assert_in_set(uintmax_t value, uintmax_t values[], size_t count);
1233 #else
1234 #define assert_in_set(value, values, number_of_values) \
1235     _assert_in_set(value, values, number_of_values, __FILE__, __LINE__)
1236 #endif
1237
1238 #ifdef DOXYGEN
1239 /**
1240  * @brief Assert that the specified value is not within a set.
1241  *
1242  * The function prints an error message to standard error and terminates the
1243  * test by calling fail() if value is within a set.
1244  *
1245  * @param[in]  value  The value to look up
1246  *
1247  * @param[in]  values[]  The array to check for the value.
1248  *
1249  * @param[in]  count  The size of the values array.
1250  */
1251 void assert_not_in_set(uintmax_t value, uintmax_t values[], size_t count);
1252 #else
1253 #define assert_not_in_set(value, values, number_of_values) \
1254     _assert_not_in_set(value, values, number_of_values, __FILE__, __LINE__)
1255 #endif
1256
1257 /** @} */
1258
1259 /**
1260  * @defgroup cmocka_exec Running Tests
1261  * @ingroup cmocka
1262  *
1263  * This is the way tests are executed with CMocka.
1264  *
1265  * The following example illustrates this macro's use with the unit_test macro.
1266  *
1267  * @code
1268  * void Test0(void **state);
1269  * void Test1(void **state);
1270  *
1271  * int main(void)
1272  * {
1273  *     const UnitTest tests[] = {
1274  *         unit_test(Test0),
1275  *         unit_test(Test1),
1276  *     };
1277  *
1278  *     return run_tests(tests);
1279  * }
1280  * @endcode
1281  *
1282  * @{
1283  */
1284
1285 #ifdef DOXYGEN
1286 /**
1287  * @brief Forces the test to fail immediately and quit.
1288  */
1289 void fail(void);
1290 #else
1291 #define fail() _fail(__FILE__, __LINE__)
1292 #endif
1293
1294 #ifdef DOXYGEN
1295 /**
1296  * @brief Forces the test to fail immediately and quit, printing the reason.
1297  */
1298 void fail_msg(const char *msg, ...);
1299 #else
1300 #define fail_msg(msg, ...) do { \
1301     print_error("ERROR: " msg "\n", ##__VA_ARGS__); \
1302     fail(); \
1303 } while (0)
1304 #endif
1305
1306 #ifdef DOXYGEN
1307 /**
1308  * @brief Generic method to run a single test.
1309  *
1310  * @param[in]  #function The function to test.
1311  *
1312  * @return 0 on success, 1 if an error occured.
1313  *
1314  * @code
1315  * // A test case that does nothing and succeeds.
1316  * void null_test_success(void **state) {
1317  * }
1318  *
1319  * int main(void) {
1320  *      return run_test(null_test_success);
1321  * }
1322  * @endcode
1323  */
1324 int run_test(#function);
1325 #else
1326 #define run_test(f) _run_test(#f, f, NULL, UNIT_TEST_FUNCTION_TYPE_TEST, NULL)
1327 #endif
1328
1329 static inline void _unit_test_dummy(void **state) {
1330     (void)state;
1331 }
1332
1333 /** Initializes a UnitTest structure. */
1334 #define unit_test(f) { #f, f, UNIT_TEST_FUNCTION_TYPE_TEST }
1335
1336 #define _unit_test_setup(test, setup) \
1337     { #test "_" #setup, setup, UNIT_TEST_FUNCTION_TYPE_SETUP }
1338
1339 /** Initializes a UnitTest structure with a setup function. */
1340 #define unit_test_setup(test, setup) \
1341     _unit_test_setup(test, setup), \
1342     unit_test(test), \
1343     _unit_test_teardown(test, _unit_test_dummy)
1344
1345 #define _unit_test_teardown(test, teardown) \
1346     { #test "_" #teardown, teardown, UNIT_TEST_FUNCTION_TYPE_TEARDOWN }
1347
1348 /** Initializes a UnitTest structure with a teardown function. */
1349 #define unit_test_teardown(test, teardown) \
1350     _unit_test_setup(test, _unit_test_dummy), \
1351     unit_test(test), \
1352     _unit_test_teardown(test, teardown)
1353
1354 #define group_test_setup(setup) \
1355     { "group_" #setup, setup, UNIT_TEST_FUNCTION_TYPE_GROUP_SETUP }
1356
1357 #define group_test_teardown(teardown) \
1358     { "group_" #teardown, teardown, UNIT_TEST_FUNCTION_TYPE_GROUP_TEARDOWN }
1359
1360 /**
1361  * Initialize an array of UnitTest structures with a setup function for a test
1362  * and a teardown function.  Either setup or teardown can be NULL.
1363  */
1364 #define unit_test_setup_teardown(test, setup, teardown) \
1365     _unit_test_setup(test, setup), \
1366     unit_test(test), \
1367     _unit_test_teardown(test, teardown)
1368
1369 #ifdef DOXYGEN
1370 /**
1371  * @brief Run tests specified by an array of UnitTest structures.
1372  *
1373  * @param[in]  tests[] The array of unit tests to execute.
1374  *
1375  * @return 0 on success, 1 if an error occured.
1376  *
1377  * @code
1378  * static void setup(void **state) {
1379  *      int *answer = malloc(sizeof(int));
1380  *      assert_non_null(answer);
1381  *
1382  *      *answer = 42;
1383  *
1384  *      *state = answer;
1385  * }
1386  *
1387  * static void teardown(void **state) {
1388  *      free(*state);
1389  * }
1390  *
1391  * static void null_test_success(void **state) {
1392  *     (void) state;
1393  * }
1394  *
1395  * static void int_test_success(void **state) {
1396  *      int *answer = *state;
1397  *      assert_int_equal(*answer, 42);
1398  * }
1399  *
1400  * int main(void) {
1401  *     const UnitTest tests[] = {
1402  *         unit_test(null_test_success),
1403  *         unit_test_setup_teardown(int_test_success, setup, teardown),
1404  *     };
1405  *
1406  *     return run_tests(tests);
1407  * }
1408  * @endcode
1409  *
1410  * @see unit_test
1411  * @see unit_test_setup
1412  * @see unit_test_teardown
1413  * @see unit_test_setup_teardown
1414  */
1415 int run_tests(const UnitTest tests[]);
1416 #else
1417 #define run_tests(tests) _run_tests(tests, sizeof(tests) / sizeof(tests)[0])
1418 #endif
1419
1420 #define run_group_tests(tests) _run_group_tests(tests, sizeof(tests) / sizeof(tests)[0])
1421
1422 /** @} */
1423
1424 /**
1425  * @defgroup cmocka_alloc Dynamic Memory Allocation
1426  * @ingroup cmocka
1427  *
1428  * Memory leaks, buffer overflows and underflows can be checked using cmocka.
1429  *
1430  * To test for memory leaks, buffer overflows and underflows a module being
1431  * tested by cmocka should replace calls to malloc(), calloc() and free() to
1432  * test_malloc(), test_calloc() and test_free() respectively. Each time a block
1433  * is deallocated using test_free() it is checked for corruption, if a corrupt
1434  * block is found a test failure is signalled. All blocks allocated using the
1435  * test_*() allocation functions are tracked by the cmocka library. When a test
1436  * completes if any allocated blocks (memory leaks) remain they are reported
1437  * and a test failure is signalled.
1438  *
1439  * For simplicity cmocka currently executes all tests in one process. Therefore
1440  * all test cases in a test application share a single address space which
1441  * means memory corruption from a single test case could potentially cause the
1442  * test application to exit prematurely.
1443  *
1444  * @{
1445  */
1446
1447 #ifdef DOXYGEN
1448 /**
1449  * @brief Test function overriding malloc.
1450  *
1451  * @param[in]  size  The bytes which should be allocated.
1452  *
1453  * @return A pointer to the allocated memory or NULL on error.
1454  *
1455  * @code
1456  * #ifdef UNIT_TESTING
1457  * extern void* _test_malloc(const size_t size, const char* file, const int line);
1458  *
1459  * #define malloc(size) _test_malloc(size, __FILE__, __LINE__)
1460  * #endif
1461  *
1462  * void leak_memory() {
1463  *     int * const temporary = (int*)malloc(sizeof(int));
1464  *     *temporary = 0;
1465  * }
1466  * @endcode
1467  *
1468  * @see malloc(3)
1469  */
1470 void *test_malloc(size_t size);
1471 #else
1472 #define test_malloc(size) _test_malloc(size, __FILE__, __LINE__)
1473 #endif
1474
1475 #ifdef DOXYGEN
1476 /**
1477  * @brief Test function overriding calloc.
1478  *
1479  * The memory is set to zero.
1480  *
1481  * @param[in]  nmemb  The number of elements for an array to be allocated.
1482  *
1483  * @param[in]  size   The size in bytes of each array element to allocate.
1484  *
1485  * @return A pointer to the allocated memory, NULL on error.
1486  *
1487  * @see calloc(3)
1488  */
1489 void *test_calloc(size_t nmemb, size_t size);
1490 #else
1491 #define test_calloc(num, size) _test_calloc(num, size, __FILE__, __LINE__)
1492 #endif
1493
1494 #ifdef DOXYGEN
1495 /**
1496  * @brief Test function overriding free(3).
1497  *
1498  * @param[in]  ptr  The pointer to the memory space to free.
1499  *
1500  * @see free(3).
1501  */
1502 void test_free(void *ptr);
1503 #else
1504 #define test_free(ptr) _test_free(ptr, __FILE__, __LINE__)
1505 #endif
1506
1507 /* Redirect malloc, calloc and free to the unit test allocators. */
1508 #ifdef UNIT_TESTING
1509 #define malloc test_malloc
1510 #define calloc test_calloc
1511 #define free test_free
1512 #endif /* UNIT_TESTING */
1513
1514 /** @} */
1515
1516
1517 /**
1518  * @defgroup cmocka_mock_assert Standard Assertions
1519  * @ingroup cmocka
1520  *
1521  * How to handle assert(3) of the standard C library.
1522  *
1523  * Runtime assert macros like the standard C library's assert() should be
1524  * redefined in modules being tested to use cmocka's mock_assert() function.
1525  * Normally mock_assert() signals a test failure. If a function is called using
1526  * the expect_assert_failure() macro, any calls to mock_assert() within the
1527  * function will result in the execution of the test. If no calls to
1528  * mock_assert() occur during the function called via expect_assert_failure() a
1529  * test failure is signalled.
1530  *
1531  * @{
1532  */
1533
1534 /**
1535  * @brief Function to replace assert(3) in tested code.
1536  *
1537  * In conjuction with check_assert() it's possible to determine whether an
1538  * assert condition has failed without stopping a test.
1539  *
1540  * @param[in]  result  The expression to assert.
1541  *
1542  * @param[in]  expression  The expression as string.
1543  *
1544  * @param[in]  file  The file mock_assert() is called.
1545  *
1546  * @param[in]  line  The line mock_assert() is called.
1547  *
1548  * @code
1549  * #ifdef UNIT_TESTING
1550  * extern void mock_assert(const int result, const char* const expression,
1551  *                         const char * const file, const int line);
1552  *
1553  * #undef assert
1554  * #define assert(expression) \
1555  *     mock_assert((int)(expression), #expression, __FILE__, __LINE__);
1556  * #endif
1557  *
1558  * void increment_value(int * const value) {
1559  *     assert(value);
1560  *     (*value) ++;
1561  * }
1562  * @endcode
1563  *
1564  * @see assert(3)
1565  * @see expect_assert_failure
1566  */
1567 void mock_assert(const int result, const char* const expression,
1568                  const char * const file, const int line);
1569
1570 #ifdef DOXYGEN
1571 /**
1572  * @brief Ensure that mock_assert() is called.
1573  *
1574  * If mock_assert() is called the assert expression string is returned.
1575  *
1576  * @param[in]  fn_call  The function will will call mock_assert().
1577  *
1578  * @code
1579  * #define assert mock_assert
1580  *
1581  * void showmessage(const char *message) {
1582  *   assert(message);
1583  * }
1584  *
1585  * int main(int argc, const char* argv[]) {
1586  *   expect_assert_failure(show_message(NULL));
1587  *   printf("succeeded\n");
1588  *   return 0;
1589  * }
1590  * @endcode
1591  *
1592  */
1593 void expect_assert_failure(function fn_call);
1594 #else
1595 #define expect_assert_failure(function_call) \
1596   { \
1597     const int result = setjmp(global_expect_assert_env); \
1598     global_expecting_assert = 1; \
1599     if (result) { \
1600       print_message("Expected assertion %s occurred\n", \
1601                     global_last_failed_assert); \
1602       global_expecting_assert = 0; \
1603     } else { \
1604       function_call ; \
1605       global_expecting_assert = 0; \
1606       print_error("Expected assert in %s\n", #function_call); \
1607       _fail(__FILE__, __LINE__); \
1608     } \
1609   }
1610 #endif
1611
1612 /** @} */
1613
1614 /* Function prototype for setup, test and teardown functions. */
1615 typedef void (*UnitTestFunction)(void **state);
1616
1617 /* Function that determines whether a function parameter value is correct. */
1618 typedef int (*CheckParameterValue)(const LargestIntegralType value,
1619                                    const LargestIntegralType check_value_data);
1620
1621 /* Type of the unit test function. */
1622 typedef enum UnitTestFunctionType {
1623     UNIT_TEST_FUNCTION_TYPE_TEST = 0,
1624     UNIT_TEST_FUNCTION_TYPE_SETUP,
1625     UNIT_TEST_FUNCTION_TYPE_TEARDOWN,
1626     UNIT_TEST_FUNCTION_TYPE_GROUP_SETUP,
1627     UNIT_TEST_FUNCTION_TYPE_GROUP_TEARDOWN,
1628 } UnitTestFunctionType;
1629
1630 /*
1631  * Stores a unit test function with its name and type.
1632  * NOTE: Every setup function must be paired with a teardown function.  It's
1633  * possible to specify NULL function pointers.
1634  */
1635 typedef struct UnitTest {
1636     const char* name;
1637     UnitTestFunction function;
1638     UnitTestFunctionType function_type;
1639 } UnitTest;
1640
1641 typedef struct GroupTest {
1642     UnitTestFunction setup;
1643     UnitTestFunction teardown;
1644     const UnitTest *tests;
1645     const size_t number_of_tests;
1646 } GroupTest;
1647
1648 /* Location within some source code. */
1649 typedef struct SourceLocation {
1650     const char* file;
1651     int line;
1652 } SourceLocation;
1653
1654 /* Event that's called to check a parameter value. */
1655 typedef struct CheckParameterEvent {
1656     SourceLocation location;
1657     const char *parameter_name;
1658     CheckParameterValue check_value;
1659     LargestIntegralType check_value_data;
1660 } CheckParameterEvent;
1661
1662 /* Used by expect_assert_failure() and mock_assert(). */
1663 extern int global_expecting_assert;
1664 extern jmp_buf global_expect_assert_env;
1665 extern const char * global_last_failed_assert;
1666
1667 /* Retrieves a value for the given function, as set by "will_return". */
1668 LargestIntegralType _mock(const char * const function, const char* const file,
1669                           const int line);
1670
1671 void _expect_check(
1672     const char* const function, const char* const parameter,
1673     const char* const file, const int line,
1674     const CheckParameterValue check_function,
1675     const LargestIntegralType check_data, CheckParameterEvent * const event,
1676     const int count);
1677
1678 void _expect_in_set(
1679     const char* const function, const char* const parameter,
1680     const char* const file, const int line, const LargestIntegralType values[],
1681     const size_t number_of_values, const int count);
1682 void _expect_not_in_set(
1683     const char* const function, const char* const parameter,
1684     const char* const file, const int line, const LargestIntegralType values[],
1685     const size_t number_of_values, const int count);
1686
1687 void _expect_in_range(
1688     const char* const function, const char* const parameter,
1689     const char* const file, const int line,
1690     const LargestIntegralType minimum,
1691     const LargestIntegralType maximum, const int count);
1692 void _expect_not_in_range(
1693     const char* const function, const char* const parameter,
1694     const char* const file, const int line,
1695     const LargestIntegralType minimum,
1696     const LargestIntegralType maximum, const int count);
1697
1698 void _expect_value(
1699     const char* const function, const char* const parameter,
1700     const char* const file, const int line, const LargestIntegralType value,
1701     const int count);
1702 void _expect_not_value(
1703     const char* const function, const char* const parameter,
1704     const char* const file, const int line, const LargestIntegralType value,
1705     const int count);
1706
1707 void _expect_string(
1708     const char* const function, const char* const parameter,
1709     const char* const file, const int line, const char* string,
1710     const int count);
1711 void _expect_not_string(
1712     const char* const function, const char* const parameter,
1713     const char* const file, const int line, const char* string,
1714     const int count);
1715
1716 void _expect_memory(
1717     const char* const function, const char* const parameter,
1718     const char* const file, const int line, const void* const memory,
1719     const size_t size, const int count);
1720 void _expect_not_memory(
1721     const char* const function, const char* const parameter,
1722     const char* const file, const int line, const void* const memory,
1723     const size_t size, const int count);
1724
1725 void _expect_any(
1726     const char* const function, const char* const parameter,
1727     const char* const file, const int line, const int count);
1728
1729 void _check_expected(
1730     const char * const function_name, const char * const parameter_name,
1731     const char* file, const int line, const LargestIntegralType value);
1732
1733 void _will_return(const char * const function_name, const char * const file,
1734                   const int line, const LargestIntegralType value,
1735                   const int count);
1736 void _assert_true(const LargestIntegralType result,
1737                   const char* const expression,
1738                   const char * const file, const int line);
1739 void _assert_return_code(const LargestIntegralType result,
1740                          size_t rlen,
1741                          const LargestIntegralType error,
1742                          const char * const expression,
1743                          const char * const file,
1744                          const int line);
1745 void _assert_int_equal(
1746     const LargestIntegralType a, const LargestIntegralType b,
1747     const char * const file, const int line);
1748 void _assert_int_not_equal(
1749     const LargestIntegralType a, const LargestIntegralType b,
1750     const char * const file, const int line);
1751 void _assert_string_equal(const char * const a, const char * const b,
1752                           const char * const file, const int line);
1753 void _assert_string_not_equal(const char * const a, const char * const b,
1754                               const char *file, const int line);
1755 void _assert_memory_equal(const void * const a, const void * const b,
1756                           const size_t size, const char* const file,
1757                           const int line);
1758 void _assert_memory_not_equal(const void * const a, const void * const b,
1759                               const size_t size, const char* const file,
1760                               const int line);
1761 void _assert_in_range(
1762     const LargestIntegralType value, const LargestIntegralType minimum,
1763     const LargestIntegralType maximum, const char* const file, const int line);
1764 void _assert_not_in_range(
1765     const LargestIntegralType value, const LargestIntegralType minimum,
1766     const LargestIntegralType maximum, const char* const file, const int line);
1767 void _assert_in_set(
1768     const LargestIntegralType value, const LargestIntegralType values[],
1769     const size_t number_of_values, const char* const file, const int line);
1770 void _assert_not_in_set(
1771     const LargestIntegralType value, const LargestIntegralType values[],
1772     const size_t number_of_values, const char* const file, const int line);
1773
1774 void* _test_malloc(const size_t size, const char* file, const int line);
1775 void* _test_calloc(const size_t number_of_elements, const size_t size,
1776                    const char* file, const int line);
1777 void _test_free(void* const ptr, const char* file, const int line);
1778
1779 void _fail(const char * const file, const int line);
1780 int _run_test(
1781     const char * const function_name, const UnitTestFunction Function,
1782     void ** const volatile state, const UnitTestFunctionType function_type,
1783     const void* const heap_check_point);
1784 int _run_tests(const UnitTest * const tests, const size_t number_of_tests);
1785 int _run_group_tests(const UnitTest * const tests,
1786                      const size_t number_of_tests);
1787
1788 /* Standard output and error print methods. */
1789 void print_message(const char* const format, ...) CMOCKA_PRINTF_ATTRIBUTE(1, 2);
1790 void print_error(const char* const format, ...) CMOCKA_PRINTF_ATTRIBUTE(1, 2);
1791 void vprint_message(const char* const format, va_list args) CMOCKA_PRINTF_ATTRIBUTE(1, 0);
1792 void vprint_error(const char* const format, va_list args) CMOCKA_PRINTF_ATTRIBUTE(1, 0);
1793
1794 /** @} */
1795
1796 #endif /* CMOCKA_H_ */