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