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