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