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