2 * Copyright 2008 Google Inc.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #define __func__ __FUNCTION__
25 #define inline __inline
31 # endif /* __cplusplus */
32 int __stdcall
IsDebuggerPresent();
35 # endif /* __cplusplus */
36 # endif /* _MSC_VER < 1500 */
37 # endif /* _MSC_VER */
41 * @defgroup cmocka The CMocka API
43 * These headers or their equivalents should be included prior to including
51 * This allows test applications to use custom definitions of C standard
52 * library functions and types.
57 /* If __WORDSIZE is not set, try to figure it out and default to 32 bit. */
59 # if defined(__x86_64__) && !defined(__ILP32__)
60 # define __WORDSIZE 64
62 # define __WORDSIZE 32
68 * Largest integral type. This type should be large enough to hold any
69 * pointer or integer supported by the compiler.
71 typedef uintmax_t LargestIntegralType
;
73 #ifndef LargestIntegralType
74 # if __WORDSIZE == 64 && !defined(_WIN64)
75 # define LargestIntegralType unsigned long int
77 # define LargestIntegralType unsigned long long int
79 #endif /* LargestIntegralType */
82 /* Printf format used to display LargestIntegralType as a hexidecimal. */
83 #ifndef LargestIntegralTypePrintfFormat
85 # define LargestIntegralTypePrintfFormat "0x%I64x"
88 # define LargestIntegralTypePrintfFormat "%#lx"
90 # define LargestIntegralTypePrintfFormat "%#llx"
93 #endif /* LargestIntegralTypePrintfFormat */
95 /* Printf format used to display LargestIntegralType as a decimal. */
96 #ifndef LargestIntegralTypePrintfFormatDecimal
98 # define LargestIntegralTypePrintfFormatDecimal "%I64u"
100 # if __WORDSIZE == 64
101 # define LargestIntegralTypePrintfFormatDecimal "%lu"
103 # define LargestIntegralTypePrintfFormatDecimal "%llu"
106 #endif /* LargestIntegralTypePrintfFormat */
108 /* Perform an unsigned cast to LargestIntegralType. */
109 #define cast_to_largest_integral_type(value) \
110 ((LargestIntegralType)(value))
112 /* Smallest integral type capable of holding a pointer. */
113 #if !defined(_UINTPTR_T) && !defined(_UINTPTR_T_DEFINED)
115 /* WIN32 is an ILP32 platform */
116 typedef unsigned int uintptr_t;
117 # elif defined(_WIN64)
118 typedef unsigned long int uintptr_t
121 /* ILP32 and LP64 platforms */
122 # ifdef __WORDSIZE /* glibc */
123 # if __WORDSIZE == 64
124 typedef unsigned long int uintptr_t;
126 typedef unsigned int uintptr_t;
127 # endif /* __WORDSIZE == 64 */
128 # else /* __WORDSIZE */
129 # if defined(_LP64) || defined(_I32LPx)
130 typedef unsigned long int uintptr_t;
132 typedef unsigned int uintptr_t;
134 # endif /* __WORDSIZE */
138 # define _UINTPTR_T_DEFINED
139 #endif /* !defined(_UINTPTR_T) || !defined(_UINTPTR_T_DEFINED) */
141 /* Perform an unsigned cast to uintptr_t. */
142 #define cast_to_pointer_integral_type(value) \
143 ((uintptr_t)((size_t)(value)))
145 /* Perform a cast of a pointer to LargestIntegralType */
146 #define cast_ptr_to_largest_integral_type(value) \
147 cast_to_largest_integral_type(cast_to_pointer_integral_type(value))
149 /* GCC have printf type attribute check. */
151 #define CMOCKA_PRINTF_ATTRIBUTE(a,b) \
152 __attribute__ ((__format__ (__printf__, a, b)))
154 #define CMOCKA_PRINTF_ATTRIBUTE(a,b)
155 #endif /* __GNUC__ */
157 #if defined(__GNUC__)
158 #define CMOCKA_DEPRECATED __attribute__ ((deprecated))
159 #elif defined(_MSC_VER)
160 #define CMOCKA_DEPRECATED __declspec(deprecated)
162 #define CMOCKA_DEPRECATED
165 #define WILL_RETURN_ALWAYS -1
166 #define WILL_RETURN_ONCE -2
169 * @defgroup cmocka_mock Mock Objects
172 * Mock objects mock objects are simulated objects that mimic the behavior of
173 * real objects. Instead of calling the real objects, the tested object calls a
174 * mock object that merely asserts that the correct methods were called, with
175 * the expected parameters, in the correct order.
178 * <li><strong>will_return(function, value)</strong> - The will_return() macro
179 * pushes a value onto a stack of mock values. This macro is intended to be
180 * used by the unit test itself, while programming the behaviour of the mocked
183 * <li><strong>mock()</strong> - the mock macro pops a value from a stack of
184 * test values. The user of the mock() macro is the mocked object that uses it
185 * to learn how it should behave.</li>
188 * Because the will_return() and mock() are intended to be used in pairs, the
189 * cmocka library would fail the test if there are more values pushed onto the
190 * stack using will_return() than consumed with mock() and vice-versa.
192 * The following unit test stub illustrates how would a unit test instruct the
193 * mock object to return a particular value:
196 * will_return(chef_cook, "hotdog");
197 * will_return(chef_cook, 0);
200 * Now the mock object can check if the parameter it received is the parameter
201 * which is expected by the test driver. This can be done the following way:
204 * int chef_cook(const char *order, char **dish_out)
206 * check_expected(order);
210 * For a complete example please at a look
211 * <a href="http://git.cryptomilk.org/projects/cmocka.git/tree/example/chef_wrap/waiter_test_wrap.c">here</a>.
218 * @brief Retrieve a return value of the current function.
220 * @return The value which was stored to return by this function.
224 LargestIntegralType
mock(void);
226 #define mock() _mock(__func__, __FILE__, __LINE__)
231 * @brief Retrieve a typed return value of the current function.
233 * The value would be casted to type internally to avoid having the
234 * caller to do the cast manually.
236 * @param[in] #type The expected type of the return value
238 * @return The value which was stored to return by this function.
243 * param = mock_type(int);
248 * @see mock_ptr_type()
250 #type mock_type(#type);
252 #define mock_type(type) ((type) mock())
257 * @brief Retrieve a typed return value of the current function.
259 * The value would be casted to type internally to avoid having the
260 * caller to do the cast manually but also casted to uintptr_t to make
261 * sure the result has a valid size to be used as a pointer.
263 * @param[in] #type The expected type of the return value
265 * @return The value which was stored to return by this function.
270 * param = mock_ptr_type(char *);
277 type
mock_ptr_type(#type);
279 #define mock_ptr_type(type) ((type) (uintptr_t) mock())
285 * @brief Store a value to be returned by mock() later.
287 * @param[in] #function The function which should return the given value.
289 * @param[in] value The value to be returned by mock().
292 * int return_integer(void)
294 * return (int)mock();
297 * static void test_integer_return(void **state)
299 * will_return(return_integer, 42);
301 * assert_int_equal(my_function_calling_return_integer(), 42);
306 * @see will_return_count()
308 void will_return(#function, LargestIntegralType value);
310 #define will_return(function, value) \
311 _will_return(#function, __FILE__, __LINE__, \
312 cast_to_largest_integral_type(value), 1)
317 * @brief Store a value to be returned by mock() later.
319 * @param[in] #function The function which should return the given value.
321 * @param[in] value The value to be returned by mock().
323 * @param[in] count The parameter indicates the number of times the value should
324 * be returned by mock(). If count is set to -1, the value
325 * will always be returned but must be returned at least once.
326 * If count is set to -2, the value will always be returned
327 * by mock(), but is not required to be returned.
331 void will_return_count(#function, LargestIntegralType value, int count);
333 #define will_return_count(function, value, count) \
334 _will_return(#function, __FILE__, __LINE__, \
335 cast_to_largest_integral_type(value), count)
340 * @brief Store a value that will be always returned by mock().
342 * @param[in] #function The function which should return the given value.
344 * @param[in] #value The value to be returned by mock().
346 * This is equivalent to:
348 * will_return_count(function, value, -1);
351 * @see will_return_count()
354 void will_return_always(#function, LargestIntegralType value);
356 #define will_return_always(function, value) \
357 will_return_count(function, (value), WILL_RETURN_ALWAYS)
362 * @brief Store a value that may be always returned by mock().
364 * This stores a value which will always be returned by mock() but is not
365 * required to be returned by at least one call to mock(). Therefore,
366 * in contrast to will_return_always() which causes a test failure if it
367 * is not returned at least once, will_return_maybe() will never cause a test
368 * to fail if its value is not returned.
370 * @param[in] #function The function which should return the given value.
372 * @param[in] #value The value to be returned by mock().
374 * This is equivalent to:
376 * will_return_count(function, value, -2);
379 * @see will_return_count()
382 void will_return_maybe(#function, LargestIntegralType value);
384 #define will_return_maybe(function, value) \
385 will_return_count(function, (value), WILL_RETURN_ONCE)
390 * @defgroup cmocka_param Checking Parameters
393 * Functionality to store expected values for mock function parameters.
395 * In addition to storing the return values of mock functions, cmocka provides
396 * functionality to store expected values for mock function parameters using
397 * the expect_*() functions provided. A mock function parameter can then be
398 * validated using the check_expected() macro.
400 * Successive calls to expect_*() macros for a parameter queues values to check
401 * the specified parameter. check_expected() checks a function parameter
402 * against the next value queued using expect_*(), if the parameter check fails
403 * a test failure is signalled. In addition if check_expected() is called and
404 * no more parameter values are queued a test failure occurs.
406 * The following test stub illustrates how to do this. First is the the function
407 * we call in the test driver:
410 * static void test_driver(void **state)
412 * expect_string(chef_cook, order, "hotdog");
416 * Now the chef_cook function can check if the parameter we got passed is the
417 * parameter which is expected by the test driver. This can be done the
421 * int chef_cook(const char *order, char **dish_out)
423 * check_expected(order);
427 * For a complete example please at a look at
428 * <a href="http://git.cryptomilk.org/projects/cmocka.git/tree/example/chef_wrap/waiter_test_wrap.c">here</a>
434 * Add a custom parameter checking function. If the event parameter is NULL
435 * the event structure is allocated internally by this function. If event
436 * parameter is provided it must be allocated on the heap and doesn't need to
437 * be deallocated by the caller.
441 * @brief Add a custom parameter checking function.
443 * If the event parameter is NULL the event structure is allocated internally
444 * by this function. If the parameter is provided it must be allocated on the
445 * heap and doesn't need to be deallocated by the caller.
447 * @param[in] #function The function to add a custom parameter checking
450 * @param[in] #parameter The parameters passed to the function.
452 * @param[in] #check_function The check function to call.
454 * @param[in] check_data The data to pass to the check function.
456 void expect_check(#function, #parameter, #check_function, const void *check_data);
458 #define expect_check(function, parameter, check_function, check_data) \
459 _expect_check(#function, #parameter, __FILE__, __LINE__, check_function, \
460 cast_to_largest_integral_type(check_data), NULL, 1)
465 * @brief Add an event to check if the parameter value is part of the provided
468 * The event is triggered by calling check_expected() in the mocked function.
470 * @param[in] #function The function to add the check for.
472 * @param[in] #parameter The name of the parameter passed to the function.
474 * @param[in] value_array[] The array to check for the value.
476 * @see check_expected().
478 void expect_in_set(#function, #parameter, LargestIntegralType value_array[]);
480 #define expect_in_set(function, parameter, value_array) \
481 expect_in_set_count(function, parameter, value_array, 1)
486 * @brief Add an event to check if the parameter value is part of the provided
489 * The event is triggered by calling check_expected() in the mocked function.
491 * @param[in] #function The function to add the check for.
493 * @param[in] #parameter The name of the parameter passed to the function.
495 * @param[in] value_array[] The array to check for the value.
497 * @param[in] count The count parameter returns the number of times the value
498 * should be returned by check_expected(). If count is set
499 * to -1 the value will always be returned.
501 * @see check_expected().
503 void expect_in_set_count(#function, #parameter, LargestIntegralType value_array[], size_t count);
505 #define expect_in_set_count(function, parameter, value_array, count) \
506 _expect_in_set(#function, #parameter, __FILE__, __LINE__, value_array, \
507 sizeof(value_array) / sizeof((value_array)[0]), count)
512 * @brief Add an event to check if the parameter value is not part of the
515 * The event is triggered by calling check_expected() in the mocked function.
517 * @param[in] #function The function to add the check for.
519 * @param[in] #parameter The name of the parameter passed to the function.
521 * @param[in] value_array[] The array to check for the value.
523 * @see check_expected().
525 void expect_not_in_set(#function, #parameter, LargestIntegralType value_array[]);
527 #define expect_not_in_set(function, parameter, value_array) \
528 expect_not_in_set_count(function, parameter, value_array, 1)
533 * @brief Add an event to check if the parameter value is not part of the
536 * The event is triggered by calling check_expected() in the mocked function.
538 * @param[in] #function The function to add the check for.
540 * @param[in] #parameter The name of the parameter passed to the function.
542 * @param[in] value_array[] The array to check for the value.
544 * @param[in] count The count parameter returns the number of times the value
545 * should be returned by check_expected(). If count is set
546 * to -1 the value will always be returned.
548 * @see check_expected().
550 void expect_not_in_set_count(#function, #parameter, LargestIntegralType value_array[], size_t count);
552 #define expect_not_in_set_count(function, parameter, value_array, count) \
553 _expect_not_in_set( \
554 #function, #parameter, __FILE__, __LINE__, value_array, \
555 sizeof(value_array) / sizeof((value_array)[0]), count)
561 * @brief Add an event to check a parameter is inside a numerical range.
562 * The check would succeed if minimum <= value <= maximum.
564 * The event is triggered by calling check_expected() in the mocked function.
566 * @param[in] #function The function to add the check for.
568 * @param[in] #parameter The name of the parameter passed to the function.
570 * @param[in] minimum The lower boundary of the interval to check against.
572 * @param[in] maximum The upper boundary of the interval to check against.
574 * @see check_expected().
576 void expect_in_range(#function, #parameter, LargestIntegralType minimum, LargestIntegralType maximum);
578 #define expect_in_range(function, parameter, minimum, maximum) \
579 expect_in_range_count(function, parameter, minimum, maximum, 1)
584 * @brief Add an event to repeatedly check a parameter is inside a
585 * numerical range. The check would succeed if minimum <= value <= maximum.
587 * The event is triggered by calling check_expected() in the mocked function.
589 * @param[in] #function The function to add the check for.
591 * @param[in] #parameter The name of the parameter passed to the function.
593 * @param[in] minimum The lower boundary of the interval to check against.
595 * @param[in] maximum The upper boundary of the interval to check against.
597 * @param[in] count The count parameter returns the number of times the value
598 * should be returned by check_expected(). If count is set
599 * to -1 the value will always be returned.
601 * @see check_expected().
603 void expect_in_range_count(#function, #parameter, LargestIntegralType minimum, LargestIntegralType maximum, size_t count);
605 #define expect_in_range_count(function, parameter, minimum, maximum, count) \
606 _expect_in_range(#function, #parameter, __FILE__, __LINE__, minimum, \
612 * @brief Add an event to check a parameter is outside a numerical range.
613 * The check would succeed if minimum > value > maximum.
615 * The event is triggered by calling check_expected() in the mocked function.
617 * @param[in] #function The function to add the check for.
619 * @param[in] #parameter The name of the parameter passed to the function.
621 * @param[in] minimum The lower boundary of the interval to check against.
623 * @param[in] maximum The upper boundary of the interval to check against.
625 * @see check_expected().
627 void expect_not_in_range(#function, #parameter, LargestIntegralType minimum, LargestIntegralType maximum);
629 #define expect_not_in_range(function, parameter, minimum, maximum) \
630 expect_not_in_range_count(function, parameter, minimum, maximum, 1)
635 * @brief Add an event to repeatedly check a parameter is outside a
636 * numerical range. The check would succeed if minimum > value > maximum.
638 * The event is triggered by calling check_expected() in the mocked function.
640 * @param[in] #function The function to add the check for.
642 * @param[in] #parameter The name of the parameter passed to the function.
644 * @param[in] minimum The lower boundary of the interval to check against.
646 * @param[in] maximum The upper boundary of the interval to check against.
648 * @param[in] count The count parameter returns the number of times the value
649 * should be returned by check_expected(). If count is set
650 * to -1 the value will always be returned.
652 * @see check_expected().
654 void expect_not_in_range_count(#function, #parameter, LargestIntegralType minimum, LargestIntegralType maximum, size_t count);
656 #define expect_not_in_range_count(function, parameter, minimum, maximum, \
658 _expect_not_in_range(#function, #parameter, __FILE__, __LINE__, \
659 minimum, maximum, count)
664 * @brief Add an event to check if a parameter is the given value.
666 * The event is triggered by calling check_expected() in the mocked function.
668 * @param[in] #function The function to add the check for.
670 * @param[in] #parameter The name of the parameter passed to the function.
672 * @param[in] value The value to check.
674 * @see check_expected().
676 void expect_value(#function, #parameter, LargestIntegralType value);
678 #define expect_value(function, parameter, value) \
679 expect_value_count(function, parameter, value, 1)
684 * @brief Add an event to repeatedly check if a parameter is the given value.
686 * The event is triggered by calling check_expected() in the mocked function.
688 * @param[in] #function The function to add the check for.
690 * @param[in] #parameter The name of the parameter passed to the function.
692 * @param[in] value The value to check.
694 * @param[in] count The count parameter returns the number of times the value
695 * should be returned by check_expected(). If count is set
696 * to -1 the value will always be returned.
698 * @see check_expected().
700 void expect_value_count(#function, #parameter, LargestIntegralType value, size_t count);
702 #define expect_value_count(function, parameter, value, count) \
703 _expect_value(#function, #parameter, __FILE__, __LINE__, \
704 cast_to_largest_integral_type(value), count)
709 * @brief Add an event to check if a parameter isn't the given value.
711 * The event is triggered by calling check_expected() in the mocked function.
713 * @param[in] #function The function to add the check for.
715 * @param[in] #parameter The name of the parameter passed to the function.
717 * @param[in] value The value to check.
719 * @see check_expected().
721 void expect_not_value(#function, #parameter, LargestIntegralType value);
723 #define expect_not_value(function, parameter, value) \
724 expect_not_value_count(function, parameter, value, 1)
729 * @brief Add an event to repeatedly check if a parameter isn't the given value.
731 * The event is triggered by calling check_expected() in the mocked function.
733 * @param[in] #function The function to add the check for.
735 * @param[in] #parameter The name of the parameter passed to the function.
737 * @param[in] value The value to check.
739 * @param[in] count The count parameter returns the number of times the value
740 * should be returned by check_expected(). If count is set
741 * to -1 the value will always be returned.
743 * @see check_expected().
745 void expect_not_value_count(#function, #parameter, LargestIntegralType value, size_t count);
747 #define expect_not_value_count(function, parameter, value, count) \
748 _expect_not_value(#function, #parameter, __FILE__, __LINE__, \
749 cast_to_largest_integral_type(value), count)
754 * @brief Add an event to check if the parameter value is equal to the
757 * The event is triggered by calling check_expected() in the mocked function.
759 * @param[in] #function The function to add the check for.
761 * @param[in] #parameter The name of the parameter passed to the function.
763 * @param[in] string The string value to compare.
765 * @see check_expected().
767 void expect_string(#function, #parameter, const char *string);
769 #define expect_string(function, parameter, string) \
770 expect_string_count(function, parameter, string, 1)
775 * @brief Add an event to check if the parameter value is equal to the
778 * The event is triggered by calling check_expected() in the mocked function.
780 * @param[in] #function The function to add the check for.
782 * @param[in] #parameter The name of the parameter passed to the function.
784 * @param[in] string The string value to compare.
786 * @param[in] count The count parameter returns the number of times the value
787 * should be returned by check_expected(). If count is set
788 * to -1 the value will always be returned.
790 * @see check_expected().
792 void expect_string_count(#function, #parameter, const char *string, size_t count);
794 #define expect_string_count(function, parameter, string, count) \
795 _expect_string(#function, #parameter, __FILE__, __LINE__, \
796 (const char*)(string), count)
801 * @brief Add an event to check if the parameter value isn't equal to the
804 * The event is triggered by calling check_expected() in the mocked function.
806 * @param[in] #function The function to add the check for.
808 * @param[in] #parameter The name of the parameter passed to the function.
810 * @param[in] string The string value to compare.
812 * @see check_expected().
814 void expect_not_string(#function, #parameter, const char *string);
816 #define expect_not_string(function, parameter, string) \
817 expect_not_string_count(function, parameter, string, 1)
822 * @brief Add an event to check if the parameter value isn't equal to the
825 * The event is triggered by calling check_expected() in the mocked function.
827 * @param[in] #function The function to add the check for.
829 * @param[in] #parameter The name of the parameter passed to the function.
831 * @param[in] string The string value to compare.
833 * @param[in] count The count parameter returns the number of times the value
834 * should be returned by check_expected(). If count is set
835 * to -1 the value will always be returned.
837 * @see check_expected().
839 void expect_not_string_count(#function, #parameter, const char *string, size_t count);
841 #define expect_not_string_count(function, parameter, string, count) \
842 _expect_not_string(#function, #parameter, __FILE__, __LINE__, \
843 (const char*)(string), count)
848 * @brief Add an event to check if the parameter does match an area of memory.
850 * The event is triggered by calling check_expected() in the mocked function.
852 * @param[in] #function The function to add the check for.
854 * @param[in] #parameter The name of the parameter passed to the function.
856 * @param[in] memory The memory to compare.
858 * @param[in] size The size of the memory to compare.
860 * @see check_expected().
862 void expect_memory(#function, #parameter, void *memory, size_t size);
864 #define expect_memory(function, parameter, memory, size) \
865 expect_memory_count(function, parameter, memory, size, 1)
870 * @brief Add an event to repeatedly check if the parameter does match an area
873 * The event is triggered by calling check_expected() in the mocked function.
875 * @param[in] #function The function to add the check for.
877 * @param[in] #parameter The name of the parameter passed to the function.
879 * @param[in] memory The memory to compare.
881 * @param[in] size The size of the memory to compare.
883 * @param[in] count The count parameter returns the number of times the value
884 * should be returned by check_expected(). If count is set
885 * to -1 the value will always be returned.
887 * @see check_expected().
889 void expect_memory_count(#function, #parameter, void *memory, size_t size, size_t count);
891 #define expect_memory_count(function, parameter, memory, size, count) \
892 _expect_memory(#function, #parameter, __FILE__, __LINE__, \
893 (const void*)(memory), size, count)
898 * @brief Add an event to check if the parameter doesn't match an area of
901 * The event is triggered by calling check_expected() in the mocked function.
903 * @param[in] #function The function to add the check for.
905 * @param[in] #parameter The name of the parameter passed to the function.
907 * @param[in] memory The memory to compare.
909 * @param[in] size The size of the memory to compare.
911 * @see check_expected().
913 void expect_not_memory(#function, #parameter, void *memory, size_t size);
915 #define expect_not_memory(function, parameter, memory, size) \
916 expect_not_memory_count(function, parameter, memory, size, 1)
921 * @brief Add an event to repeatedly check if the parameter doesn't match an
924 * The event is triggered by calling check_expected() in the mocked function.
926 * @param[in] #function The function to add the check for.
928 * @param[in] #parameter The name of the parameter passed to the function.
930 * @param[in] memory The memory to compare.
932 * @param[in] size The size of the memory to compare.
934 * @param[in] count The count parameter returns the number of times the value
935 * should be returned by check_expected(). If count is set
936 * to -1 the value will always be returned.
938 * @see check_expected().
940 void expect_not_memory_count(#function, #parameter, void *memory, size_t size, size_t count);
942 #define expect_not_memory_count(function, parameter, memory, size, count) \
943 _expect_not_memory(#function, #parameter, __FILE__, __LINE__, \
944 (const void*)(memory), size, count)
950 * @brief Add an event to check if a parameter (of any value) has been passed.
952 * The event is triggered by calling check_expected() in the mocked function.
954 * @param[in] #function The function to add the check for.
956 * @param[in] #parameter The name of the parameter passed to the function.
958 * @see check_expected().
960 void expect_any(#function, #parameter);
962 #define expect_any(function, parameter) \
963 expect_any_count(function, parameter, 1)
968 * @brief Add an event to repeatedly check if a parameter (of any value) has
971 * The event is triggered by calling check_expected() in the mocked function.
973 * @param[in] #function The function to add the check for.
975 * @param[in] #parameter The name of the parameter passed to the function.
977 * @param[in] count The count parameter returns the number of times the value
978 * should be returned by check_expected(). If count is set
979 * to -1 the value will always be returned.
981 * @see check_expected().
983 void expect_any_count(#function, #parameter, size_t count);
985 #define expect_any_count(function, parameter, count) \
986 _expect_any(#function, #parameter, __FILE__, __LINE__, count)
991 * @brief Determine whether a function parameter is correct.
993 * This ensures the next value queued by one of the expect_*() macros matches
994 * the specified variable.
996 * This function needs to be called in the mock object.
998 * @param[in] #parameter The parameter to check.
1000 void check_expected(#parameter);
1002 #define check_expected(parameter) \
1003 _check_expected(__func__, #parameter, __FILE__, __LINE__, \
1004 cast_to_largest_integral_type(parameter))
1009 * @brief Determine whether a function parameter is correct.
1011 * This ensures the next value queued by one of the expect_*() macros matches
1012 * the specified variable.
1014 * This function needs to be called in the mock object.
1016 * @param[in] #parameter The pointer to check.
1018 void check_expected_ptr(#parameter);
1020 #define check_expected_ptr(parameter) \
1021 _check_expected(__func__, #parameter, __FILE__, __LINE__, \
1022 cast_ptr_to_largest_integral_type(parameter))
1028 * @defgroup cmocka_asserts Assert Macros
1031 * This is a set of useful assert macros like the standard C libary's
1034 * On an assertion failure a cmocka assert macro will write the failure to the
1035 * standard error stream and signal a test failure. Due to limitations of the C
1036 * language the general C standard library assert() and cmocka's assert_true()
1037 * and assert_false() macros can only display the expression that caused the
1038 * assert failure. cmocka's type specific assert macros, assert_{type}_equal()
1039 * and assert_{type}_not_equal(), display the data that caused the assertion
1040 * failure which increases data visibility aiding debugging of failing test
1048 * @brief Assert that the given expression is true.
1050 * The function prints an error message to standard error and terminates the
1051 * test by calling fail() if expression is false (i.e., compares equal to
1054 * @param[in] expression The expression to evaluate.
1056 * @see assert_int_equal()
1057 * @see assert_string_equal()
1059 void assert_true(scalar expression
);
1061 #define assert_true(c) _assert_true(cast_to_largest_integral_type(c), #c, \
1067 * @brief Assert that the given expression is false.
1069 * The function prints an error message to standard error and terminates the
1070 * test by calling fail() if expression is true.
1072 * @param[in] expression The expression to evaluate.
1074 * @see assert_int_equal()
1075 * @see assert_string_equal()
1077 void assert_false(scalar expression
);
1079 #define assert_false(c) _assert_true(!(cast_to_largest_integral_type(c)), #c, \
1085 * @brief Assert that the return_code is greater than or equal to 0.
1087 * The function prints an error message to standard error and terminates the
1088 * test by calling fail() if the return code is smaller than 0. If the function
1089 * you check sets an errno if it fails you can pass it to the function and
1090 * it will be printed as part of the error message.
1092 * @param[in] rc The return code to evaluate.
1094 * @param[in] error Pass errno here or 0.
1096 void assert_return_code(int rc
, int error
);
1098 #define assert_return_code(rc, error) \
1099 _assert_return_code(cast_to_largest_integral_type(rc), \
1101 cast_to_largest_integral_type(error), \
1102 #rc, __FILE__, __LINE__)
1107 * @brief Assert that the given pointer is non-NULL.
1109 * The function prints an error message to standard error and terminates the
1110 * test by calling fail() if the pointer is non-NULL.
1112 * @param[in] pointer The pointer to evaluate.
1114 * @see assert_null()
1116 void assert_non_null(void *pointer
);
1118 #define assert_non_null(c) _assert_true(cast_ptr_to_largest_integral_type(c), #c, \
1124 * @brief Assert that the given pointer is NULL.
1126 * The function prints an error message to standard error and terminates the
1127 * test by calling fail() if the pointer is non-NULL.
1129 * @param[in] pointer The pointer to evaluate.
1131 * @see assert_non_null()
1133 void assert_null(void *pointer
);
1135 #define assert_null(c) _assert_true(!(cast_ptr_to_largest_integral_type(c)), #c, \
1141 * @brief Assert that the two given pointers are equal.
1143 * The function prints an error message and terminates the test by calling
1144 * fail() if the pointers are not equal.
1146 * @param[in] a The first pointer to compare.
1148 * @param[in] b The pointer to compare against the first one.
1150 void assert_ptr_equal(void *a
, void *b
);
1152 #define assert_ptr_equal(a, b) \
1153 _assert_int_equal(cast_ptr_to_largest_integral_type(a), \
1154 cast_ptr_to_largest_integral_type(b), \
1160 * @brief Assert that the two given pointers are not equal.
1162 * The function prints an error message and terminates the test by calling
1163 * fail() if the pointers are equal.
1165 * @param[in] a The first pointer to compare.
1167 * @param[in] b The pointer to compare against the first one.
1169 void assert_ptr_not_equal(void *a
, void *b
);
1171 #define assert_ptr_not_equal(a, b) \
1172 _assert_int_not_equal(cast_ptr_to_largest_integral_type(a), \
1173 cast_ptr_to_largest_integral_type(b), \
1179 * @brief Assert that the two given integers are equal.
1181 * The function prints an error message to standard error and terminates the
1182 * test by calling fail() if the integers are not equal.
1184 * @param[in] a The first integer to compare.
1186 * @param[in] b The integer to compare against the first one.
1188 void assert_int_equal(int a
, int b
);
1190 #define assert_int_equal(a, b) \
1191 _assert_int_equal(cast_to_largest_integral_type(a), \
1192 cast_to_largest_integral_type(b), \
1198 * @brief Assert that the two given integers are not equal.
1200 * The function prints an error message to standard error and terminates the
1201 * test by calling fail() if the integers are equal.
1203 * @param[in] a The first integer to compare.
1205 * @param[in] b The integer to compare against the first one.
1207 * @see assert_int_equal()
1209 void assert_int_not_equal(int a
, int b
);
1211 #define assert_int_not_equal(a, b) \
1212 _assert_int_not_equal(cast_to_largest_integral_type(a), \
1213 cast_to_largest_integral_type(b), \
1219 * @brief Assert that the two given strings are equal.
1221 * The function prints an error message to standard error and terminates the
1222 * test by calling fail() if the strings are not equal.
1224 * @param[in] a The string to check.
1226 * @param[in] b The other string to compare.
1228 void assert_string_equal(const char *a
, const char *b
);
1230 #define assert_string_equal(a, b) \
1231 _assert_string_equal((const char*)(a), (const char*)(b), __FILE__, \
1237 * @brief Assert that the two given strings are not equal.
1239 * The function prints an error message to standard error and terminates the
1240 * test by calling fail() if the strings are equal.
1242 * @param[in] a The string to check.
1244 * @param[in] b The other string to compare.
1246 void assert_string_not_equal(const char *a
, const char *b
);
1248 #define assert_string_not_equal(a, b) \
1249 _assert_string_not_equal((const char*)(a), (const char*)(b), __FILE__, \
1255 * @brief Assert that the two given areas of memory are equal, otherwise fail.
1257 * The function prints an error message to standard error and terminates the
1258 * test by calling fail() if the memory is not equal.
1260 * @param[in] a The first memory area to compare
1261 * (interpreted as unsigned char).
1263 * @param[in] b The second memory area to compare
1264 * (interpreted as unsigned char).
1266 * @param[in] size The first n bytes of the memory areas to compare.
1268 void assert_memory_equal(const void *a
, const void *b
, size_t size
);
1270 #define assert_memory_equal(a, b, size) \
1271 _assert_memory_equal((const void*)(a), (const void*)(b), size, __FILE__, \
1277 * @brief Assert that the two given areas of memory are not equal.
1279 * The function prints an error message to standard error and terminates the
1280 * test by calling fail() if the memory is equal.
1282 * @param[in] a The first memory area to compare
1283 * (interpreted as unsigned char).
1285 * @param[in] b The second memory area to compare
1286 * (interpreted as unsigned char).
1288 * @param[in] size The first n bytes of the memory areas to compare.
1290 void assert_memory_not_equal(const void *a
, const void *b
, size_t size
);
1292 #define assert_memory_not_equal(a, b, size) \
1293 _assert_memory_not_equal((const void*)(a), (const void*)(b), size, \
1299 * @brief Assert that the specified value is not smaller than the minimum
1300 * and and not greater than the maximum.
1302 * The function prints an error message to standard error and terminates the
1303 * test by calling fail() if value is not in range.
1305 * @param[in] value The value to check.
1307 * @param[in] minimum The minimum value allowed.
1309 * @param[in] maximum The maximum value allowed.
1311 void assert_in_range(LargestIntegralType value
, LargestIntegralType minimum
, LargestIntegralType maximum
);
1313 #define assert_in_range(value, minimum, maximum) \
1315 cast_to_largest_integral_type(value), \
1316 cast_to_largest_integral_type(minimum), \
1317 cast_to_largest_integral_type(maximum), __FILE__, __LINE__)
1322 * @brief Assert that the specified value is smaller than the minimum or
1323 * greater than the maximum.
1325 * The function prints an error message to standard error and terminates the
1326 * test by calling fail() if value is in range.
1328 * @param[in] value The value to check.
1330 * @param[in] minimum The minimum value to compare.
1332 * @param[in] maximum The maximum value to compare.
1334 void assert_not_in_range(LargestIntegralType value
, LargestIntegralType minimum
, LargestIntegralType maximum
);
1336 #define assert_not_in_range(value, minimum, maximum) \
1337 _assert_not_in_range( \
1338 cast_to_largest_integral_type(value), \
1339 cast_to_largest_integral_type(minimum), \
1340 cast_to_largest_integral_type(maximum), __FILE__, __LINE__)
1345 * @brief Assert that the specified value is within a set.
1347 * The function prints an error message to standard error and terminates the
1348 * test by calling fail() if value is not within a set.
1350 * @param[in] value The value to look up
1352 * @param[in] values[] The array to check for the value.
1354 * @param[in] count The size of the values array.
1356 void assert_in_set(LargestIntegralType value
, LargestIntegralType values
[], size_t count
);
1358 #define assert_in_set(value, values, number_of_values) \
1359 _assert_in_set(value, values, number_of_values, __FILE__, __LINE__)
1364 * @brief Assert that the specified value is not within a set.
1366 * The function prints an error message to standard error and terminates the
1367 * test by calling fail() if value is within a set.
1369 * @param[in] value The value to look up
1371 * @param[in] values[] The array to check for the value.
1373 * @param[in] count The size of the values array.
1375 void assert_not_in_set(LargestIntegralType value
, LargestIntegralType values
[], size_t count
);
1377 #define assert_not_in_set(value, values, number_of_values) \
1378 _assert_not_in_set(value, values, number_of_values, __FILE__, __LINE__)
1384 * @defgroup cmocka_call_order Call Ordering
1387 * It is often beneficial to make sure that functions are called in an
1388 * order. This is independent of mock returns and parameter checking as both
1389 * of the aforementioned do not check the order in which they are called from
1390 * different functions.
1393 * <li><strong>expect_function_call(function)</strong> - The
1394 * expect_function_call() macro pushes an expectation onto the stack of
1395 * expected calls.</li>
1397 * <li><strong>function_called()</strong> - pops a value from the stack of
1398 * expected calls. function_called() is invoked within the mock object
1402 * expect_function_call() and function_called() are intended to be used in
1403 * pairs. Cmocka will fail a test if there are more or less expected calls
1404 * created (e.g. expect_function_call()) than consumed with function_called().
1405 * There are provisions such as ignore_function_calls() which allow this
1406 * restriction to be circumvented in tests where mock calls for the code under
1407 * test are not the focus of the test.
1409 * The following example illustrates how a unit test instructs cmocka
1410 * to expect a function_called() from a particular mock,
1411 * <strong>chef_sing()</strong>:
1414 * void chef_sing(void);
1416 * void code_under_test()
1421 * void some_test(void **state)
1423 * expect_function_call(chef_sing);
1424 * code_under_test();
1428 * The implementation of the mock then must check whether it was meant to
1429 * be called by invoking <strong>function_called()</strong>:
1434 * function_called();
1443 * @brief Check that current mocked function is being called in the expected
1446 * @see expect_function_call()
1448 void function_called(void);
1450 #define function_called() _function_called(__func__, __FILE__, __LINE__)
1455 * @brief Store expected call(s) to a mock to be checked by function_called()
1458 * @param[in] #function The function which should should be called
1460 * @param[in] times number of times this mock must be called
1462 * @see function_called()
1464 void expect_function_calls(#function, const int times);
1466 #define expect_function_calls(function, times) \
1467 _expect_function_call(#function, __FILE__, __LINE__, times)
1472 * @brief Store expected single call to a mock to be checked by
1473 * function_called() later.
1475 * @param[in] #function The function which should should be called
1477 * @see function_called()
1479 void expect_function_call(#function);
1481 #define expect_function_call(function) \
1482 _expect_function_call(#function, __FILE__, __LINE__, 1)
1487 * @brief Expects function_called() from given mock at least once
1489 * @param[in] #function The function which should should be called
1491 * @see function_called()
1493 void expect_function_call_any(#function);
1495 #define expect_function_call_any(function) \
1496 _expect_function_call(#function, __FILE__, __LINE__, -1)
1501 * @brief Ignores function_called() invocations from given mock function.
1503 * @param[in] #function The function which should should be called
1505 * @see function_called()
1507 void ignore_function_calls(#function);
1509 #define ignore_function_calls(function) \
1510 _expect_function_call(#function, __FILE__, __LINE__, -2)
1516 * @defgroup cmocka_exec Running Tests
1519 * This is the way tests are executed with CMocka.
1521 * The following example illustrates this macro's use with the unit_test macro.
1524 * void Test0(void **state);
1525 * void Test1(void **state);
1529 * const struct CMUnitTest tests[] = {
1530 * cmocka_unit_test(Test0),
1531 * cmocka_unit_test(Test1),
1534 * return cmocka_run_group_tests(tests, NULL, NULL);
1543 * @brief Forces the test to fail immediately and quit.
1547 #define fail() _fail(__FILE__, __LINE__)
1552 * @brief Forces the test to not be executed, but marked as skipped
1556 #define skip() _skip(__FILE__, __LINE__)
1561 * @brief Forces the test to fail immediately and quit, printing the reason.
1564 * fail_msg("This is some error message for test");
1570 * char *error_msg = "This is some error message for test";
1571 * fail_msg("%s", error_msg);
1574 void fail_msg(const char *msg
, ...);
1576 #define fail_msg(msg, ...) do { \
1577 print_error("ERROR: " msg "\n", ##__VA_ARGS__); \
1584 * @brief Generic method to run a single test.
1586 * @deprecated This function was deprecated in favor of cmocka_run_group_tests
1588 * @param[in] #function The function to test.
1590 * @return 0 on success, 1 if an error occured.
1593 * // A test case that does nothing and succeeds.
1594 * void null_test_success(void **state) {
1598 * return run_test(null_test_success);
1602 int run_test(#function);
1604 #define run_test(f) _run_test(#f, f, NULL, UNIT_TEST_FUNCTION_TYPE_TEST, NULL)
1607 static inline void _unit_test_dummy(void **state
) {
1611 /** Initializes a UnitTest structure.
1613 * @deprecated This function was deprecated in favor of cmocka_unit_test
1615 #define unit_test(f) { #f, f, UNIT_TEST_FUNCTION_TYPE_TEST }
1617 #define _unit_test_setup(test, setup) \
1618 { #test "_" #setup, setup, UNIT_TEST_FUNCTION_TYPE_SETUP }
1620 /** Initializes a UnitTest structure with a setup function.
1622 * @deprecated This function was deprecated in favor of cmocka_unit_test_setup
1624 #define unit_test_setup(test, setup) \
1625 _unit_test_setup(test, setup), \
1627 _unit_test_teardown(test, _unit_test_dummy)
1629 #define _unit_test_teardown(test, teardown) \
1630 { #test "_" #teardown, teardown, UNIT_TEST_FUNCTION_TYPE_TEARDOWN }
1632 /** Initializes a UnitTest structure with a teardown function.
1634 * @deprecated This function was deprecated in favor of cmocka_unit_test_teardown
1636 #define unit_test_teardown(test, teardown) \
1637 _unit_test_setup(test, _unit_test_dummy), \
1639 _unit_test_teardown(test, teardown)
1641 /** Initializes a UnitTest structure for a group setup function.
1643 * @deprecated This function was deprecated in favor of cmocka_run_group_tests
1645 #define group_test_setup(setup) \
1646 { "group_" #setup, setup, UNIT_TEST_FUNCTION_TYPE_GROUP_SETUP }
1648 /** Initializes a UnitTest structure for a group teardown function.
1650 * @deprecated This function was deprecated in favor of cmocka_run_group_tests
1652 #define group_test_teardown(teardown) \
1653 { "group_" #teardown, teardown, UNIT_TEST_FUNCTION_TYPE_GROUP_TEARDOWN }
1656 * Initialize an array of UnitTest structures with a setup function for a test
1657 * and a teardown function. Either setup or teardown can be NULL.
1659 * @deprecated This function was deprecated in favor of
1660 * cmocka_unit_test_setup_teardown
1662 #define unit_test_setup_teardown(test, setup, teardown) \
1663 _unit_test_setup(test, setup), \
1665 _unit_test_teardown(test, teardown)
1668 /** Initializes a CMUnitTest structure. */
1669 #define cmocka_unit_test(f) { #f, f, NULL, NULL, NULL }
1671 /** Initializes a CMUnitTest structure with a setup function. */
1672 #define cmocka_unit_test_setup(f, setup) { #f, f, setup, NULL, NULL }
1674 /** Initializes a CMUnitTest structure with a teardown function. */
1675 #define cmocka_unit_test_teardown(f, teardown) { #f, f, NULL, teardown, NULL }
1678 * Initialize an array of CMUnitTest structures with a setup function for a test
1679 * and a teardown function. Either setup or teardown can be NULL.
1681 #define cmocka_unit_test_setup_teardown(f, setup, teardown) { #f, f, setup, teardown, NULL }
1684 * Initialize a CMUnitTest structure with given initial state. It will be passed
1685 * to test function as an argument later. It can be used when test state does
1686 * not need special initialization or was initialized already.
1687 * @note If the group setup function initialized the state already, it won't be
1688 * overridden by the initial state defined here.
1690 #define cmocka_unit_test_prestate(f, state) { #f, f, NULL, NULL, state }
1693 * Initialize a CMUnitTest structure with given initial state, setup and
1694 * teardown function. Any of these values can be NULL. Initial state is passed
1695 * later to setup function, or directly to test if none was given.
1696 * @note If the group setup function initialized the state already, it won't be
1697 * overridden by the initial state defined here.
1699 #define cmocka_unit_test_prestate_setup_teardown(f, setup, teardown, state) { #f, f, setup, teardown, state }
1701 #define run_tests(tests) _run_tests(tests, sizeof(tests) / sizeof(tests)[0])
1702 #define run_group_tests(tests) _run_group_tests(tests, sizeof(tests) / sizeof(tests)[0])
1706 * @brief Run tests specified by an array of CMUnitTest structures.
1708 * @param[in] group_tests[] The array of unit tests to execute.
1710 * @param[in] group_setup The setup function which should be called before
1711 * all unit tests are executed.
1713 * @param[in] group_teardown The teardown function to be called after all
1714 * tests have finished.
1716 * @return 0 on success, or the number of failed tests.
1719 * static int setup(void **state) {
1720 * int *answer = malloc(sizeof(int));
1721 * if (*answer == NULL) {
1731 * static int teardown(void **state) {
1737 * static void null_test_success(void **state) {
1741 * static void int_test_success(void **state) {
1742 * int *answer = *state;
1743 * assert_int_equal(*answer, 42);
1747 * const struct CMUnitTest tests[] = {
1748 * cmocka_unit_test(null_test_success),
1749 * cmocka_unit_test_setup_teardown(int_test_success, setup, teardown),
1752 * return cmocka_run_group_tests(tests, NULL, NULL);
1756 * @see cmocka_unit_test
1757 * @see cmocka_unit_test_setup
1758 * @see cmocka_unit_test_teardown
1759 * @see cmocka_unit_test_setup_teardown
1761 int cmocka_run_group_tests(const struct CMUnitTest group_tests
[],
1762 CMFixtureFunction group_setup
,
1763 CMFixtureFunction group_teardown
);
1765 # define cmocka_run_group_tests(group_tests, group_setup, group_teardown) \
1766 _cmocka_run_group_tests(#group_tests, group_tests, sizeof(group_tests) / sizeof(group_tests)[0], group_setup, group_teardown)
1771 * @brief Run tests specified by an array of CMUnitTest structures and specify
1774 * @param[in] group_name The name of the group test.
1776 * @param[in] group_tests[] The array of unit tests to execute.
1778 * @param[in] group_setup The setup function which should be called before
1779 * all unit tests are executed.
1781 * @param[in] group_teardown The teardown function to be called after all
1782 * tests have finished.
1784 * @return 0 on success, or the number of failed tests.
1787 * static int setup(void **state) {
1788 * int *answer = malloc(sizeof(int));
1789 * if (*answer == NULL) {
1799 * static int teardown(void **state) {
1805 * static void null_test_success(void **state) {
1809 * static void int_test_success(void **state) {
1810 * int *answer = *state;
1811 * assert_int_equal(*answer, 42);
1815 * const struct CMUnitTest tests[] = {
1816 * cmocka_unit_test(null_test_success),
1817 * cmocka_unit_test_setup_teardown(int_test_success, setup, teardown),
1820 * return cmocka_run_group_tests_name("success_test", tests, NULL, NULL);
1824 * @see cmocka_unit_test
1825 * @see cmocka_unit_test_setup
1826 * @see cmocka_unit_test_teardown
1827 * @see cmocka_unit_test_setup_teardown
1829 int cmocka_run_group_tests_name(const char *group_name
,
1830 const struct CMUnitTest group_tests
[],
1831 CMFixtureFunction group_setup
,
1832 CMFixtureFunction group_teardown
);
1834 # define cmocka_run_group_tests_name(group_name, group_tests, group_setup, group_teardown) \
1835 _cmocka_run_group_tests(group_name, group_tests, sizeof(group_tests) / sizeof(group_tests)[0], group_setup, group_teardown)
1841 * @defgroup cmocka_alloc Dynamic Memory Allocation
1844 * Memory leaks, buffer overflows and underflows can be checked using cmocka.
1846 * To test for memory leaks, buffer overflows and underflows a module being
1847 * tested by cmocka should replace calls to malloc(), calloc() and free() to
1848 * test_malloc(), test_calloc() and test_free() respectively. Each time a block
1849 * is deallocated using test_free() it is checked for corruption, if a corrupt
1850 * block is found a test failure is signalled. All blocks allocated using the
1851 * test_*() allocation functions are tracked by the cmocka library. When a test
1852 * completes if any allocated blocks (memory leaks) remain they are reported
1853 * and a test failure is signalled.
1855 * For simplicity cmocka currently executes all tests in one process. Therefore
1856 * all test cases in a test application share a single address space which
1857 * means memory corruption from a single test case could potentially cause the
1858 * test application to exit prematurely.
1865 * @brief Test function overriding malloc.
1867 * @param[in] size The bytes which should be allocated.
1869 * @return A pointer to the allocated memory or NULL on error.
1872 * #ifdef UNIT_TESTING
1873 * extern void* _test_malloc(const size_t size, const char* file, const int line);
1875 * #define malloc(size) _test_malloc(size, __FILE__, __LINE__)
1878 * void leak_memory() {
1879 * int * const temporary = (int*)malloc(sizeof(int));
1886 void *test_malloc(size_t size
);
1888 #define test_malloc(size) _test_malloc(size, __FILE__, __LINE__)
1893 * @brief Test function overriding calloc.
1895 * The memory is set to zero.
1897 * @param[in] nmemb The number of elements for an array to be allocated.
1899 * @param[in] size The size in bytes of each array element to allocate.
1901 * @return A pointer to the allocated memory, NULL on error.
1905 void *test_calloc(size_t nmemb
, size_t size
);
1907 #define test_calloc(num, size) _test_calloc(num, size, __FILE__, __LINE__)
1912 * @brief Test function overriding realloc which detects buffer overruns
1913 * and memoery leaks.
1915 * @param[in] ptr The memory block which should be changed.
1917 * @param[in] size The bytes which should be allocated.
1919 * @return The newly allocated memory block, NULL on error.
1921 void *test_realloc(void *ptr
, size_t size
);
1923 #define test_realloc(ptr, size) _test_realloc(ptr, size, __FILE__, __LINE__)
1928 * @brief Test function overriding free(3).
1930 * @param[in] ptr The pointer to the memory space to free.
1934 void test_free(void *ptr
);
1936 #define test_free(ptr) _test_free(ptr, __FILE__, __LINE__)
1939 /* Redirect malloc, calloc and free to the unit test allocators. */
1941 #define malloc test_malloc
1942 #define realloc test_realloc
1943 #define calloc test_calloc
1944 #define free test_free
1945 #endif /* UNIT_TESTING */
1951 * @defgroup cmocka_mock_assert Standard Assertions
1954 * How to handle assert(3) of the standard C library.
1956 * Runtime assert macros like the standard C library's assert() should be
1957 * redefined in modules being tested to use cmocka's mock_assert() function.
1958 * Normally mock_assert() signals a test failure. If a function is called using
1959 * the expect_assert_failure() macro, any calls to mock_assert() within the
1960 * function will result in the execution of the test. If no calls to
1961 * mock_assert() occur during the function called via expect_assert_failure() a
1962 * test failure is signalled.
1968 * @brief Function to replace assert(3) in tested code.
1970 * In conjuction with check_assert() it's possible to determine whether an
1971 * assert condition has failed without stopping a test.
1973 * @param[in] result The expression to assert.
1975 * @param[in] expression The expression as string.
1977 * @param[in] file The file mock_assert() is called.
1979 * @param[in] line The line mock_assert() is called.
1982 * #ifdef UNIT_TESTING
1983 * extern void mock_assert(const int result, const char* const expression,
1984 * const char * const file, const int line);
1987 * #define assert(expression) \
1988 * mock_assert((int)(expression), #expression, __FILE__, __LINE__);
1991 * void increment_value(int * const value) {
1998 * @see expect_assert_failure
2000 void mock_assert(const int result
, const char* const expression
,
2001 const char * const file
, const int line
);
2005 * @brief Ensure that mock_assert() is called.
2007 * If mock_assert() is called the assert expression string is returned.
2009 * @param[in] fn_call The function will will call mock_assert().
2012 * #define assert mock_assert
2014 * void showmessage(const char *message) {
2018 * int main(int argc, const char* argv[]) {
2019 * expect_assert_failure(show_message(NULL));
2020 * printf("succeeded\n");
2026 void expect_assert_failure(function fn_call
);
2028 #define expect_assert_failure(function_call) \
2030 const int result = setjmp(global_expect_assert_env); \
2031 global_expecting_assert = 1; \
2033 print_message("Expected assertion %s occurred\n", \
2034 global_last_failed_assert); \
2035 global_expecting_assert = 0; \
2038 global_expecting_assert = 0; \
2039 print_error("Expected assert in %s\n", #function_call); \
2040 _fail(__FILE__, __LINE__); \
2047 /* Function prototype for setup, test and teardown functions. */
2048 typedef void (*UnitTestFunction
)(void **state
);
2050 /* Function that determines whether a function parameter value is correct. */
2051 typedef int (*CheckParameterValue
)(const LargestIntegralType value
,
2052 const LargestIntegralType check_value_data
);
2054 /* Type of the unit test function. */
2055 typedef enum UnitTestFunctionType
{
2056 UNIT_TEST_FUNCTION_TYPE_TEST
= 0,
2057 UNIT_TEST_FUNCTION_TYPE_SETUP
,
2058 UNIT_TEST_FUNCTION_TYPE_TEARDOWN
,
2059 UNIT_TEST_FUNCTION_TYPE_GROUP_SETUP
,
2060 UNIT_TEST_FUNCTION_TYPE_GROUP_TEARDOWN
,
2061 } UnitTestFunctionType
;
2064 * Stores a unit test function with its name and type.
2065 * NOTE: Every setup function must be paired with a teardown function. It's
2066 * possible to specify NULL function pointers.
2068 typedef struct UnitTest
{
2070 UnitTestFunction function
;
2071 UnitTestFunctionType function_type
;
2074 typedef struct GroupTest
{
2075 UnitTestFunction setup
;
2076 UnitTestFunction teardown
;
2077 const UnitTest
*tests
;
2078 const size_t number_of_tests
;
2081 /* Function prototype for test functions. */
2082 typedef void (*CMUnitTestFunction
)(void **state
);
2084 /* Function prototype for setup and teardown functions. */
2085 typedef int (*CMFixtureFunction
)(void **state
);
2089 CMUnitTestFunction test_func
;
2090 CMFixtureFunction setup_func
;
2091 CMFixtureFunction teardown_func
;
2092 void *initial_state
;
2095 /* Location within some source code. */
2096 typedef struct SourceLocation
{
2101 /* Event that's called to check a parameter value. */
2102 typedef struct CheckParameterEvent
{
2103 SourceLocation location
;
2104 const char *parameter_name
;
2105 CheckParameterValue check_value
;
2106 LargestIntegralType check_value_data
;
2107 } CheckParameterEvent
;
2109 /* Used by expect_assert_failure() and mock_assert(). */
2110 extern int global_expecting_assert
;
2111 extern jmp_buf global_expect_assert_env
;
2112 extern const char * global_last_failed_assert
;
2114 /* Retrieves a value for the given function, as set by "will_return". */
2115 LargestIntegralType
_mock(const char * const function
, const char* const file
,
2118 void _expect_function_call(
2119 const char * const function_name
,
2120 const char * const file
,
2124 void _function_called(const char * const function
, const char* const file
,
2128 const char* const function
, const char* const parameter
,
2129 const char* const file
, const int line
,
2130 const CheckParameterValue check_function
,
2131 const LargestIntegralType check_data
, CheckParameterEvent
* const event
,
2134 void _expect_in_set(
2135 const char* const function
, const char* const parameter
,
2136 const char* const file
, const int line
, const LargestIntegralType values
[],
2137 const size_t number_of_values
, const int count
);
2138 void _expect_not_in_set(
2139 const char* const function
, const char* const parameter
,
2140 const char* const file
, const int line
, const LargestIntegralType values
[],
2141 const size_t number_of_values
, const int count
);
2143 void _expect_in_range(
2144 const char* const function
, const char* const parameter
,
2145 const char* const file
, const int line
,
2146 const LargestIntegralType minimum
,
2147 const LargestIntegralType maximum
, const int count
);
2148 void _expect_not_in_range(
2149 const char* const function
, const char* const parameter
,
2150 const char* const file
, const int line
,
2151 const LargestIntegralType minimum
,
2152 const LargestIntegralType maximum
, const int count
);
2155 const char* const function
, const char* const parameter
,
2156 const char* const file
, const int line
, const LargestIntegralType value
,
2158 void _expect_not_value(
2159 const char* const function
, const char* const parameter
,
2160 const char* const file
, const int line
, const LargestIntegralType value
,
2163 void _expect_string(
2164 const char* const function
, const char* const parameter
,
2165 const char* const file
, const int line
, const char* string
,
2167 void _expect_not_string(
2168 const char* const function
, const char* const parameter
,
2169 const char* const file
, const int line
, const char* string
,
2172 void _expect_memory(
2173 const char* const function
, const char* const parameter
,
2174 const char* const file
, const int line
, const void* const memory
,
2175 const size_t size
, const int count
);
2176 void _expect_not_memory(
2177 const char* const function
, const char* const parameter
,
2178 const char* const file
, const int line
, const void* const memory
,
2179 const size_t size
, const int count
);
2182 const char* const function
, const char* const parameter
,
2183 const char* const file
, const int line
, const int count
);
2185 void _check_expected(
2186 const char * const function_name
, const char * const parameter_name
,
2187 const char* file
, const int line
, const LargestIntegralType value
);
2189 void _will_return(const char * const function_name
, const char * const file
,
2190 const int line
, const LargestIntegralType value
,
2192 void _assert_true(const LargestIntegralType result
,
2193 const char* const expression
,
2194 const char * const file
, const int line
);
2195 void _assert_return_code(const LargestIntegralType result
,
2197 const LargestIntegralType error
,
2198 const char * const expression
,
2199 const char * const file
,
2201 void _assert_int_equal(
2202 const LargestIntegralType a
, const LargestIntegralType b
,
2203 const char * const file
, const int line
);
2204 void _assert_int_not_equal(
2205 const LargestIntegralType a
, const LargestIntegralType b
,
2206 const char * const file
, const int line
);
2207 void _assert_string_equal(const char * const a
, const char * const b
,
2208 const char * const file
, const int line
);
2209 void _assert_string_not_equal(const char * const a
, const char * const b
,
2210 const char *file
, const int line
);
2211 void _assert_memory_equal(const void * const a
, const void * const b
,
2212 const size_t size
, const char* const file
,
2214 void _assert_memory_not_equal(const void * const a
, const void * const b
,
2215 const size_t size
, const char* const file
,
2217 void _assert_in_range(
2218 const LargestIntegralType value
, const LargestIntegralType minimum
,
2219 const LargestIntegralType maximum
, const char* const file
, const int line
);
2220 void _assert_not_in_range(
2221 const LargestIntegralType value
, const LargestIntegralType minimum
,
2222 const LargestIntegralType maximum
, const char* const file
, const int line
);
2223 void _assert_in_set(
2224 const LargestIntegralType value
, const LargestIntegralType values
[],
2225 const size_t number_of_values
, const char* const file
, const int line
);
2226 void _assert_not_in_set(
2227 const LargestIntegralType value
, const LargestIntegralType values
[],
2228 const size_t number_of_values
, const char* const file
, const int line
);
2230 void* _test_malloc(const size_t size
, const char* file
, const int line
);
2231 void* _test_realloc(void *ptr
, const size_t size
, const char* file
, const int line
);
2232 void* _test_calloc(const size_t number_of_elements
, const size_t size
,
2233 const char* file
, const int line
);
2234 void _test_free(void* const ptr
, const char* file
, const int line
);
2236 void _fail(const char * const file
, const int line
);
2238 void _skip(const char * const file
, const int line
);
2241 const char * const function_name
, const UnitTestFunction Function
,
2242 void ** const volatile state
, const UnitTestFunctionType function_type
,
2243 const void* const heap_check_point
);
2244 CMOCKA_DEPRECATED
int _run_tests(const UnitTest
* const tests
,
2245 const size_t number_of_tests
);
2246 CMOCKA_DEPRECATED
int _run_group_tests(const UnitTest
* const tests
,
2247 const size_t number_of_tests
);
2250 int _cmocka_run_group_tests(const char *group_name
,
2251 const struct CMUnitTest
* const tests
,
2252 const size_t num_tests
,
2253 CMFixtureFunction group_setup
,
2254 CMFixtureFunction group_teardown
);
2256 /* Standard output and error print methods. */
2257 void print_message(const char* const format
, ...) CMOCKA_PRINTF_ATTRIBUTE(1, 2);
2258 void print_error(const char* const format
, ...) CMOCKA_PRINTF_ATTRIBUTE(1, 2);
2259 void vprint_message(const char* const format
, va_list args
) CMOCKA_PRINTF_ATTRIBUTE(1, 0);
2260 void vprint_error(const char* const format
, va_list args
) CMOCKA_PRINTF_ATTRIBUTE(1, 0);
2262 enum cm_message_output
{
2270 * @brief Function to set the output format for a test.
2272 * The ouput format for the test can either be set globally using this
2273 * function or overriden with environment variable CMOCKA_MESSAGE_OUTPUT.
2275 * The environment variable can be set to either STDOUT, SUBUNIT, TAP or XML.
2277 * @param[in] output The output format to use for the test.
2280 void cmocka_set_message_output(enum cm_message_output output
);
2284 #endif /* CMOCKA_H_ */