src/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  * Largest integral type.  This type should be large enough to hold any
  57  * pointer or integer supported by the compiler.
  58  */
  59 #ifndef LargestIntegralType
  60 #define LargestIntegralType unsigned long long
  61 #endif /* LargestIntegralType */
  62
  63 /* Printf format used to display LargestIntegralType. */
  64 #ifndef LargestIntegralTypePrintfFormat
  65 #ifdef _WIN32
  66 #define LargestIntegralTypePrintfFormat "%I64x"
  67 #else
  68 #define LargestIntegralTypePrintfFormat "%llx"
  69 #endif /* _WIN32 */
  70 #endif /* LargestIntegralTypePrintfFormat */
  71
  72 /* Perform an unsigned cast to LargestIntegralType. */
  73 #define cast_to_largest_integral_type(value) \
  74     ((LargestIntegralType)((unsigned)(size_t)(value)))
  75
  76 /* Smallest integral type capable of holding a pointer. */
  77 #ifndef _UINTPTR_T
  78 #define _UINTPTR_T
  79 #ifdef _WIN32
  80
  81 /* WIN32 is an ILP32 platform */
  82 typedef unsigned long uintptr_t;
  83
  84 /* what about 64-bit windows?
  85  * what's the right preprocessor symbol?
  86 typedef unsigned long long uintptr_t */
  87
  88 #else /* _WIN32 */
  89
  90 /* ILP32 and LP64 platforms */
  91 #ifdef __WORDSIZE
  92 # if __WORDSIZE == 64
  93 typedef unsigned long int uintptr_t;
  94 # else
  95 typedef unsigned int uintptr_t;
  96 # endif /* __WORDSIZE == 64 */
  97 #else /* __WORDSIZE */
  98 typedef unsigned long int uintptr_t;
  99 #endif /* __WORDSIZE */
 100
 101 #endif /* _WIN32 */
 102 #endif /* _UINTPTR_T */
 103
 104 /* Perform an unsigned cast to uintptr_t. */
 105 #define cast_to_pointer_integral_type(value) \
 106     ((uintptr_t)(value))
 107
 108 /* Perform a cast of a pointer to uintmax_t */
 109 #define cast_ptr_to_largest_integral_type(value) \
 110 cast_to_largest_integral_type(cast_to_pointer_integral_type(value))
 111
 112 /* Retrieves a return value for the current function. */
 113 #define mock() _mock(__func__, __FILE__, __LINE__)
 114
 115 /*
 116  * Stores a value to be returned by the specified function later.
 117  * The count parameter returns the number of times the value should be returned
 118  * by mock().  If count is set to -1 the value will always be returned.
 119  */
 120 #define will_return(function, value) \
 121     _will_return(#function, __FILE__, __LINE__, \
 122                  cast_to_largest_integral_type(value), 1)
 123 #define will_return_count(function, value, count) \
 124     _will_return(#function, __FILE__, __LINE__, \
 125                  cast_to_largest_integral_type(value), count)
 126
 127 /*
 128  * Add a custom parameter checking function.  If the event parameter is NULL
 129  * the event structure is allocated internally by this function.  If event
 130  * parameter is provided it must be allocated on the heap and doesn't need to
 131  * be deallocated by the caller.
 132  */
 133 #define expect_check(function, parameter, check_function, check_data) \
 134     _expect_check(#function, #parameter, __FILE__, __LINE__, check_function, \
 135                   cast_to_largest_integral_type(check_data), NULL, 0)
 136
 137 /*
 138  * Add an event to check a parameter, using check_expected(), against a set of
 139  * values. See will_return() for a description of the count parameter.
 140  */
 141 #define expect_in_set(function, parameter, value_array) \
 142     expect_in_set_count(function, parameter, value_array, 1)
 143 #define expect_in_set_count(function, parameter, value_array, count) \
 144     _expect_in_set(#function, #parameter, __FILE__, __LINE__, value_array, \
 145                    sizeof(value_array) / sizeof((value_array)[0]), count)
 146 #define expect_not_in_set(function, parameter, value_array) \
 147     expect_not_in_set_count(function, parameter, value_array, 1)
 148 #define expect_not_in_set_count(function, parameter, value_array, count) \
 149     _expect_not_in_set( \
 150         #function, #parameter, __FILE__, __LINE__, value_array, \
 151         sizeof(value_array) / sizeof((value_array)[0]), count)
 152
 153
 154 /*
 155  * Add an event to check a parameter, using check_expected(), against a
 156  * signed range.  Where range is minimum <= value <= maximum.
 157  * See will_return() for a description of the count parameter.
 158  */
 159 #define expect_in_range(function, parameter, minimum, maximum) \
 160     expect_in_range_count(function, parameter, minimum, maximum, 1)
 161 #define expect_in_range_count(function, parameter, minimum, maximum, count) \
 162     _expect_in_range(#function, #parameter, __FILE__, __LINE__, minimum, \
 163                      maximum, count)
 164
 165 /*
 166  * Add an event to check a parameter, using check_expected(), against a
 167  * signed range.  Where range is value < minimum or value > maximum.
 168  * See will_return() for a description of the count parameter.
 169  */
 170 #define expect_not_in_range(function, parameter, minimum, maximum) \
 171     expect_not_in_range_count(function, parameter, minimum, maximum, 1)
 172 #define expect_not_in_range_count(function, parameter, minimum, maximum, \
 173                                   count) \
 174     _expect_not_in_range(#function, #parameter, __FILE__, __LINE__, \
 175                          minimum, maximum, count)
 176
 177 /*
 178  * Add an event to check whether a parameter, using check_expected(), is or
 179  * isn't a value.  See will_return() for a description of the count parameter.
 180  */
 181 #define expect_value(function, parameter, value) \
 182     expect_value_count(function, parameter, value, 1)
 183 #define expect_value_count(function, parameter, value, count) \
 184     _expect_value(#function, #parameter, __FILE__, __LINE__, \
 185                   cast_to_largest_integral_type(value), count)
 186 #define expect_not_value(function, parameter, value) \
 187     expect_not_value_count(function, parameter, value, 1)
 188 #define expect_not_value_count(function, parameter, value, count) \
 189     _expect_not_value(#function, #parameter, __FILE__, __LINE__, \
 190                       cast_to_largest_integral_type(value), count)
 191
 192 /*
 193  * Add an event to check whether a parameter, using check_expected(),
 194  * is or isn't a string.  See will_return() for a description of the count
 195  * parameter.
 196  */
 197 #define expect_string(function, parameter, string) \
 198     expect_string_count(function, parameter, string, 1)
 199 #define expect_string_count(function, parameter, string, count) \
 200     _expect_string(#function, #parameter, __FILE__, __LINE__, \
 201                    (const char*)(string), count)
 202 #define expect_not_string(function, parameter, string) \
 203     expect_not_string_count(function, parameter, string, 1)
 204 #define expect_not_string_count(function, parameter, string, count) \
 205     _expect_not_string(#function, #parameter, __FILE__, __LINE__, \
 206                        (const char*)(string), count)
 207
 208 /*
 209  * Add an event to check whether a parameter, using check_expected() does or
 210  * doesn't match an area of memory.  See will_return() for a description of
 211  * the count parameter.
 212  */
 213 #define expect_memory(function, parameter, memory, size) \
 214     expect_memory_count(function, parameter, memory, size, 1)
 215 #define expect_memory_count(function, parameter, memory, size, count) \
 216     _expect_memory(#function, #parameter, __FILE__, __LINE__, \
 217                    (const void*)(memory), size, count)
 218 #define expect_not_memory(function, parameter, memory, size) \
 219     expect_not_memory_count(function, parameter, memory, size, 1)
 220 #define expect_not_memory_count(function, parameter, memory, size, count) \
 221     _expect_not_memory(#function, #parameter, __FILE__, __LINE__, \
 222                        (const void*)(memory), size, count)
 223
 224
 225 /*
 226  * Add an event to allow any value for a parameter checked using
 227  * check_expected().  See will_return() for a description of the count
 228  * parameter.
 229  */
 230 #define expect_any(function, parameter) \
 231     expect_any_count(function, parameter, 1)
 232 #define expect_any_count(function, parameter, count) \
 233     _expect_any(#function, #parameter, __FILE__, __LINE__, count)
 234
 235 /*
 236  * Determine whether a function parameter is correct.  This ensures the next
 237  * value queued by one of the expect_*() macros matches the specified variable.
 238  */
 239 #define check_expected(parameter) \
 240     _check_expected(__func__, #parameter, __FILE__, __LINE__, \
 241                     cast_to_largest_integral_type(parameter))
 242
 243 /* Assert that the given expression is true. */
 244 #define assert_true(c) _assert_true(cast_to_largest_integral_type(c), #c, \
 245                                     __FILE__, __LINE__)
 246 /* Assert that the given expression is false. */
 247 #define assert_false(c) _assert_true(!(cast_to_largest_integral_type(c)), #c, \
 248                                      __FILE__, __LINE__)
 249
 250 /* Assert that the given pointer is non-NULL. */
 251 #define assert_non_null(c) _assert_true(cast_ptr_to_largest_integral_type(c), #c, \
 252 __FILE__, __LINE__)
 253 /* Assert that the given pointer is NULL. */
 254 #define assert_null(c) _assert_true(!(cast_ptr_to_largest_integral_type(c)), #c, \
 255 __FILE__, __LINE__)
 256
 257 /* Assert that the two given integers are equal, otherwise fail. */
 258 #define assert_int_equal(a, b) \
 259     _assert_int_equal(cast_to_largest_integral_type(a), \
 260                       cast_to_largest_integral_type(b), \
 261                       __FILE__, __LINE__)
 262 /* Assert that the two given integers are not equal, otherwise fail. */
 263 #define assert_int_not_equal(a, b) \
 264     _assert_int_not_equal(cast_to_largest_integral_type(a), \
 265                           cast_to_largest_integral_type(b), \
 266                           __FILE__, __LINE__)
 267
 268 /* Assert that the two given strings are equal, otherwise fail. */
 269 #define assert_string_equal(a, b) \
 270     _assert_string_equal((const char*)(a), (const char*)(b), __FILE__, \
 271                          __LINE__)
 272 /* Assert that the two given strings are not equal, otherwise fail. */
 273 #define assert_string_not_equal(a, b) \
 274     _assert_string_not_equal((const char*)(a), (const char*)(b), __FILE__, \
 275                              __LINE__)
 276
 277 /* Assert that the two given areas of memory are equal, otherwise fail. */
 278 #define assert_memory_equal(a, b, size) \
 279     _assert_memory_equal((const char*)(a), (const char*)(b), size, __FILE__, \
 280                          __LINE__)
 281 /* Assert that the two given areas of memory are not equal, otherwise fail. */
 282 #define assert_memory_not_equal(a, b, size) \
 283     _assert_memory_not_equal((const char*)(a), (const char*)(b), size, \
 284                              __FILE__, __LINE__)
 285
 286 /* Assert that the specified value is >= minimum and <= maximum. */
 287 #define assert_in_range(value, minimum, maximum) \
 288     _assert_in_range( \
 289         cast_to_largest_integral_type(value), \
 290         cast_to_largest_integral_type(minimum), \
 291         cast_to_largest_integral_type(maximum), __FILE__, __LINE__)
 292
 293 /* Assert that the specified value is < minumum or > maximum */
 294 #define assert_not_in_range(value, minimum, maximum) \
 295     _assert_not_in_range( \
 296         cast_to_largest_integral_type(value), \
 297         cast_to_largest_integral_type(minimum), \
 298         cast_to_largest_integral_type(maximum), __FILE__, __LINE__)
 299
 300 /* Assert that the specified value is within a set. */
 301 #define assert_in_set(value, values, number_of_values) \
 302     _assert_in_set(value, values, number_of_values, __FILE__, __LINE__)
 303 /* Assert that the specified value is not within a set. */
 304 #define assert_not_in_set(value, values, number_of_values) \
 305     _assert_not_in_set(value, values, number_of_values, __FILE__, __LINE__)
 306
 307
 308 /* Forces the test to fail immediately and quit. */
 309 #define fail() _fail(__FILE__, __LINE__)
 310
 311 /* Generic method to kick off testing */
 312 #define run_test(f) _run_test(#f, f, NULL, UNIT_TEST_FUNCTION_TYPE_TEST, NULL)
 313
 314 /* Initializes a UnitTest structure. */
 315 #define unit_test(f) { #f, f, UNIT_TEST_FUNCTION_TYPE_TEST }
 316 #define unit_test_setup(test, setup) \
 317     { #test "_" #setup, setup, UNIT_TEST_FUNCTION_TYPE_SETUP }
 318 #define unit_test_teardown(test, teardown) \
 319     { #test "_" #teardown, teardown, UNIT_TEST_FUNCTION_TYPE_TEARDOWN }
 320
 321 /*
 322  * Initialize an array of UnitTest structures with a setup function for a test
 323  * and a teardown function.  Either setup or teardown can be NULL.
 324  */
 325 #define unit_test_setup_teardown(test, setup, teardown) \
 326     unit_test_setup(test, setup), \
 327     unit_test(test), \
 328     unit_test_teardown(test, teardown)
 329
 330 /*
 331  * Run tests specified by an array of UnitTest structures.  The following
 332  * example illustrates this macro's use with the unit_test macro.
 333  *
 334  * void Test0();
 335  * void Test1();
 336  *
 337  * int main(int argc, char* argv[]) {
 338  *     const UnitTest tests[] = {
 339  *         unit_test(Test0);
 340  *         unit_test(Test1);
 341  *     };
 342  *     return run_tests(tests);
 343  * }
 344  */
 345 #define run_tests(tests) _run_tests(tests, sizeof(tests) / sizeof(tests)[0])
 346
 347 /* Dynamic allocators */
 348 #define test_malloc(size) _test_malloc(size, __FILE__, __LINE__)
 349 #define test_calloc(num, size) _test_calloc(num, size, __FILE__, __LINE__)
 350 #define test_free(ptr) _test_free(ptr, __FILE__, __LINE__)
 351
 352 /* Redirect malloc, calloc and free to the unit test allocators. */
 353 #if UNIT_TESTING
 354 #define malloc test_malloc
 355 #define calloc test_calloc
 356 #define free test_free
 357 #endif /* UNIT_TESTING */
 358
 359 /*
 360  * Ensure mock_assert() is called.  If mock_assert() is called the assert
 361  * expression string is returned.
 362  * For example:
 363  *
 364  * #define assert mock_assert
 365  *
 366  * void showmessage(const char *message) {
 367  *   assert(message);
 368  * }
 369  *
 370  * int main(int argc, const char* argv[]) {
 371  *   expect_assert_failure(show_message(NULL));
 372  *   printf("succeeded\n");
 373  *   return 0;
 374  * }
 375  */
 376 #define expect_assert_failure(function_call) \
 377   { \
 378     const int result = setjmp(global_expect_assert_env); \
 379     global_expecting_assert = 1; \
 380     if (result) { \
 381       print_message("Expected assertion %s occurred\n", \
 382                     global_last_failed_assert); \
 383       global_expecting_assert = 0; \
 384     } else { \
 385       function_call ; \
 386       global_expecting_assert = 0; \
 387       print_error("Expected assert in %s\n", #function_call); \
 388       _fail(__FILE__, __LINE__); \
 389     } \
 390   }
 391
 392 /* Function prototype for setup, test and teardown functions. */
 393 typedef void (*UnitTestFunction)(void **state);
 394
 395 /* Function that determines whether a function parameter value is correct. */
 396 typedef int (*CheckParameterValue)(const LargestIntegralType value,
 397                                    const LargestIntegralType check_value_data);
 398
 399 /* Type of the unit test function. */
 400 typedef enum UnitTestFunctionType {
 401     UNIT_TEST_FUNCTION_TYPE_TEST = 0,
 402     UNIT_TEST_FUNCTION_TYPE_SETUP,
 403     UNIT_TEST_FUNCTION_TYPE_TEARDOWN,
 404 } UnitTestFunctionType;
 405
 406 /*
 407  * Stores a unit test function with its name and type.
 408  * NOTE: Every setup function must be paired with a teardown function.  It's
 409  * possible to specify NULL function pointers.
 410  */
 411 typedef struct UnitTest {
 412     const char* name;
 413     UnitTestFunction function;
 414     UnitTestFunctionType function_type;
 415 } UnitTest;
 416
 417
 418 /* Location within some source code. */
 419 typedef struct SourceLocation {
 420     const char* file;
 421     int line;
 422 } SourceLocation;
 423
 424 /* Event that's called to check a parameter value. */
 425 typedef struct CheckParameterEvent {
 426     SourceLocation location;
 427     const char *parameter_name;
 428     CheckParameterValue check_value;
 429     LargestIntegralType check_value_data;
 430 } CheckParameterEvent;
 431
 432 /* Used by expect_assert_failure() and mock_assert(). */
 433 extern int global_expecting_assert;
 434 extern jmp_buf global_expect_assert_env;
 435 extern const char * global_last_failed_assert;
 436
 437 /* Retrieves a value for the given function, as set by "will_return". */
 438 LargestIntegralType _mock(const char * const function, const char* const file,
 439                           const int line);
 440
 441 void _expect_check(
 442     const char* const function, const char* const parameter,
 443     const char* const file, const int line,
 444     const CheckParameterValue check_function,
 445     const LargestIntegralType check_data, CheckParameterEvent * const event,
 446     const int count);
 447
 448 void _expect_in_set(
 449     const char* const function, const char* const parameter,
 450     const char* const file, const int line, const LargestIntegralType values[],
 451     const size_t number_of_values, const int count);
 452 void _expect_not_in_set(
 453     const char* const function, const char* const parameter,
 454     const char* const file, const int line, const LargestIntegralType values[],
 455     const size_t number_of_values, const int count);
 456
 457 void _expect_in_range(
 458     const char* const function, const char* const parameter,
 459     const char* const file, const int line,
 460     const LargestIntegralType minimum,
 461     const LargestIntegralType maximum, const int count);
 462 void _expect_not_in_range(
 463     const char* const function, const char* const parameter,
 464     const char* const file, const int line,
 465     const LargestIntegralType minimum,
 466     const LargestIntegralType maximum, const int count);
 467
 468 void _expect_value(
 469     const char* const function, const char* const parameter,
 470     const char* const file, const int line, const LargestIntegralType value,
 471     const int count);
 472 void _expect_not_value(
 473     const char* const function, const char* const parameter,
 474     const char* const file, const int line, const LargestIntegralType value,
 475     const int count);
 476
 477 void _expect_string(
 478     const char* const function, const char* const parameter,
 479     const char* const file, const int line, const char* string,
 480     const int count);
 481 void _expect_not_string(
 482     const char* const function, const char* const parameter,
 483     const char* const file, const int line, const char* string,
 484     const int count);
 485
 486 void _expect_memory(
 487     const char* const function, const char* const parameter,
 488     const char* const file, const int line, const void* const memory,
 489     const size_t size, const int count);
 490 void _expect_not_memory(
 491     const char* const function, const char* const parameter,
 492     const char* const file, const int line, const void* const memory,
 493     const size_t size, const int count);
 494
 495 void _expect_any(
 496     const char* const function, const char* const parameter,
 497     const char* const file, const int line, const int count);
 498
 499 void _check_expected(
 500     const char * const function_name, const char * const parameter_name,
 501     const char* file, const int line, const LargestIntegralType value);
 502
 503 /*
 504  * Can be used to replace assert in tested code so that in conjuction with
 505  * check_assert() it's possible to determine whether an assert condition has
 506  * failed without stopping a test.
 507  */
 508 void mock_assert(const int result, const char* const expression,
 509                  const char * const file, const int line);
 510
 511 void _will_return(const char * const function_name, const char * const file,
 512                   const int line, const LargestIntegralType value,
 513                   const int count);
 514 void _assert_true(const LargestIntegralType result,
 515                   const char* const expression,
 516                   const char * const file, const int line);
 517 void _assert_int_equal(
 518     const LargestIntegralType a, const LargestIntegralType b,
 519     const char * const file, const int line);
 520 void _assert_int_not_equal(
 521     const LargestIntegralType a, const LargestIntegralType b,
 522     const char * const file, const int line);
 523 void _assert_string_equal(const char * const a, const char * const b,
 524                           const char * const file, const int line);
 525 void _assert_string_not_equal(const char * const a, const char * const b,
 526                               const char *file, const int line);
 527 void _assert_memory_equal(const void * const a, const void * const b,
 528                           const size_t size, const char* const file,
 529                           const int line);
 530 void _assert_memory_not_equal(const void * const a, const void * const b,
 531                               const size_t size, const char* const file,
 532                               const int line);
 533 void _assert_in_range(
 534     const LargestIntegralType value, const LargestIntegralType minimum,
 535     const LargestIntegralType maximum, const char* const file, const int line);
 536 void _assert_not_in_range(
 537     const LargestIntegralType value, const LargestIntegralType minimum,
 538     const LargestIntegralType maximum, const char* const file, const int line);
 539 void _assert_in_set(
 540     const LargestIntegralType value, const LargestIntegralType values[],
 541     const size_t number_of_values, const char* const file, const int line);
 542 void _assert_not_in_set(
 543     const LargestIntegralType value, const LargestIntegralType values[],
 544     const size_t number_of_values, const char* const file, const int line);
 545
 546 void* _test_malloc(const size_t size, const char* file, const int line);
 547 void* _test_calloc(const size_t number_of_elements, const size_t size,
 548                    const char* file, const int line);
 549 void _test_free(void* const ptr, const char* file, const int line);
 550
 551 void _fail(const char * const file, const int line);
 552 int _run_test(
 553     const char * const function_name, const UnitTestFunction Function,
 554     void ** const volatile state, const UnitTestFunctionType function_type,
 555     const void* const heap_check_point);
 556 int _run_tests(const UnitTest * const tests, const size_t number_of_tests);
 557
 558 /* Standard output and error print methods. */
 559 void print_message(const char* const format, ...) PRINTF_ATTRIBUTE(1, 2);
 560 void print_error(const char* const format, ...) PRINTF_ATTRIBUTE(1, 2);
 561 void vprint_message(const char* const format, va_list args) PRINTF_ATTRIBUTE(1, 0);
 562 void vprint_error(const char* const format, va_list args) PRINTF_ATTRIBUTE(1, 0);
 563
 564 #endif /* CMOCKA_H_ */