1/*
2 * Copyright 2008 Google Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16#ifndef CMOCKA_H_
17#define CMOCKA_H_
18
19#ifdef _WIN32
20#ifdef _MSC_VER
21
22#define __func__ __FUNCTION__
23
24#ifndef inline
25#define inline __inline
26#endif /* inline */
27
28#if _MSC_VER < 1500
29#ifdef __cplusplus
30extern "C" {
31#endif /* __cplusplus */
32int __stdcall IsDebuggerPresent();
33#ifdef __cplusplus
34} /* extern "C" */
35#endif /* __cplusplus */
36#endif /* _MSC_VER < 1500 */
37#endif /* _MSC_VER */
38#endif /* _WIN32 */
39
40/**
41 * @defgroup cmocka The CMocka API
42 *
43 * These headers or their equivalents should be included prior to including
44 * this header file.
45 * @code
46 * #include <stdarg.h>
47 * #include <stddef.h>
48 * #include <setjmp.h>
49 * @endcode
50 *
51 * This allows test applications to use custom definitions of C standard
52 * library functions and types.
53 *
54 * @{
55 */
56
57/* If __WORDSIZE is not set, try to figure it out and default to 32 bit. */
58#ifndef __WORDSIZE
59#if defined(__x86_64__) && !defined(__ILP32__)
60#define __WORDSIZE 64
61#else
62#define __WORDSIZE 32
63#endif
64#endif
65
66#ifdef DOXYGEN
67/**
68 * Largest integral type. This type should be large enough to hold any
69 * pointer or integer supported by the compiler.
70 */
71typedef uintmax_t LargestIntegralType;
72#else /* DOXGEN */
73#ifndef LargestIntegralType
74#if __WORDSIZE == 64
75#define LargestIntegralType unsigned long int
76#else
77#define LargestIntegralType unsigned long long int
78#endif
79#endif /* LargestIntegralType */
80#endif /* DOXYGEN */
81
82/* Printf format used to display LargestIntegralType. */
83#ifndef LargestIntegralTypePrintfFormat
84#ifdef _WIN32
85#define LargestIntegralTypePrintfFormat "0x%I64x"
86#else
87#if __WORDSIZE == 64
88#define LargestIntegralTypePrintfFormat "%#lx"
89#else
90#define LargestIntegralTypePrintfFormat "%#llx"
91#endif
92#endif /* _WIN32 */
93#endif /* LargestIntegralTypePrintfFormat */
94
95/* Perform an unsigned cast to LargestIntegralType. */
96#define cast_to_largest_integral_type(value) ((LargestIntegralType)(value))
97
98/* Smallest integral type capable of holding a pointer. */
99#if !defined(_UINTPTR_T) && !defined(_UINTPTR_T_DEFINED)
100#if defined(_WIN32)
101/* WIN32 is an ILP32 platform */
102typedef unsigned int uintptr_t;
103#elif defined(_WIN64)
104typedef unsigned long int uintptr_t
105#else /* _WIN32 */
106
107/* ILP32 and LP64 platforms */
108#ifdef __WORDSIZE /* glibc */
109#if __WORDSIZE == 64
110typedef unsigned long int uintptr_t;
111#else
112typedef unsigned int uintptr_t;
113#endif /* __WORDSIZE == 64 */
114#else /* __WORDSIZE */
115#if defined(_LP64) || defined(_I32LPx)
116typedef unsigned long int uintptr_t;
117#else
118typedef unsigned int uintptr_t;
119#endif
120#endif /* __WORDSIZE */
121#endif /* _WIN32 */
122
123#define _UINTPTR_T
124#define _UINTPTR_T_DEFINED
125#endif /* !defined(_UINTPTR_T) || !defined(_UINTPTR_T_DEFINED) */
126
127/* Perform an unsigned cast to uintptr_t. */
128#define cast_to_pointer_integral_type(value) ((uintptr_t)((size_t)(value)))
129
130/* Perform a cast of a pointer to LargestIntegralType */
131#define cast_ptr_to_largest_integral_type(value) \
132 cast_to_largest_integral_type(cast_to_pointer_integral_type(value))
133
134/* GCC have printf type attribute check. */
135#ifdef __GNUC__
136#define CMOCKA_PRINTF_ATTRIBUTE(a, b) \
137 __attribute__((__format__(__printf__, a, b)))
138#else
139#define CMOCKA_PRINTF_ATTRIBUTE(a, b)
140#endif /* __GNUC__ */
141
142#if defined(__GNUC__)
143#define CMOCKA_DEPRECATED __attribute__((deprecated))
144#elif defined(_MSC_VER)
145#define CMOCKA_DEPRECATED __declspec(deprecated)
146#else
147#define CMOCKA_DEPRECATED
148#endif
149
150/**
151 * @defgroup cmocka_mock Mock Objects
152 * @ingroup cmocka
153 *
154 * Mock objects mock objects are simulated objects that mimic the behavior of
155 * real objects. Instead of calling the real objects, the tested object calls a
156 * mock object that merely asserts that the correct methods were called, with
157 * the expected parameters, in the correct order.
158 *
159 * <ul>
160 * <li><strong>will_return(function, value)</strong> - The will_return() macro
161 * pushes a value onto a stack of mock values. This macro is intended to be
162 * used by the unit test itself, while programming the behaviour of the mocked
163 * object.</li>
164 *
165 * <li><strong>mock()</strong> - the mock macro pops a value from a stack of
166 * test values. The user of the mock() macro is the mocked object that uses it
167 * to learn how it should behave.</li>
168 * </ul>
169 *
170 * Because the will_return() and mock() are intended to be used in pairs, the
171 * cmocka library would fail the test if there are more values pushed onto the
172 * stack using will_return() than consumed with mock() and vice-versa.
173 *
174 * The following unit test stub illustrates how would a unit test instruct the
175 * mock object to return a particular value:
176 *
177 * @code
178 * will_return(chef_cook, "hotdog");
179 * will_return(chef_cook, 0);
180 * @endcode
181 *
182 * Now the mock object can check if the parameter it received is the parameter
183 * which is expected by the test driver. This can be done the following way:
184 *
185 * @code
186 * int chef_cook(const char *order, char **dish_out)
187 * {
188 * check_expected(order);
189 * }
190 * @endcode
191 *
192 * For a complete example please at a look
193 * <a
194 * href="http://git.cryptomilk.org/projects/cmocka.git/tree/example/chef_wrap/waiter_test_wrap.c">here</a>.
195 *
196 * @{
197 */
198
199#ifdef DOXYGEN
200/**
201 * @brief Retrieve a return value of the current function.
202 *
203 * @return The value which was stored to return by this function.
204 *
205 * @see will_return()
206 */
207LargestIntegralType mock(void);
208#else
209#define mock() _mock(__func__, __FILE__, __LINE__)
210#endif
211
212#ifdef DOXYGEN
213/**
214 * @brief Retrieve a typed return value of the current function.
215 *
216 * The value would be casted to type internally to avoid having the
217 * caller to do the cast manually.
218 *
219 * @param[in] #type The expected type of the return value
220 *
221 * @return The value which was stored to return by this function.
222 *
223 * @code
224 * int param;
225 *
226 * param = mock_type(int);
227 * @endcode
228 *
229 * @see will_return()
230 * @see mock()
231 * @see mock_ptr_type()
232 */
233#type mock_type(#type);
234#else
235#define mock_type(type) ((type)mock())
236#endif
237
238#ifdef DOXYGEN
239/**
240 * @brief Retrieve a typed return value of the current function.
241 *
242 * The value would be casted to type internally to avoid having the
243 * caller to do the cast manually but also casted to uintptr_t to make
244 * sure the result has a valid size to be used as a pointer.
245 *
246 * @param[in] #type The expected type of the return value
247 *
248 * @return The value which was stored to return by this function.
249 *
250 * @code
251 * char *param;
252 *
253 * param = mock_ptr_type(char *);
254 * @endcode
255 *
256 * @see will_return()
257 * @see mock()
258 * @see mock_type()
259 */
260type mock_ptr_type(#type);
261#else
262#define mock_ptr_type(type) ((type)(uintptr_t)mock())
263#endif
264
265#ifdef DOXYGEN
266/**
267 * @brief Store a value to be returned by mock() later.
268 *
269 * @param[in] #function The function which should return the given value.
270 *
271 * @param[in] value The value to be returned by mock().
272 *
273 * @code
274 * int return_integer(void)
275 * {
276 * return (int)mock();
277 * }
278 *
279 * static void test_integer_return(void **state)
280 * {
281 * will_return(return_integer, 42);
282 *
283 * assert_int_equal(my_function_calling_return_integer(), 42);
284 * }
285 * @endcode
286 *
287 * @see mock()
288 * @see will_return_count()
289 */
290void will_return(#function, LargestIntegralType value);
291#else
292#define will_return(function, value) \
293 _will_return(#function, __FILE__, __LINE__, \
294 cast_to_largest_integral_type(value), 1)
295#endif
296
297#ifdef DOXYGEN
298/**
299 * @brief Store a value to be returned by mock() later.
300 *
301 * @param[in] #function The function which should return the given value.
302 *
303 * @param[in] value The value to be returned by mock().
304 *
305 * @param[in] count The parameter returns the number of times the value should
306 * be returned by mock(). If count is set to -1 the value will
307 * always be returned.
308 *
309 * @see mock()
310 */
311void will_return_count(#function, LargestIntegralType value, int count);
312#else
313#define will_return_count(function, value, count) \
314 _will_return(#function, __FILE__, __LINE__, \
315 cast_to_largest_integral_type(value), count)
316#endif
317
318#ifdef DOXYGEN
319/**
320 * @brief Store a value that will be always returned by mock().
321 *
322 * @param[in] #function The function which should return the given value.
323 *
324 * @param[in] #value The value to be returned by mock().
325 *
326 * This is equivalent to:
327 * @code
328 * will_return_count(function, value, -1);
329 * @endcode
330 *
331 * @see will_return_count()
332 * @see mock()
333 */
334void will_return_always(#function, LargestIntegralType value);
335#else
336#define will_return_always(function, value) \
337 will_return_count(function, (value), -1)
338#endif
339
340/** @} */
341
342/**
343 * @defgroup cmocka_param Checking Parameters
344 * @ingroup cmocka
345 *
346 * Functionality to store expected values for mock function parameters.
347 *
348 * In addition to storing the return values of mock functions, cmocka provides
349 * functionality to store expected values for mock function parameters using
350 * the expect_*() functions provided. A mock function parameter can then be
351 * validated using the check_expected() macro.
352 *
353 * Successive calls to expect_*() macros for a parameter queues values to check
354 * the specified parameter. check_expected() checks a function parameter
355 * against the next value queued using expect_*(), if the parameter check fails
356 * a test failure is signalled. In addition if check_expected() is called and
357 * no more parameter values are queued a test failure occurs.
358 *
359 * The following test stub illustrates how to do this. First is the the function
360 * we call in the test driver:
361 *
362 * @code
363 * static void test_driver(void **state)
364 * {
365 * expect_string(chef_cook, order, "hotdog");
366 * }
367 * @endcode
368 *
369 * Now the chef_cook function can check if the parameter we got passed is the
370 * parameter which is expected by the test driver. This can be done the
371 * following way:
372 *
373 * @code
374 * int chef_cook(const char *order, char **dish_out)
375 * {
376 * check_expected(order);
377 * }
378 * @endcode
379 *
380 * For a complete example please at a look at
381 * <a
382 * href="http://git.cryptomilk.org/projects/cmocka.git/tree/example/chef_wrap/waiter_test_wrap.c">here</a>
383 *
384 * @{
385 */
386
387/*
388 * Add a custom parameter checking function. If the event parameter is NULL
389 * the event structure is allocated internally by this function. If event
390 * parameter is provided it must be allocated on the heap and doesn't need to
391 * be deallocated by the caller.
392 */
393#ifdef DOXYGEN
394/**
395 * @brief Add a custom parameter checking function.
396 *
397 * If the event parameter is NULL the event structure is allocated internally
398 * by this function. If the parameter is provided it must be allocated on the
399 * heap and doesn't need to be deallocated by the caller.
400 *
401 * @param[in] #function The function to add a custom parameter checking
402 * function for.
403 *
404 * @param[in] #parameter The parameters passed to the function.
405 *
406 * @param[in] #check_function The check function to call.
407 *
408 * @param[in] check_data The data to pass to the check function.
409 */
410void expect_check(#function, #parameter, #check_function,
411 const void* check_data);
412#else
413#define expect_check(function, parameter, check_function, check_data) \
414 _expect_check(#function, #parameter, __FILE__, __LINE__, check_function, \
415 cast_to_largest_integral_type(check_data), NULL, 1)
416#endif
417
418#ifdef DOXYGEN
419/**
420 * @brief Add an event to check if the parameter value is part of the provided
421 * array.
422 *
423 * The event is triggered by calling check_expected() in the mocked function.
424 *
425 * @param[in] #function The function to add the check for.
426 *
427 * @param[in] #parameter The name of the parameter passed to the function.
428 *
429 * @param[in] value_array[] The array to check for the value.
430 *
431 * @see check_expected().
432 */
433void expect_in_set(#function, #parameter, LargestIntegralType value_array[]);
434#else
435#define expect_in_set(function, parameter, value_array) \
436 expect_in_set_count(function, parameter, value_array, 1)
437#endif
438
439#ifdef DOXYGEN
440/**
441 * @brief Add an event to check if the parameter value is part of the provided
442 * array.
443 *
444 * The event is triggered by calling check_expected() in the mocked function.
445 *
446 * @param[in] #function The function to add the check for.
447 *
448 * @param[in] #parameter The name of the parameter passed to the function.
449 *
450 * @param[in] value_array[] The array to check for the value.
451 *
452 * @param[in] count The count parameter returns the number of times the value
453 * should be returned by check_expected(). If count is set
454 * to -1 the value will always be returned.
455 *
456 * @see check_expected().
457 */
458void expect_in_set_count(#function, #parameter,
459 LargestIntegralType value_array[], size_t count);
460#else
461#define expect_in_set_count(function, parameter, value_array, count) \
462 _expect_in_set(#function, #parameter, __FILE__, __LINE__, value_array, \
463 sizeof(value_array) / sizeof((value_array)[0]), count)
464#endif
465
466#ifdef DOXYGEN
467/**
468 * @brief Add an event to check if the parameter value is not part of the
469 * provided array.
470 *
471 * The event is triggered by calling check_expected() in the mocked function.
472 *
473 * @param[in] #function The function to add the check for.
474 *
475 * @param[in] #parameter The name of the parameter passed to the function.
476 *
477 * @param[in] value_array[] The array to check for the value.
478 *
479 * @see check_expected().
480 */
481void expect_not_in_set(#function, #parameter,
482 LargestIntegralType value_array[]);
483#else
484#define expect_not_in_set(function, parameter, value_array) \
485 expect_not_in_set_count(function, parameter, value_array, 1)
486#endif
487
488#ifdef DOXYGEN
489/**
490 * @brief Add an event to check if the parameter value is not part of the
491 * provided array.
492 *
493 * The event is triggered by calling check_expected() in the mocked function.
494 *
495 * @param[in] #function The function to add the check for.
496 *
497 * @param[in] #parameter The name of the parameter passed to the function.
498 *
499 * @param[in] value_array[] The array to check for the value.
500 *
501 * @param[in] count The count parameter returns the number of times the value
502 * should be returned by check_expected(). If count is set
503 * to -1 the value will always be returned.
504 *
505 * @see check_expected().
506 */
507void expect_not_in_set_count(#function, #parameter,
508 LargestIntegralType value_array[], size_t count);
509#else
510#define expect_not_in_set_count(function, parameter, value_array, count) \
511 _expect_not_in_set(#function, #parameter, __FILE__, __LINE__, value_array, \
512 sizeof(value_array) / sizeof((value_array)[0]), count)
513#endif
514
515#ifdef DOXYGEN
516/**
517 * @brief Add an event to check a parameter is inside a numerical range.
518 * The check would succeed if minimum <= value <= maximum.
519 *
520 * The event is triggered by calling check_expected() in the mocked function.
521 *
522 * @param[in] #function The function to add the check for.
523 *
524 * @param[in] #parameter The name of the parameter passed to the function.
525 *
526 * @param[in] minimum The lower boundary of the interval to check against.
527 *
528 * @param[in] maximum The upper boundary of the interval to check against.
529 *
530 * @see check_expected().
531 */
532void expect_in_range(#function, #parameter, LargestIntegralType minimum,
533 LargestIntegralType maximum);
534#else
535#define expect_in_range(function, parameter, minimum, maximum) \
536 expect_in_range_count(function, parameter, minimum, maximum, 1)
537#endif
538
539#ifdef DOXYGEN
540/**
541 * @brief Add an event to repeatedly check a parameter is inside a
542 * numerical range. The check would succeed if minimum <= value <= maximum.
543 *
544 * The event is triggered by calling check_expected() in the mocked function.
545 *
546 * @param[in] #function The function to add the check for.
547 *
548 * @param[in] #parameter The name of the parameter passed to the function.
549 *
550 * @param[in] minimum The lower boundary of the interval to check against.
551 *
552 * @param[in] maximum The upper boundary of the interval to check against.
553 *
554 * @param[in] count The count parameter returns the number of times the value
555 * should be returned by check_expected(). If count is set
556 * to -1 the value will always be returned.
557 *
558 * @see check_expected().
559 */
560void expect_in_range_count(#function, #parameter, LargestIntegralType minimum,
561 LargestIntegralType maximum, size_t count);
562#else
563#define expect_in_range_count(function, parameter, minimum, maximum, count) \
564 _expect_in_range(#function, #parameter, __FILE__, __LINE__, minimum, \
565 maximum, count)
566#endif
567
568#ifdef DOXYGEN
569/**
570 * @brief Add an event to check a parameter is outside a numerical range.
571 * The check would succeed if minimum > value > maximum.
572 *
573 * The event is triggered by calling check_expected() in the mocked function.
574 *
575 * @param[in] #function The function to add the check for.
576 *
577 * @param[in] #parameter The name of the parameter passed to the function.
578 *
579 * @param[in] minimum The lower boundary of the interval to check against.
580 *
581 * @param[in] maximum The upper boundary of the interval to check against.
582 *
583 * @see check_expected().
584 */
585void expect_not_in_range(#function, #parameter, LargestIntegralType minimum,
586 LargestIntegralType maximum);
587#else
588#define expect_not_in_range(function, parameter, minimum, maximum) \
589 expect_not_in_range_count(function, parameter, minimum, maximum, 1)
590#endif
591
592#ifdef DOXYGEN
593/**
594 * @brief Add an event to repeatedly check a parameter is outside a
595 * numerical range. The check would succeed if minimum > value > maximum.
596 *
597 * The event is triggered by calling check_expected() in the mocked function.
598 *
599 * @param[in] #function The function to add the check for.
600 *
601 * @param[in] #parameter The name of the parameter passed to the function.
602 *
603 * @param[in] minimum The lower boundary of the interval to check against.
604 *
605 * @param[in] maximum The upper boundary of the interval to check against.
606 *
607 * @param[in] count The count parameter returns the number of times the value
608 * should be returned by check_expected(). If count is set
609 * to -1 the value will always be returned.
610 *
611 * @see check_expected().
612 */
613void expect_not_in_range_count(#function, #parameter,
614 LargestIntegralType minimum,
615 LargestIntegralType maximum, size_t count);
616#else
617#define expect_not_in_range_count(function, parameter, minimum, maximum, \
618 count) \
619 _expect_not_in_range(#function, #parameter, __FILE__, __LINE__, minimum, \
620 maximum, count)
621#endif
622
623#ifdef DOXYGEN
624/**
625 * @brief Add an event to check if a parameter is the given value.
626 *
627 * The event is triggered by calling check_expected() in the mocked function.
628 *
629 * @param[in] #function The function to add the check for.
630 *
631 * @param[in] #parameter The name of the parameter passed to the function.
632 *
633 * @param[in] value The value to check.
634 *
635 * @see check_expected().
636 */
637void expect_value(#function, #parameter, LargestIntegralType value);
638#else
639#define expect_value(function, parameter, value) \
640 expect_value_count(function, parameter, value, 1)
641#endif
642
643#ifdef DOXYGEN
644/**
645 * @brief Add an event to repeatedly check if a parameter is the given value.
646 *
647 * The event is triggered by calling check_expected() in the mocked function.
648 *
649 * @param[in] #function The function to add the check for.
650 *
651 * @param[in] #parameter The name of the parameter passed to the function.
652 *
653 * @param[in] value The value to check.
654 *
655 * @param[in] count The count parameter returns the number of times the value
656 * should be returned by check_expected(). If count is set
657 * to -1 the value will always be returned.
658 *
659 * @see check_expected().
660 */
661void expect_value_count(#function, #parameter, LargestIntegralType value,
662 size_t count);
663#else
664#define expect_value_count(function, parameter, value, count) \
665 _expect_value(#function, #parameter, __FILE__, __LINE__, \
666 cast_to_largest_integral_type(value), count)
667#endif
668
669#ifdef DOXYGEN
670/**
671 * @brief Add an event to check if a parameter isn't the given value.
672 *
673 * The event is triggered by calling check_expected() in the mocked function.
674 *
675 * @param[in] #function The function to add the check for.
676 *
677 * @param[in] #parameter The name of the parameter passed to the function.
678 *
679 * @param[in] value The value to check.
680 *
681 * @see check_expected().
682 */
683void expect_not_value(#function, #parameter, LargestIntegralType value);
684#else
685#define expect_not_value(function, parameter, value) \
686 expect_not_value_count(function, parameter, value, 1)
687#endif
688
689#ifdef DOXYGEN
690/**
691 * @brief Add an event to repeatedly check if a parameter isn't the given value.
692 *
693 * The event is triggered by calling check_expected() in the mocked function.
694 *
695 * @param[in] #function The function to add the check for.
696 *
697 * @param[in] #parameter The name of the parameter passed to the function.
698 *
699 * @param[in] value The value to check.
700 *
701 * @param[in] count The count parameter returns the number of times the value
702 * should be returned by check_expected(). If count is set
703 * to -1 the value will always be returned.
704 *
705 * @see check_expected().
706 */
707void expect_not_value_count(#function, #parameter, LargestIntegralType value,
708 size_t count);
709#else
710#define expect_not_value_count(function, parameter, value, count) \
711 _expect_not_value(#function, #parameter, __FILE__, __LINE__, \
712 cast_to_largest_integral_type(value), count)
713#endif
714
715#ifdef DOXYGEN
716/**
717 * @brief Add an event to check if the parameter value is equal to the
718 * provided string.
719 *
720 * The event is triggered by calling check_expected() in the mocked function.
721 *
722 * @param[in] #function The function to add the check for.
723 *
724 * @param[in] #parameter The name of the parameter passed to the function.
725 *
726 * @param[in] string The string value to compare.
727 *
728 * @see check_expected().
729 */
730void expect_string(#function, #parameter, const char* string);
731#else
732#define expect_string(function, parameter, string) \
733 expect_string_count(function, parameter, string, 1)
734#endif
735
736#ifdef DOXYGEN
737/**
738 * @brief Add an event to check if the parameter value is equal to the
739 * provided string.
740 *
741 * The event is triggered by calling check_expected() in the mocked function.
742 *
743 * @param[in] #function The function to add the check for.
744 *
745 * @param[in] #parameter The name of the parameter passed to the function.
746 *
747 * @param[in] string The string value to compare.
748 *
749 * @param[in] count The count parameter returns the number of times the value
750 * should be returned by check_expected(). If count is set
751 * to -1 the value will always be returned.
752 *
753 * @see check_expected().
754 */
755void expect_string_count(#function, #parameter, const char* string,
756 size_t count);
757#else
758#define expect_string_count(function, parameter, string, count) \
759 _expect_string(#function, #parameter, __FILE__, __LINE__, \
760 (const char*)(string), count)
761#endif
762
763#ifdef DOXYGEN
764/**
765 * @brief Add an event to check if the parameter value isn't equal to the
766 * provided string.
767 *
768 * The event is triggered by calling check_expected() in the mocked function.
769 *
770 * @param[in] #function The function to add the check for.
771 *
772 * @param[in] #parameter The name of the parameter passed to the function.
773 *
774 * @param[in] string The string value to compare.
775 *
776 * @see check_expected().
777 */
778void expect_not_string(#function, #parameter, const char* string);
779#else
780#define expect_not_string(function, parameter, string) \
781 expect_not_string_count(function, parameter, string, 1)
782#endif
783
784#ifdef DOXYGEN
785/**
786 * @brief Add an event to check if the parameter value isn't equal to the
787 * provided string.
788 *
789 * The event is triggered by calling check_expected() in the mocked function.
790 *
791 * @param[in] #function The function to add the check for.
792 *
793 * @param[in] #parameter The name of the parameter passed to the function.
794 *
795 * @param[in] string The string value to compare.
796 *
797 * @param[in] count The count parameter returns the number of times the value
798 * should be returned by check_expected(). If count is set
799 * to -1 the value will always be returned.
800 *
801 * @see check_expected().
802 */
803void expect_not_string_count(#function, #parameter, const char* string,
804 size_t count);
805#else
806#define expect_not_string_count(function, parameter, string, count) \
807 _expect_not_string(#function, #parameter, __FILE__, __LINE__, \
808 (const char*)(string), count)
809#endif
810
811#ifdef DOXYGEN
812/**
813 * @brief Add an event to check if the parameter does match an area of memory.
814 *
815 * The event is triggered by calling check_expected() in the mocked function.
816 *
817 * @param[in] #function The function to add the check for.
818 *
819 * @param[in] #parameter The name of the parameter passed to the function.
820 *
821 * @param[in] memory The memory to compare.
822 *
823 * @param[in] size The size of the memory to compare.
824 *
825 * @see check_expected().
826 */
827void expect_memory(#function, #parameter, void* memory, size_t size);
828#else
829#define expect_memory(function, parameter, memory, size) \
830 expect_memory_count(function, parameter, memory, size, 1)
831#endif
832
833#ifdef DOXYGEN
834/**
835 * @brief Add an event to repeatedly check if the parameter does match an area
836 * of memory.
837 *
838 * The event is triggered by calling check_expected() in the mocked function.
839 *
840 * @param[in] #function The function to add the check for.
841 *
842 * @param[in] #parameter The name of the parameter passed to the function.
843 *
844 * @param[in] memory The memory to compare.
845 *
846 * @param[in] size The size of the memory to compare.
847 *
848 * @param[in] count The count parameter returns the number of times the value
849 * should be returned by check_expected(). If count is set
850 * to -1 the value will always be returned.
851 *
852 * @see check_expected().
853 */
854void expect_memory_count(#function, #parameter, void* memory, size_t size,
855 size_t count);
856#else
857#define expect_memory_count(function, parameter, memory, size, count) \
858 _expect_memory(#function, #parameter, __FILE__, __LINE__, \
859 (const void*)(memory), size, count)
860#endif
861
862#ifdef DOXYGEN
863/**
864 * @brief Add an event to check if the parameter doesn't match an area of
865 * memory.
866 *
867 * The event is triggered by calling check_expected() in the mocked function.
868 *
869 * @param[in] #function The function to add the check for.
870 *
871 * @param[in] #parameter The name of the parameter passed to the function.
872 *
873 * @param[in] memory The memory to compare.
874 *
875 * @param[in] size The size of the memory to compare.
876 *
877 * @see check_expected().
878 */
879void expect_not_memory(#function, #parameter, void* memory, size_t size);
880#else
881#define expect_not_memory(function, parameter, memory, size) \
882 expect_not_memory_count(function, parameter, memory, size, 1)
883#endif
884
885#ifdef DOXYGEN
886/**
887 * @brief Add an event to repeatedly check if the parameter doesn't match an
888 * area of memory.
889 *
890 * The event is triggered by calling check_expected() in the mocked function.
891 *
892 * @param[in] #function The function to add the check for.
893 *
894 * @param[in] #parameter The name of the parameter passed to the function.
895 *
896 * @param[in] memory The memory to compare.
897 *
898 * @param[in] size The size of the memory to compare.
899 *
900 * @param[in] count The count parameter returns the number of times the value
901 * should be returned by check_expected(). If count is set
902 * to -1 the value will always be returned.
903 *
904 * @see check_expected().
905 */
906void expect_not_memory_count(#function, #parameter, void* memory, size_t size,
907 size_t count);
908#else
909#define expect_not_memory_count(function, parameter, memory, size, count) \
910 _expect_not_memory(#function, #parameter, __FILE__, __LINE__, \
911 (const void*)(memory), size, count)
912#endif
913
914#ifdef DOXYGEN
915/**
916 * @brief Add an event to check if a parameter (of any value) has been passed.
917 *
918 * The event is triggered by calling check_expected() in the mocked function.
919 *
920 * @param[in] #function The function to add the check for.
921 *
922 * @param[in] #parameter The name of the parameter passed to the function.
923 *
924 * @see check_expected().
925 */
926void expect_any(#function, #parameter);
927#else
928#define expect_any(function, parameter) expect_any_count(function, parameter, 1)
929#endif
930
931#ifdef DOXYGEN
932/**
933 * @brief Add an event to repeatedly check if a parameter (of any value) has
934 * been passed.
935 *
936 * The event is triggered by calling check_expected() in the mocked function.
937 *
938 * @param[in] #function The function to add the check for.
939 *
940 * @param[in] #parameter The name of the parameter passed to the function.
941 *
942 * @param[in] count The count parameter returns the number of times the value
943 * should be returned by check_expected(). If count is set
944 * to -1 the value will always be returned.
945 *
946 * @see check_expected().
947 */
948void expect_any_count(#function, #parameter, size_t count);
949#else
950#define expect_any_count(function, parameter, count) \
951 _expect_any(#function, #parameter, __FILE__, __LINE__, count)
952#endif
953
954#ifdef DOXYGEN
955/**
956 * @brief Determine whether a function parameter is correct.
957 *
958 * This ensures the next value queued by one of the expect_*() macros matches
959 * the specified variable.
960 *
961 * This function needs to be called in the mock object.
962 *
963 * @param[in] #parameter The parameter to check.
964 */
965void check_expected(#parameter);
966#else
967#define check_expected(parameter) \
968 _check_expected(__func__, #parameter, __FILE__, __LINE__, \
969 cast_to_largest_integral_type(parameter))
970#endif
971
972#ifdef DOXYGEN
973/**
974 * @brief Determine whether a function parameter is correct.
975 *
976 * This ensures the next value queued by one of the expect_*() macros matches
977 * the specified variable.
978 *
979 * This function needs to be called in the mock object.
980 *
981 * @param[in] #parameter The pointer to check.
982 */
983void check_expected_ptr(#parameter);
984#else
985#define check_expected_ptr(parameter) \
986 _check_expected(__func__, #parameter, __FILE__, __LINE__, \
987 cast_ptr_to_largest_integral_type(parameter))
988#endif
989
990/** @} */
991
992/**
993 * @defgroup cmocka_asserts Assert Macros
994 * @ingroup cmocka
995 *
996 * This is a set of useful assert macros like the standard C libary's
997 * assert(3) macro.
998 *
999 * On an assertion failure a cmocka assert macro will write the failure to the
1000 * standard error stream and signal a test failure. Due to limitations of the C
1001 * language the general C standard library assert() and cmocka's assert_true()
1002 * and assert_false() macros can only display the expression that caused the
1003 * assert failure. cmocka's type specific assert macros, assert_{type}_equal()
1004 * and assert_{type}_not_equal(), display the data that caused the assertion
1005 * failure which increases data visibility aiding debugging of failing test
1006 * cases.
1007 *
1008 * @{
1009 */
1010
1011#ifdef DOXYGEN
1012/**
1013 * @brief Assert that the given expression is true.
1014 *
1015 * The function prints an error message to standard error and terminates the
1016 * test by calling fail() if expression is false (i.e., compares equal to
1017 * zero).
1018 *
1019 * @param[in] expression The expression to evaluate.
1020 *
1021 * @see assert_int_equal()
1022 * @see assert_string_equal()
1023 */
1024void assert_true(scalar expression);
1025#else
1026#define assert_true(c) \
1027 _assert_true(cast_to_largest_integral_type(c), #c, __FILE__, __LINE__)
1028#endif
1029
1030#ifdef DOXYGEN
1031/**
1032 * @brief Assert that the given expression is false.
1033 *
1034 * The function prints an error message to standard error and terminates the
1035 * test by calling fail() if expression is true.
1036 *
1037 * @param[in] expression The expression to evaluate.
1038 *
1039 * @see assert_int_equal()
1040 * @see assert_string_equal()
1041 */
1042void assert_false(scalar expression);
1043#else
1044#define assert_false(c) \
1045 _assert_true(!(cast_to_largest_integral_type(c)), #c, __FILE__, __LINE__)
1046#endif
1047
1048#ifdef DOXYGEN
1049/**
1050 * @brief Assert that the return_code is greater than or equal to 0.
1051 *
1052 * The function prints an error message to standard error and terminates the
1053 * test by calling fail() if the return code is smaller than 0. If the function
1054 * you check sets an errno if it fails you can pass it to the function and
1055 * it will be printed as part of the error message.
1056 *
1057 * @param[in] rc The return code to evaluate.
1058 *
1059 * @param[in] error Pass errno here or 0.
1060 */
1061void assert_return_code(int rc, int error);
1062#else
1063#define assert_return_code(rc, error) \
1064 _assert_return_code(cast_to_largest_integral_type(rc), sizeof(rc), \
1065 cast_to_largest_integral_type(error), #rc, __FILE__, \
1066 __LINE__)
1067#endif
1068
1069#ifdef DOXYGEN
1070/**
1071 * @brief Assert that the given pointer is non-NULL.
1072 *
1073 * The function prints an error message to standard error and terminates the
1074 * test by calling fail() if the pointer is non-NULL.
1075 *
1076 * @param[in] pointer The pointer to evaluate.
1077 *
1078 * @see assert_null()
1079 */
1080void assert_non_null(void* pointer);
1081#else
1082#define assert_non_null(c) \
1083 _assert_true(cast_ptr_to_largest_integral_type(c), #c, __FILE__, __LINE__)
1084#endif
1085
1086#ifdef DOXYGEN
1087/**
1088 * @brief Assert that the given pointer is NULL.
1089 *
1090 * The function prints an error message to standard error and terminates the
1091 * test by calling fail() if the pointer is non-NULL.
1092 *
1093 * @param[in] pointer The pointer to evaluate.
1094 *
1095 * @see assert_non_null()
1096 */
1097void assert_null(void* pointer);
1098#else
1099#define assert_null(c) \
1100 _assert_true(!(cast_ptr_to_largest_integral_type(c)), #c, __FILE__, \
1101 __LINE__)
1102#endif
1103
1104#ifdef DOXYGEN
1105/**
1106 * @brief Assert that the two given pointers are equal.
1107 *
1108 * The function prints an error message and terminates the test by calling
1109 * fail() if the pointers are not equal.
1110 *
1111 * @param[in] a The first pointer to compare.
1112 *
1113 * @param[in] b The pointer to compare against the first one.
1114 */
1115void assert_ptr_equal(void* a, void* b);
1116#else
1117#define assert_ptr_equal(a, b) \
1118 _assert_int_equal(cast_ptr_to_largest_integral_type(a), \
1119 cast_ptr_to_largest_integral_type(b), __FILE__, \
1120 __LINE__)
1121#endif
1122
1123#ifdef DOXYGEN
1124/**
1125 * @brief Assert that the two given pointers are not equal.
1126 *
1127 * The function prints an error message and terminates the test by calling
1128 * fail() if the pointers are equal.
1129 *
1130 * @param[in] a The first pointer to compare.
1131 *
1132 * @param[in] b The pointer to compare against the first one.
1133 */
1134void assert_ptr_not_equal(void* a, void* b);
1135#else
1136#define assert_ptr_not_equal(a, b) \
1137 _assert_int_not_equal(cast_ptr_to_largest_integral_type(a), \
1138 cast_ptr_to_largest_integral_type(b), __FILE__, \
1139 __LINE__)
1140#endif
1141
1142#ifdef DOXYGEN
1143/**
1144 * @brief Assert that the two given integers are equal.
1145 *
1146 * The function prints an error message to standard error and terminates the
1147 * test by calling fail() if the integers are not equal.
1148 *
1149 * @param[in] a The first integer to compare.
1150 *
1151 * @param[in] b The integer to compare against the first one.
1152 */
1153void assert_int_equal(int a, int b);
1154#else
1155#define assert_int_equal(a, b) \
1156 _assert_int_equal(cast_to_largest_integral_type(a), \
1157 cast_to_largest_integral_type(b), __FILE__, __LINE__)
1158#endif
1159
1160#ifdef DOXYGEN
1161/**
1162 * @brief Assert that the two given integers are not equal.
1163 *
1164 * The function prints an error message to standard error and terminates the
1165 * test by calling fail() if the integers are equal.
1166 *
1167 * @param[in] a The first integer to compare.
1168 *
1169 * @param[in] b The integer to compare against the first one.
1170 *
1171 * @see assert_int_equal()
1172 */
1173void assert_int_not_equal(int a, int b);
1174#else
1175#define assert_int_not_equal(a, b) \
1176 _assert_int_not_equal(cast_to_largest_integral_type(a), \
1177 cast_to_largest_integral_type(b), __FILE__, \
1178 __LINE__)
1179#endif
1180
1181#ifdef DOXYGEN
1182/**
1183 * @brief Assert that the two given strings are equal.
1184 *
1185 * The function prints an error message to standard error and terminates the
1186 * test by calling fail() if the strings are not equal.
1187 *
1188 * @param[in] a The string to check.
1189 *
1190 * @param[in] b The other string to compare.
1191 */
1192void assert_string_equal(const char* a, const char* b);
1193#else
1194#define assert_string_equal(a, b) \
1195 _assert_string_equal((const char*)(a), (const char*)(b), __FILE__, __LINE__)
1196#endif
1197
1198#ifdef DOXYGEN
1199/**
1200 * @brief Assert that the two given strings are not equal.
1201 *
1202 * The function prints an error message to standard error and terminates the
1203 * test by calling fail() if the strings are equal.
1204 *
1205 * @param[in] a The string to check.
1206 *
1207 * @param[in] b The other string to compare.
1208 */
1209void assert_string_not_equal(const char* a, const char* b);
1210#else
1211#define assert_string_not_equal(a, b) \
1212 _assert_string_not_equal((const char*)(a), (const char*)(b), __FILE__, \
1213 __LINE__)
1214#endif
1215
1216#ifdef DOXYGEN
1217/**
1218 * @brief Assert that the two given areas of memory are equal, otherwise fail.
1219 *
1220 * The function prints an error message to standard error and terminates the
1221 * test by calling fail() if the memory is not equal.
1222 *
1223 * @param[in] a The first memory area to compare
1224 * (interpreted as unsigned char).
1225 *
1226 * @param[in] b The second memory area to compare
1227 * (interpreted as unsigned char).
1228 *
1229 * @param[in] size The first n bytes of the memory areas to compare.
1230 */
1231void assert_memory_equal(const void* a, const void* b, size_t size);
1232#else
1233#define assert_memory_equal(a, b, size) \
1234 _assert_memory_equal((const void*)(a), (const void*)(b), size, __FILE__, \
1235 __LINE__)
1236#endif
1237
1238#ifdef DOXYGEN
1239/**
1240 * @brief Assert that the two given areas of memory are not equal.
1241 *
1242 * The function prints an error message to standard error and terminates the
1243 * test by calling fail() if the memory is equal.
1244 *
1245 * @param[in] a The first memory area to compare
1246 * (interpreted as unsigned char).
1247 *
1248 * @param[in] b The second memory area to compare
1249 * (interpreted as unsigned char).
1250 *
1251 * @param[in] size The first n bytes of the memory areas to compare.
1252 */
1253void assert_memory_not_equal(const void* a, const void* b, size_t size);
1254#else
1255#define assert_memory_not_equal(a, b, size) \
1256 _assert_memory_not_equal((const void*)(a), (const void*)(b), size, \
1257 __FILE__, __LINE__)
1258#endif
1259
1260#ifdef DOXYGEN
1261/**
1262 * @brief Assert that the specified value is not smaller than the minimum
1263 * and and not greater than the maximum.
1264 *
1265 * The function prints an error message to standard error and terminates the
1266 * test by calling fail() if value is not in range.
1267 *
1268 * @param[in] value The value to check.
1269 *
1270 * @param[in] minimum The minimum value allowed.
1271 *
1272 * @param[in] maximum The maximum value allowed.
1273 */
1274void assert_in_range(LargestIntegralType value, LargestIntegralType minimum,
1275 LargestIntegralType maximum);
1276#else
1277#define assert_in_range(value, minimum, maximum) \
1278 _assert_in_range(cast_to_largest_integral_type(value), \
1279 cast_to_largest_integral_type(minimum), \
1280 cast_to_largest_integral_type(maximum), __FILE__, \
1281 __LINE__)
1282#endif
1283
1284#ifdef DOXYGEN
1285/**
1286 * @brief Assert that the specified value is smaller than the minimum or
1287 * greater than the maximum.
1288 *
1289 * The function prints an error message to standard error and terminates the
1290 * test by calling fail() if value is in range.
1291 *
1292 * @param[in] value The value to check.
1293 *
1294 * @param[in] minimum The minimum value to compare.
1295 *
1296 * @param[in] maximum The maximum value to compare.
1297 */
1298void assert_not_in_range(LargestIntegralType value, LargestIntegralType minimum,
1299 LargestIntegralType maximum);
1300#else
1301#define assert_not_in_range(value, minimum, maximum) \
1302 _assert_not_in_range(cast_to_largest_integral_type(value), \
1303 cast_to_largest_integral_type(minimum), \
1304 cast_to_largest_integral_type(maximum), __FILE__, \
1305 __LINE__)
1306#endif
1307
1308#ifdef DOXYGEN
1309/**
1310 * @brief Assert that the specified value is within a set.
1311 *
1312 * The function prints an error message to standard error and terminates the
1313 * test by calling fail() if value is not within a set.
1314 *
1315 * @param[in] value The value to look up
1316 *
1317 * @param[in] values[] The array to check for the value.
1318 *
1319 * @param[in] count The size of the values array.
1320 */
1321void assert_in_set(LargestIntegralType value, LargestIntegralType values[],
1322 size_t count);
1323#else
1324#define assert_in_set(value, values, number_of_values) \
1325 _assert_in_set(value, values, number_of_values, __FILE__, __LINE__)
1326#endif
1327
1328#ifdef DOXYGEN
1329/**
1330 * @brief Assert that the specified value is not within a set.
1331 *
1332 * The function prints an error message to standard error and terminates the
1333 * test by calling fail() if value is within a set.
1334 *
1335 * @param[in] value The value to look up
1336 *
1337 * @param[in] values[] The array to check for the value.
1338 *
1339 * @param[in] count The size of the values array.
1340 */
1341void assert_not_in_set(LargestIntegralType value, LargestIntegralType values[],
1342 size_t count);
1343#else
1344#define assert_not_in_set(value, values, number_of_values) \
1345 _assert_not_in_set(value, values, number_of_values, __FILE__, __LINE__)
1346#endif
1347
1348/** @} */
1349
1350/**
1351 * @defgroup cmocka_exec Running Tests
1352 * @ingroup cmocka
1353 *
1354 * This is the way tests are executed with CMocka.
1355 *
1356 * The following example illustrates this macro's use with the unit_test macro.
1357 *
1358 * @code
1359 * void Test0(void **state);
1360 * void Test1(void **state);
1361 *
1362 * int main(void)
1363 * {
1364 * const struct CMUnitTest tests[] = {
1365 * cmocka_unit_test(Test0),
1366 * cmocka_unit_test(Test1),
1367 * };
1368 *
1369 * return cmocka_run_group_tests(tests, NULL, NULL);
1370 * }
1371 * @endcode
1372 *
1373 * @{
1374 */
1375
1376#ifdef DOXYGEN
1377/**
1378 * @brief Forces the test to fail immediately and quit.
1379 */
1380void fail(void);
1381#else
1382#define fail() _fail(__FILE__, __LINE__)
1383#endif
1384
1385#ifdef DOXYGEN
1386/**
1387 * @brief Forces the test to not be executed, but marked as skipped
1388 */
1389void skip(void);
1390#else
1391#define skip() _skip(__FILE__, __LINE__)
1392#endif
1393
1394#ifdef DOXYGEN
1395/**
1396 * @brief Forces the test to fail immediately and quit, printing the reason.
1397 *
1398 * @code
1399 * fail_msg("This is some error message for test");
1400 * @endcode
1401 *
1402 * or
1403 *
1404 * @code
1405 * char *error_msg = "This is some error message for test";
1406 * fail_msg("%s", error_msg);
1407 * @endcode
1408 */
1409void fail_msg(const char* msg, ...);
1410#else
1411#define fail_msg(msg, ...) \
1412 do { \
1413 print_error("ERROR: " msg "\n", ##__VA_ARGS__); \
1414 fail(); \
1415 } while (0)
1416#endif
1417
1418#ifdef DOXYGEN
1419/**
1420 * @brief Generic method to run a single test.
1421 *
1422 * @deprecated This function was deprecated in favor of cmocka_run_group_tests
1423 *
1424 * @param[in] #function The function to test.
1425 *
1426 * @return 0 on success, 1 if an error occured.
1427 *
1428 * @code
1429 * // A test case that does nothing and succeeds.
1430 * void null_test_success(void **state) {
1431 * }
1432 *
1433 * int main(void) {
1434 * return run_test(null_test_success);
1435 * }
1436 * @endcode
1437 */
1438int run_test(#function);
1439#else
1440#define run_test(f) _run_test(#f, f, NULL, UNIT_TEST_FUNCTION_TYPE_TEST, NULL)
1441#endif
1442
1443static inline void _unit_test_dummy(void** state) { (void)state; }
1444
1445/** Initializes a UnitTest structure.
1446 *
1447 * @deprecated This function was deprecated in favor of cmocka_unit_test
1448 */
1449#define unit_test(f) \
1450 { #f, f, UNIT_TEST_FUNCTION_TYPE_TEST }
1451
1452#define _unit_test_setup(test, setup) \
1453 { #test "_" #setup, setup, UNIT_TEST_FUNCTION_TYPE_SETUP }
1454
1455/** Initializes a UnitTest structure with a setup function.
1456 *
1457 * @deprecated This function was deprecated in favor of cmocka_unit_test_setup
1458 */
1459#define unit_test_setup(test, setup) \
1460 _unit_test_setup(test, setup), unit_test(test), \
1461 _unit_test_teardown(test, _unit_test_dummy)
1462
1463#define _unit_test_teardown(test, teardown) \
1464 { #test "_" #teardown, teardown, UNIT_TEST_FUNCTION_TYPE_TEARDOWN }
1465
1466/** Initializes a UnitTest structure with a teardown function.
1467 *
1468 * @deprecated This function was deprecated in favor of
1469 * cmocka_unit_test_teardown
1470 */
1471#define unit_test_teardown(test, teardown) \
1472 _unit_test_setup(test, _unit_test_dummy), unit_test(test), \
1473 _unit_test_teardown(test, teardown)
1474
1475/** Initializes a UnitTest structure for a group setup function.
1476 *
1477 * @deprecated This function was deprecated in favor of cmocka_run_group_tests
1478 */
1479#define group_test_setup(setup) \
1480 { "group_" #setup, setup, UNIT_TEST_FUNCTION_TYPE_GROUP_SETUP }
1481
1482/** Initializes a UnitTest structure for a group teardown function.
1483 *
1484 * @deprecated This function was deprecated in favor of cmocka_run_group_tests
1485 */
1486#define group_test_teardown(teardown) \
1487 { "group_" #teardown, teardown, UNIT_TEST_FUNCTION_TYPE_GROUP_TEARDOWN }
1488
1489/**
1490 * Initialize an array of UnitTest structures with a setup function for a test
1491 * and a teardown function. Either setup or teardown can be NULL.
1492 *
1493 * @deprecated This function was deprecated in favor of
1494 * cmocka_unit_test_setup_teardown
1495 */
1496#define unit_test_setup_teardown(test, setup, teardown) \
1497 _unit_test_setup(test, setup), unit_test(test), \
1498 _unit_test_teardown(test, teardown)
1499
1500/** Initializes a CMUnitTest structure. */
1501#define cmocka_unit_test(f) \
1502 { #f, f, NULL, NULL }
1503
1504/** Initializes a CMUnitTest structure with a setup function. */
1505#define cmocka_unit_test_setup(f, setup) \
1506 { #f, f, setup, NULL }
1507
1508/** Initializes a CMUnitTest structure with a teardown function. */
1509#define cmocka_unit_test_teardown(f, teardown) \
1510 { #f, f, NULL, teardown }
1511
1512/**
1513 * Initialize an array of CMUnitTest structures with a setup function for a test
1514 * and a teardown function. Either setup or teardown can be NULL.
1515 */
1516#define cmocka_unit_test_setup_teardown(f, setup, teardown) \
1517 { #f, f, setup, teardown }
1518
1519#define run_tests(tests) _run_tests(tests, sizeof(tests) / sizeof(tests)[0])
1520#define run_group_tests(tests) \
1521 _run_group_tests(tests, sizeof(tests) / sizeof(tests)[0])
1522
1523#ifdef DOXYGEN
1524/**
1525 * @brief Run tests specified by an array of CMUnitTest structures.
1526 *
1527 * @param[in] group_tests[] The array of unit tests to execute.
1528 *
1529 * @param[in] group_setup The setup function which should be called before
1530 * all unit tests are executed.
1531 *
1532 * @param[in] group_teardown The teardown function to be called after all
1533 * tests have finished.
1534 *
1535 * @return 0 on success, or the number of failed tests.
1536 *
1537 * @code
1538 * static int setup(void **state) {
1539 * int *answer = malloc(sizeof(int));
1540 * if (*answer == NULL) {
1541 * return -1;
1542 * }
1543 * *answer = 42;
1544 *
1545 * *state = answer;
1546 *
1547 * return 0;
1548 * }
1549 *
1550 * static int teardown(void **state) {
1551 * free(*state);
1552 *
1553 * return 0;
1554 * }
1555 *
1556 * static void null_test_success(void **state) {
1557 * (void) state;
1558 * }
1559 *
1560 * static void int_test_success(void **state) {
1561 * int *answer = *state;
1562 * assert_int_equal(*answer, 42);
1563 * }
1564 *
1565 * int main(void) {
1566 * const struct CMUnitTest tests[] = {
1567 * cmocka_unit_test(null_test_success),
1568 * cmocka_unit_test_setup_teardown(int_test_success, setup, teardown),
1569 * };
1570 *
1571 * return cmocka_run_group_tests(tests, NULL, NULL);
1572 * }
1573 * @endcode
1574 *
1575 * @see cmocka_unit_test
1576 * @see cmocka_unit_test_setup
1577 * @see cmocka_unit_test_teardown
1578 * @see cmocka_unit_test_setup_teardown
1579 */
1580int cmocka_run_group_tests(const struct CMUnitTest group_tests[],
1581 CMFixtureFunction group_setup,
1582 CMFixtureFunction group_teardown);
1583#else
1584#define cmocka_run_group_tests(group_tests, group_setup, group_teardown) \
1585 _cmocka_run_group_tests(#group_tests, group_tests, \
1586 sizeof(group_tests) / sizeof(group_tests)[0], \
1587 group_setup, group_teardown)
1588#endif
1589
1590#ifdef DOXYGEN
1591/**
1592 * @brief Run tests specified by an array of CMUnitTest structures and specify
1593 * a name.
1594 *
1595 * @param[in] group_name The name of the group test.
1596 *
1597 * @param[in] group_tests[] The array of unit tests to execute.
1598 *
1599 * @param[in] group_setup The setup function which should be called before
1600 * all unit tests are executed.
1601 *
1602 * @param[in] group_teardown The teardown function to be called after all
1603 * tests have finished.
1604 *
1605 * @return 0 on success, or the number of failed tests.
1606 *
1607 * @code
1608 * static int setup(void **state) {
1609 * int *answer = malloc(sizeof(int));
1610 * if (*answer == NULL) {
1611 * return -1;
1612 * }
1613 * *answer = 42;
1614 *
1615 * *state = answer;
1616 *
1617 * return 0;
1618 * }
1619 *
1620 * static int teardown(void **state) {
1621 * free(*state);
1622 *
1623 * return 0;
1624 * }
1625 *
1626 * static void null_test_success(void **state) {
1627 * (void) state;
1628 * }
1629 *
1630 * static void int_test_success(void **state) {
1631 * int *answer = *state;
1632 * assert_int_equal(*answer, 42);
1633 * }
1634 *
1635 * int main(void) {
1636 * const struct CMUnitTest tests[] = {
1637 * cmocka_unit_test(null_test_success),
1638 * cmocka_unit_test_setup_teardown(int_test_success, setup, teardown),
1639 * };
1640 *
1641 * return cmocka_run_group_tests_name("success_test", tests, NULL, NULL);
1642 * }
1643 * @endcode
1644 *
1645 * @see cmocka_unit_test
1646 * @see cmocka_unit_test_setup
1647 * @see cmocka_unit_test_teardown
1648 * @see cmocka_unit_test_setup_teardown
1649 */
1650int cmocka_run_group_tests_name(const char* group_name,
1651 const struct CMUnitTest group_tests[],
1652 CMFixtureFunction group_setup,
1653 CMFixtureFunction group_teardown);
1654#else
1655#define cmocka_run_group_tests_name(group_name, group_tests, group_setup, \
1656 group_teardown) \
1657 _cmocka_run_group_tests(group_name, group_tests, \
1658 sizeof(group_tests) / sizeof(group_tests)[0], \
1659 group_setup, group_teardown)
1660#endif
1661
1662/** @} */
1663
1664/**
1665 * @defgroup cmocka_alloc Dynamic Memory Allocation
1666 * @ingroup cmocka
1667 *
1668 * Memory leaks, buffer overflows and underflows can be checked using cmocka.
1669 *
1670 * To test for memory leaks, buffer overflows and underflows a module being
1671 * tested by cmocka should replace calls to malloc(), calloc() and free() to
1672 * test_malloc(), test_calloc() and test_free() respectively. Each time a block
1673 * is deallocated using test_free() it is checked for corruption, if a corrupt
1674 * block is found a test failure is signalled. All blocks allocated using the
1675 * test_*() allocation functions are tracked by the cmocka library. When a test
1676 * completes if any allocated blocks (memory leaks) remain they are reported
1677 * and a test failure is signalled.
1678 *
1679 * For simplicity cmocka currently executes all tests in one process. Therefore
1680 * all test cases in a test application share a single address space which
1681 * means memory corruption from a single test case could potentially cause the
1682 * test application to exit prematurely.
1683 *
1684 * @{
1685 */
1686
1687#ifdef DOXYGEN
1688/**
1689 * @brief Test function overriding malloc.
1690 *
1691 * @param[in] size The bytes which should be allocated.
1692 *
1693 * @return A pointer to the allocated memory or NULL on error.
1694 *
1695 * @code
1696 * #ifdef UNIT_TESTING
1697 * extern void* _test_malloc(const size_t size, const char* file, const int
1698 * line);
1699 *
1700 * #define malloc(size) _test_malloc(size, __FILE__, __LINE__)
1701 * #endif
1702 *
1703 * void leak_memory() {
1704 * int * const temporary = (int*)malloc(sizeof(int));
1705 * *temporary = 0;
1706 * }
1707 * @endcode
1708 *
1709 * @see malloc(3)
1710 */
1711void* test_malloc(size_t size);
1712#else
1713#define test_malloc(size) _test_malloc(size, __FILE__, __LINE__)
1714#endif
1715
1716#ifdef DOXYGEN
1717/**
1718 * @brief Test function overriding calloc.
1719 *
1720 * The memory is set to zero.
1721 *
1722 * @param[in] nmemb The number of elements for an array to be allocated.
1723 *
1724 * @param[in] size The size in bytes of each array element to allocate.
1725 *
1726 * @return A pointer to the allocated memory, NULL on error.
1727 *
1728 * @see calloc(3)
1729 */
1730void* test_calloc(size_t nmemb, size_t size);
1731#else
1732#define test_calloc(num, size) _test_calloc(num, size, __FILE__, __LINE__)
1733#endif
1734
1735#ifdef DOXYGEN
1736/**
1737 * @brief Test function overriding realloc which detects buffer overruns
1738 * and memoery leaks.
1739 *
1740 * @param[in] ptr The memory block which should be changed.
1741 *
1742 * @param[in] size The bytes which should be allocated.
1743 *
1744 * @return The newly allocated memory block, NULL on error.
1745 */
1746void* test_realloc(void* ptr, size_t size);
1747#else
1748#define test_realloc(ptr, size) _test_realloc(ptr, size, __FILE__, __LINE__)
1749#endif
1750
1751#ifdef DOXYGEN
1752/**
1753 * @brief Test function overriding free(3).
1754 *
1755 * @param[in] ptr The pointer to the memory space to free.
1756 *
1757 * @see free(3).
1758 */
1759void test_free(void* ptr);
1760#else
1761#define test_free(ptr) _test_free(ptr, __FILE__, __LINE__)
1762#endif
1763
1764/* Redirect malloc, calloc and free to the unit test allocators. */
1765#ifdef UNIT_TESTING
1766#define malloc test_malloc
1767#define realloc test_realloc
1768#define calloc test_calloc
1769#define free test_free
1770#endif /* UNIT_TESTING */
1771
1772/** @} */
1773
1774/**
1775 * @defgroup cmocka_mock_assert Standard Assertions
1776 * @ingroup cmocka
1777 *
1778 * How to handle assert(3) of the standard C library.
1779 *
1780 * Runtime assert macros like the standard C library's assert() should be
1781 * redefined in modules being tested to use cmocka's mock_assert() function.
1782 * Normally mock_assert() signals a test failure. If a function is called using
1783 * the expect_assert_failure() macro, any calls to mock_assert() within the
1784 * function will result in the execution of the test. If no calls to
1785 * mock_assert() occur during the function called via expect_assert_failure() a
1786 * test failure is signalled.
1787 *
1788 * @{
1789 */
1790
1791/**
1792 * @brief Function to replace assert(3) in tested code.
1793 *
1794 * In conjuction with check_assert() it's possible to determine whether an
1795 * assert condition has failed without stopping a test.
1796 *
1797 * @param[in] result The expression to assert.
1798 *
1799 * @param[in] expression The expression as string.
1800 *
1801 * @param[in] file The file mock_assert() is called.
1802 *
1803 * @param[in] line The line mock_assert() is called.
1804 *
1805 * @code
1806 * #ifdef UNIT_TESTING
1807 * extern void mock_assert(const int result, const char* const expression,
1808 * const char * const file, const int line);
1809 *
1810 * #undef assert
1811 * #define assert(expression) \
1812 * mock_assert((int)(expression), #expression, __FILE__, __LINE__);
1813 * #endif
1814 *
1815 * void increment_value(int * const value) {
1816 * assert(value);
1817 * (*value) ++;
1818 * }
1819 * @endcode
1820 *
1821 * @see assert(3)
1822 * @see expect_assert_failure
1823 */
1824void mock_assert(const int result, const char* const expression,
1825 const char* const file, const int line);
1826
1827#ifdef DOXYGEN
1828/**
1829 * @brief Ensure that mock_assert() is called.
1830 *
1831 * If mock_assert() is called the assert expression string is returned.
1832 *
1833 * @param[in] fn_call The function will will call mock_assert().
1834 *
1835 * @code
1836 * #define assert mock_assert
1837 *
1838 * void showmessage(const char *message) {
1839 * assert(message);
1840 * }
1841 *
1842 * int main(int argc, const char* argv[]) {
1843 * expect_assert_failure(show_message(NULL));
1844 * printf("succeeded\n");
1845 * return 0;
1846 * }
1847 * @endcode
1848 *
1849 */
1850void expect_assert_failure(function fn_call);
1851#else
1852#define expect_assert_failure(function_call) \
1853 { \
1854 const int result = setjmp(global_expect_assert_env); \
1855 global_expecting_assert = 1; \
1856 if (result) { \
1857 print_message("Expected assertion %s occurred\n", \
1858 global_last_failed_assert); \
1859 global_expecting_assert = 0; \
1860 } else { \
1861 function_call; \
1862 global_expecting_assert = 0; \
1863 print_error("Expected assert in %s\n", #function_call); \
1864 _fail(__FILE__, __LINE__); \
1865 } \
1866 }
1867#endif
1868
1869/** @} */
1870
1871/* Function prototype for setup, test and teardown functions. */
1872typedef void (*UnitTestFunction)(void** state);
1873
1874/* Function that determines whether a function parameter value is correct. */
1875typedef int (*CheckParameterValue)(const LargestIntegralType value,
1876 const LargestIntegralType check_value_data);
1877
1878/* Type of the unit test function. */
1879typedef enum UnitTestFunctionType {
1880 UNIT_TEST_FUNCTION_TYPE_TEST = 0,
1881 UNIT_TEST_FUNCTION_TYPE_SETUP,
1882 UNIT_TEST_FUNCTION_TYPE_TEARDOWN,
1883 UNIT_TEST_FUNCTION_TYPE_GROUP_SETUP,
1884 UNIT_TEST_FUNCTION_TYPE_GROUP_TEARDOWN,
1885} UnitTestFunctionType;
1886
1887/*
1888 * Stores a unit test function with its name and type.
1889 * NOTE: Every setup function must be paired with a teardown function. It's
1890 * possible to specify NULL function pointers.
1891 */
1892typedef struct UnitTest {
1893 const char* name;
1894 UnitTestFunction function;
1895 UnitTestFunctionType function_type;
1896} UnitTest;
1897
1898typedef struct GroupTest {
1899 UnitTestFunction setup;
1900 UnitTestFunction teardown;
1901 const UnitTest* tests;
1902 const size_t number_of_tests;
1903} GroupTest;
1904
1905/* Function prototype for test functions. */
1906typedef void (*CMUnitTestFunction)(void** state);
1907
1908/* Function prototype for setup and teardown functions. */
1909typedef int (*CMFixtureFunction)(void** state);
1910
1911struct CMUnitTest {
1912 const char* name;
1913 CMUnitTestFunction test_func;
1914 CMFixtureFunction setup_func;
1915 CMFixtureFunction teardown_func;
1916};
1917
1918/* Location within some source code. */
1919typedef struct SourceLocation {
1920 const char* file;
1921 int line;
1922} SourceLocation;
1923
1924/* Event that's called to check a parameter value. */
1925typedef struct CheckParameterEvent {
1926 SourceLocation location;
1927 const char* parameter_name;
1928 CheckParameterValue check_value;
1929 LargestIntegralType check_value_data;
1930} CheckParameterEvent;
1931
1932/* Used by expect_assert_failure() and mock_assert(). */
1933extern int global_expecting_assert;
1934extern jmp_buf global_expect_assert_env;
1935extern const char* global_last_failed_assert;
1936
1937/* Retrieves a value for the given function, as set by "will_return". */
1938LargestIntegralType _mock(const char* const function, const char* const file,
1939 const int line);
1940
1941void _expect_check(const char* const function, const char* const parameter,
1942 const char* const file, const int line,
1943 const CheckParameterValue check_function,
1944 const LargestIntegralType check_data,
1945 CheckParameterEvent* const event, const int count);
1946
1947void _expect_in_set(const char* const function, const char* const parameter,
1948 const char* const file, const int line,
1949 const LargestIntegralType values[],
1950 const size_t number_of_values, const int count);
1951void _expect_not_in_set(const char* const function, const char* const parameter,
1952 const char* const file, const int line,
1953 const LargestIntegralType values[],
1954 const size_t number_of_values, const int count);
1955
1956void _expect_in_range(const char* const function, const char* const parameter,
1957 const char* const file, const int line,
1958 const LargestIntegralType minimum,
1959 const LargestIntegralType maximum, const int count);
1960void _expect_not_in_range(const char* const function,
1961 const char* const parameter, const char* const file,
1962 const int line, const LargestIntegralType minimum,
1963 const LargestIntegralType maximum, const int count);
1964
1965void _expect_value(const char* const function, const char* const parameter,
1966 const char* const file, const int line,
1967 const LargestIntegralType value, const int count);
1968void _expect_not_value(const char* const function, const char* const parameter,
1969 const char* const file, const int line,
1970 const LargestIntegralType value, const int count);
1971
1972void _expect_string(const char* const function, const char* const parameter,
1973 const char* const file, const int line, const char* string,
1974 const int count);
1975void _expect_not_string(const char* const function, const char* const parameter,
1976 const char* const file, const int line,
1977 const char* string, const int count);
1978
1979void _expect_memory(const char* const function, const char* const parameter,
1980 const char* const file, const int line,
1981 const void* const memory, const size_t size,
1982 const int count);
1983void _expect_not_memory(const char* const function, const char* const parameter,
1984 const char* const file, const int line,
1985 const void* const memory, const size_t size,
1986 const int count);
1987
1988void _expect_any(const char* const function, const char* const parameter,
1989 const char* const file, const int line, const int count);
1990
1991void _check_expected(const char* const function_name,
1992 const char* const parameter_name, const char* file,
1993 const int line, const LargestIntegralType value);
1994
1995void _will_return(const char* const function_name, const char* const file,
1996 const int line, const LargestIntegralType value,
1997 const int count);
1998void _assert_true(const LargestIntegralType result,
1999 const char* const expression, const char* const file,
2000 const int line);
2001void _assert_return_code(const LargestIntegralType result, size_t rlen,
2002 const LargestIntegralType error,
2003 const char* const expression, const char* const file,
2004 const int line);
2005void _assert_int_equal(const LargestIntegralType a, const LargestIntegralType b,
2006 const char* const file, const int line);
2007void _assert_int_not_equal(const LargestIntegralType a,
2008 const LargestIntegralType b, const char* const file,
2009 const int line);
2010void _assert_string_equal(const char* const a, const char* const b,
2011 const char* const file, const int line);
2012void _assert_string_not_equal(const char* const a, const char* const b,
2013 const char* file, const int line);
2014void _assert_memory_equal(const void* const a, const void* const b,
2015 const size_t size, const char* const file,
2016 const int line);
2017void _assert_memory_not_equal(const void* const a, const void* const b,
2018 const size_t size, const char* const file,
2019 const int line);
2020void _assert_in_range(const LargestIntegralType value,
2021 const LargestIntegralType minimum,
2022 const LargestIntegralType maximum, const char* const file,
2023 const int line);
2024void _assert_not_in_range(const LargestIntegralType value,
2025 const LargestIntegralType minimum,
2026 const LargestIntegralType maximum,
2027 const char* const file, const int line);
2028void _assert_in_set(const LargestIntegralType value,
2029 const LargestIntegralType values[],
2030 const size_t number_of_values, const char* const file,
2031 const int line);
2032void _assert_not_in_set(const LargestIntegralType value,
2033 const LargestIntegralType values[],
2034 const size_t number_of_values, const char* const file,
2035 const int line);
2036
2037void* _test_malloc(const size_t size, const char* file, const int line);
2038void* _test_realloc(void* ptr, const size_t size, const char* file,
2039 const int line);
2040void* _test_calloc(const size_t number_of_elements, const size_t size,
2041 const char* file, const int line);
2042void _test_free(void* const ptr, const char* file, const int line);
2043
2044void _fail(const char* const file, const int line);
2045
2046void _skip(const char* const file, const int line);
2047
2048int _run_test(const char* const function_name, const UnitTestFunction Function,
2049 void** const volatile state,
2050 const UnitTestFunctionType function_type,
2051 const void* const heap_check_point);
2052CMOCKA_DEPRECATED int _run_tests(const UnitTest* const tests,
2053 const size_t number_of_tests);
2054CMOCKA_DEPRECATED int _run_group_tests(const UnitTest* const tests,
2055 const size_t number_of_tests);
2056
2057/* Test runner */
2058int _cmocka_run_group_tests(const char* group_name,
2059 const struct CMUnitTest* const tests,
2060 const size_t num_tests,
2061 CMFixtureFunction group_setup,
2062 CMFixtureFunction group_teardown);
2063
2064/* Standard output and error print methods. */
2065void print_message(const char* const format, ...) CMOCKA_PRINTF_ATTRIBUTE(1, 2);
2066void print_error(const char* const format, ...) CMOCKA_PRINTF_ATTRIBUTE(1, 2);
2067void vprint_message(const char* const format, va_list args)
2068 CMOCKA_PRINTF_ATTRIBUTE(1, 0);
2069void vprint_error(const char* const format, va_list args)
2070 CMOCKA_PRINTF_ATTRIBUTE(1, 0);
2071
2072enum cm_message_output {
2073 CM_OUTPUT_STDOUT,
2074 CM_OUTPUT_SUBUNIT,
2075 CM_OUTPUT_TAP,
2076 CM_OUTPUT_XML,
2077};
2078
2079/**
2080 * @brief Function to set the output format for a test.
2081 *
2082 * The ouput format for the test can either be set globally using this
2083 * function or overriden with environment variable CMOCKA_MESSAGE_OUTPUT.
2084 *
2085 * The environment variable can be set to either STDOUT, SUBUNIT, TAP or XML.
2086 *
2087 * @param[in] output The output format to use for the test.
2088 *
2089 */
2090void cmocka_set_message_output(enum cm_message_output output);
2091
2092/** @} */
2093
2094#endif /* CMOCKA_H_ */
2095