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