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