Debian Codegraph @

src/vendor/azure-uamqp-c/deps/umock-c/doc/umock_c.md

raw
1 # umock_c
2
3 # Overview
4
5 umock_c is a C mocking library that exposes APIs to allow:
6 - defining mock functions,
7 - recording expected calls
8 - comparing expected calls with actual calls.
9 On top of the basic functionality, additional convenience features like modifiers on expected calls are provided.
10
11 # Simple example
12
13 A test written with umock_c looks like below:
14
15 Let's assume unit A depends on unit B. unit B has a function called test_dependency_1_arg.
16
17 In unit B's header one would write:
18
19 ```c
20 #include "umock_prod.h"
21
22 MOCKABLE_FUNCTION(, int, test_dependency_1_arg, int, a);
23 ```
24
25 Let's assume unit A has a function called function_under_test.
26
27 ```c
28 int function_under_test();
29 {
30 int result = test_dependency_1_arg(x);
31 return result;
32 }
33 ```
34
35 A test that checks that function_under_test calls its dependency and injects a return value, while ignoring all arguments on the call looks like this:
36
37 ```c
38 TEST_FUNCTION(my_first_test)
39 {
40 // arrange
41 STRICT_EXPECTED_CALL(test_dependency_1_arg(42))
42 .SetReturn(44)
43 .IgnoreAllArguments();
44
45 // act
46 int result = function_under_test();
47
48 // assert
49 ASSERT_ARE_EQUAL(int, 44, result);
50 ASSERT_ARE_EQUAL(char_ptr, umock_c_get_expected_calls(), umock_c_get_actual_calls());
51 }
52 ```
53
54 # Exposed API (umock_c.h)
55
56 ```c
57 #define UMOCK_C_ERROR_CODE_VALUES \
58 UMOCK_C_ARG_INDEX_OUT_OF_RANGE, \
59 UMOCK_C_MALLOC_ERROR, \
60 UMOCK_C_INVALID_ARGUMENT_BUFFER, \
61 UMOCK_C_COMPARE_CALL_ERROR, \
62 UMOCK_C_RESET_CALLS_ERROR, \
63 UMOCK_C_CAPTURE_RETURN_ALREADY_USED, \
64 UMOCK_C_NULL_ARGUMENT, \
65 UMOCK_C_INVALID_PAIRED_CALLS, \
66 UMOCK_C_COPY_ARGUMENT_ERROR, \
67 UMOCK_C_ERROR
68
69 MU_DEFINE_ENUM(UMOCK_C_ERROR_CODE, UMOCK_C_ERROR_CODE_VALUES)
70
71 #define IGNORED_PTR_ARG (NULL)
72 #define IGNORED_NUM_ARG (0)
73
74 #define MOCKABLE_FUNCTION(modifiers, result, function, ...) \
75 ...
76
77 #define MOCKABLE_FUNCTION_WITH_RETURNS(modifiers, result, function, ...)(success_return_value, failure_return_value) \
78 ...
79
80 #define REGISTER_GLOBAL_MOCK_HOOK(mock_function, mock_hook_function) \
81 ...
82
83 #define REGISTER_GLOBAL_MOCK_RETURN(mock_function, return_value) \
84 ...
85
86 #define REGISTER_GLOBAL_MOCK_FAIL_RETURN(mock_function, fail_return_value) \
87 ...
88
89 #define REGISTER_GLOBAL_MOCK_RETURNS(mock_function, return_value, fail_return_value) \
90 ...
91 ...
92
93 #define STRICT_EXPECTED_CALL(call) \
94 ...
95
96 #define EXPECTED_CALL(call) \
97 ...
98
99 extern int umock_c_init(ON_UMOCK_C_ERROR on_umock_c_error);
100 extern void umock_c_deinit(void);
101 extern void umock_c_reset_all_calls(void);
102 extern const char* umock_c_get_actual_calls(void);
103 extern const char* umock_c_get_expected_calls(void);
104 ```
105
106 ## Mock definitions API
107
108 ### MOCKABLE_FUNCTION
109
110 ```c
111 MOCKABLE_FUNCTION(modifiers, result, function, ...)
112 ```
113
114 MOCKABLE_FUNCTION shall be used to wrap function definitions, allowing the user to declare a function that can be mocked.
115
116 The macro shall generate a function signature in case ENABLE_MOCKS is not defined.
117
118 Example:
119
120 ```c
121 MOCKABLE_FUNCTION(FAR, int, test_function, int, arg1)
122 ```
123
124 should generate for production code:
125
126 ```c
127 int FAR test_function(int arg1);
128 ```
129
130 ### MOCKABLE_FUNCTION_WITH_RETURNS
131
132 ```c
133 #define MOCKABLE_FUNCTION_WITH_RETURNS(modifiers, result, function, ...)(success_return_value, failure_return_value) \
134 ```
135
136 `MOCKABLE_FUNCTION_WITH_RETURNS` shall be used to wrap function definitions, allowing the user to declare a function that can be mocked and aditionally declares the values that are to be returned in case of success and failure.
137
138 The macro shall generate a function signature in case `ENABLE_MOCKS` is not defined.
139
140 Example:
141
142 ```c
143 MOCKABLE_FUNCTION_WITH_RETURNS(FAR, int, test_function, int, arg1)(0, 42)
144 ```
145
146 Specifying the return values for success and failure shall be equivalent to calling `REGISTER_GLOBAL_MOCK_RETURNS`.
147
148 If `MOCKABLE_FUNCTION_WITH_RETURNS` is used for a function that does not return, a compile error will be emitted.
149
150 ### MOCK_FUNCTION_WITH_CODE
151
152 MOCK_FUNCTION_WITH_CODE shall define a mock function and allow the user to embed code between this define and a MOCK_FUNCTION_END call.
153
154 ```c
155 MOCK_FUNCTION_WITH_CODE(, void, test_mock_function_with_code_1_arg, int, a);
156 int some_value = 42;
157 /* more code here */
158 MOCK_FUNCTION_END()
159 ```
160
161 ### ENABLE_MOCKS
162
163 If ENABLE_MOCKS is defined, MOCKABLE_FUNCTION shall generate the declaration of the function and code for the mocked function, thus allowing setting up of expectations in test functions. If ENABLE_MOCKS is not defined, MOCKABLE_FUNCTION shall only generate a declaration for the function.
164
165 ENABLE_MOCKS should be used in the translation unit that contains the tests just before including the headers for all the units that the code under test depends on. Example:
166
167 ```c
168
169 #include <stdlib.h>
170 // ... other various includes
171
172 #define ENABLE_MOCKS
173 #include "test_dependency.h"
174
175 // ... tests
176
177 ```
178
179 Note that it is possible (and sometimes necessary) to undefine ENABLE_MOCKS:
180
181 ```c
182
183 #include <stdlib.h>
184 // ... other various includes
185
186 #define ENABLE_MOCKS
187 #include "test_dependency.h"
188 #undef ENABLE_MOCKS
189
190 #include "unit_under_test.h"
191
192 // ... tests
193
194 ```
195
196 ### ENABLE_MOCK_FILTERING
197
198 `ENABLE_MOCK_FILTERING` is a define that enables filtering which mockable functions get mock functions generated. This is useful when it is not desired to generate mock functions for all the functions declared in a header (increased number of mock functions puts strains on some compilers and linkers).
199
200 If `ENABLE_MOCK_FILTERING` is defined, by default no mocks are generated. In order to enable generating a mock for a mockable function, one has to nicely ask the framework to do so by having a define for each function that should get mocks generated.
201
202 The define is of the form `please_mock_{function_name}`:
203
204 ```c
205 #define please_mock_{function_name} MOCK_ENABLED
206 ```
207
208 Example:
209
210 Assume that several mockable functions are declared in a header `my_header.h`:
211
212 ```c
213 MOCKABLE_FUNCTION(, void, function_1)
214 MOCKABLE_FUNCTION(, void, function_2)
215 MOCKABLE_FUNCTION(, void, function_3)
216 ```
217
218 If one wants to only generate the mocks for `function_2`, one would write in the translation unit before including above header:
219
220 ```c
221 #define ENABLE_MOCK_FILTERING
222
223 #define please_mock_function_2 MOCK_ENABLED
224
225 #define ENABLE_MOCKS
226 #include "my_header.h"
227 #undef ENABLE_MOCKS
228 ```
229
230 ### UMOCK_STATIC
231
232 If you intend to add several units under test into the same test library, the inclusion of the same dependency will result in symbol collisions of the mock functions. A way to get around this is to define UMOCK_STATIC as follows
233
234 ```c
235
236 #include <stdlib.h>
237 // ... other various includes
238
239 // enable emitting static mocks
240 #define UMOCK_STATIC static
241 #define ENABLE_MOCKS
242
243 #include "test_dependency.h"
244
245 #undef ENABLE_MOCKS
246 #include "unit_under_test.h"
247
248 #define ENABLE_MOCKS
249 // include unit under test source to make it see static mocks
250 #include "unit_under_test.c"
251
252 // ... tests
253
254 ```
255
256 before including dependencies. This will cause MOCK_FUNCTION macro to generate static mocks, which avoids symbol collisions if the dependency is included in other unit test .c files in the same library.
257
258 Using this technique, it is however also important to #include the unit under test source into the unit test compilation unit, so as to make it able to see the generated mocks as shown in above code sample.
259
260 ## umock init/deinit
261
262 ### umock_c_init
263
264 ```c
265 int umock_c_init(ON_UMOCK_C_ERROR on_umock_c_error);
266 ```
267
268 umock_c_init is needed before performing any action related to umock_c calls (or registering any types).
269
270 umock_c_init shall initialize umock_c.
271
272 umock_c_init called if already initialized shall fail and return a non-zero value.
273
274 umock_c_init shall initialize the umock supported types (C native types).
275
276 on_umock_c_error can be NULL.
277
278 If on_umock_c_error is non-NULL it shall be saved for later use (to be invoked whenever an umock_c error needs to be signaled to the user).
279
280 ### umock_c_deinit
281
282 ```c
283 void umock_c_deinit(void);
284 ```
285
286 umock_c_deinit shall free all umock_c used resources.
287 If umock_c was not initialized, umock_c_deinit shall do nothing.
288
289 ## Expected calls recording API
290
291 ### STRICT_EXPECTED_CALL
292
293 ```c
294 STRICT_EXPECTED_CALL(call)
295 ```
296
297 STRICT_EXPECTED_CALL shall record that a certain call is expected.
298 For each argument the argument value shall be stored for later comparison with actual calls.
299
300 The call argument shall be the complete function invocation.
301
302 Examples:
303
304 ```c
305 STRICT_EXPECTED_CALL(test_dependency_1_arg(42));
306 STRICT_EXPECTED_CALL(test_dependency_string("test"));
307 ```
308
309 ### EXPECTED_CALL
310
311 ```c
312 EXPECTED_CALL(call)
313 ```
314
315 EXPECTED_CALL shall record that a certain call is expected.
316 No arguments shall be saved by default, unless other modifiers state it.
317
318 The call argument shall be the complete function invocation.
319
320 Example:
321
322 ```c
323 EXPECTED_CALL(test_dependency_1_arg(42));
324 ```
325
326 ## Call comparison API
327
328 ### umock_c_reset_all_calls
329
330 ```c
331 void umock_c_reset_all_calls(void);
332 ```
333
334 umock_c_reset_all_calls shall reset all calls (actual and expected).
335 In case of any error, umock_c_reset_all_calls shall indicate the error through a call to the on_error callback.
336
337 ### umock_c_get_expected_calls
338
339 ```c
340 const char* umock_c_get_expected_calls(void);
341 ```
342
343 umock_c_get_expected_calls shall return all the calls that were expected, but were not fulfilled.
344
345 For each call, the format shall be "functionName(argument 1 value, ...)".
346 Each call shall be enclosed in "[]".
347
348 Example:
349
350 For a call with the signature:
351
352 ```c
353 int test_dependency_2_args(int a, int b)
354 ```
355
356 if an expected call was recorded:
357
358 ```c
359 STRICT_EXPECTED_CALL(test_dependency_2_args(42, 1));
360 ```
361
362 umock_c_get_expected_calls would return:
363
364 ```c
365 "[test_dependency_2_args(42,1)]"
366 ```
367
368 ### umock_c_get_actual_calls
369
370 ```c
371 const char* umock_c_get_actual_calls(void);
372 ```
373
374 umock_c_get_actual_calls shall return all the actual calls that were not matched to expected calls.
375
376 For each call, the format shall be "functionName(argument 1 value, ...)".
377 Each call shall be enclosed in "[]". A call to umock_c_get_actual_calls shall not modify the actual calls that were recorded.
378
379 Example:
380
381 For a call with the signature:
382
383 ```c
384 int test_dependency_2_args(int a, int b)
385 ```
386
387 if an actual call was recorded:
388
389 ```c
390 test_dependency_2_args(42, 2);
391 ```
392
393 umock_c_get_actual_calls would return:
394
395 ```c
396 "[test_dependency_2_args(42,2)]"
397 ```
398
399 ### Call comparison rules
400
401 umock_c shall compare calls in order. That means that "[A()][B()]" is different than "[B()][A()]".
402
403 When multiple return values are set for a mock function by using different means, the following order shall be in effect:
404
405 - If a return value has been specified for an expected call then that value shall be returned.
406 - If a global mock hook has been specified then it shall be called and its result returned.
407 - If a global return value has been specified then it shall be returned.
408 - Otherwise the value of a static variable of the same type as the return type shall be returned.
409
410 If call comparison fails an error shall be indicated by calling the error callback with UMOCK_C_COMPARE_CALL_ERROR.
411
412 ## Supported types
413
414 ### Out of the box
415
416 Out of the box umock_c shall support the following types through the header umocktypes_c.h:
417 - char
418 - unsigned char
419 - short
420 - unsigned short
421 - int
422 - unsigned int
423 - long
424 - unsigned long
425 - long long
426 - unsigned long long
427 - float
428 - double
429 - long double
430 - size_t
431 - void*
432 - const void*
433
434 ### Pointer types
435
436 If no custom handler has beed registered for a pointer type, it shall be trated as void*.
437
438 ### Custom types
439
440 Custom types, like structures shall be supported by allowing the user to define a set of functions that can be used by umock_c to operate with these types.
441
442 Five functions shall be provided to umock_c:
443 - A stringify function.
444
445 This function shall return the string representation of a value of the given type.
446
447 - An are_equal function.
448
449 This function shall compare 2 values of the given type and return an int indicating whether they are equal (1 means equal, 0 means different).
450
451 - A copy function.
452
453 This function shall make a copy of a value for the given type.
454
455 - A free function.
456
457 This function shall free a copied value.
458
459 #### umockvalue_stringify_type
460
461 ```c
462 char* umockvalue_stringify_{type}(const {type}* value)
463 ```
464
465 A stringify function shall allocate using malloc a char\* and fill it with a string representation of value.
466
467 If any error is encountered during building the string representation, umockvalue_stringify_type shall return NULL.
468
469 Example:
470
471 ```c
472 char* umockvalue_stringify_int(const int* value)
473 {
474 char* result;
475
476 if (value == NULL)
477 {
478 result = NULL;
479 }
480 else
481 {
482 char temp_buffer[32];
483 int length = sprintf(temp_buffer, "%d", *value);
484 if (length < 0)
485 {
486 result = NULL;
487 }
488 else
489 {
490 result = (char*)malloc(length + 1);
491 if (result != NULL)
492 {
493 memcpy(result, temp_buffer, length + 1);
494 }
495 }
496 }
497
498 return result;
499 }
500 ```
501
502 #### umockvalue_are_equal_type
503
504 ```c
505 int umockvalue_are_equal_{type}(const {type}* left, const {type}* right)
506 ```
507
508 The umockvalue_are_equal_type function shall return 1 if the 2 values are equal and 0 if they are not.
509
510 If both left and right are NULL, umockvalue_are_equal_type shall return 1.
511
512 If only one of left and right is NULL, umockvalue_are_equal_{type} shall return 0.
513
514 Example:
515
516 ```c
517 int umockvalue_are_equal_int(const int* left, const int* right)
518 {
519 int result;
520
521 if (left == right)
522 {
523 result = 1;
524 }
525 else if ((left == NULL) || (right == NULL))
526 {
527 result = 0;
528 }
529 else
530 {
531 result = ((*left) == (*right)) ? 1 : 0;
532 }
533
534 return result;
535 }
536 ```
537
538 #### umockvalue_copy_type
539
540 ```c
541 int umockvalue_copy_{type}({type}* destination, const {type}* source)
542 ```
543
544 The umockvalue_copy_type function shall copy the value from source to destination.
545
546 On success umockvalue_copy_type shall return 0.
547
548 If any of the arguments is NULL, umockvalue_copy_type shall return a non-zero value.
549
550 If any error occurs during copying the value, umockvalue_copy_type shall return a non-zero value.
551
552 Example:
553
554 ```c
555 int umockvalue_copy_int(int* destination, const int* source)
556 {
557 int result;
558
559 if ((destination == NULL) ||
560 (source == NULL))
561 {
562 result = __LINE__;
563 }
564 else
565 {
566 *destination = *source;
567 result = 0;
568 }
569
570 return result;
571 }
572 ```
573
574 #### umockvalue_free_type
575
576 ```c
577 void umockvalue_free_{type}({type}* value)
578 ```
579
580 The umockvalue_free_type function shall free a value previously copied using umockvalue_copy_type. If value is NULL, no free shall be performed.
581
582 Example:
583
584 ```c
585 void umockvalue_free_int(int* value)
586 {
587 /* no free required for int */
588 }
589 ```
590
591 ### Custom enum types
592
593 #### IMPLEMENT_UMOCK_C_ENUM_TYPE
594
595 ```c
596 IMPLEMENT_UMOCK_C_ENUM_TYPE(type, ...)
597 ```
598
599 IMPLEMENT_UMOCK_C_ENUM_TYPE shall implement umock_c handlers for an enum type.
600 The variable arguments are a list making up the enum values.
601 If a value that is not part of the enum is used, it shall be treated as an int value.
602 Note: IMPLEMENT_UMOCK_C_ENUM_TYPE only generates the handlers, registering the handlers still has to be done by using the macro REGISTER_UMOCK_VALUE_TYPE.
603
604 Example:
605
606 ```c
607 IMPLEMENT_UMOCK_C_ENUM_TYPE(my_enum, enum_value1, enum_value2)
608 ```
609
610 This provides the handlers (stringify, are_equal, etc.) for the below C enum:
611
612 ```c
613 typedef enum my_enum_tag
614 {
615 enum_value1,
616 enum_value2
617 } my_enum
618 ```
619
620 ### Type names
621
622 Since umock_c needs to maintain a list of registered types, the following rules shall be applied:
623 Each type shall be normalized to a form where all extra spaces are removed.
624 Type names are case sensitive.
625
626 #### REGISTER_UMOCK_VALUE_TYPE
627
628 ```c
629 REGISTER_UMOCK_VALUE_TYPE(value_type, stringify_func, are_equal_func, copy_func, free_func)
630 ```
631
632 REGISTER_UMOCK_VALUE_TYPE shall register the type identified by value_type to be usable by umock_c for argument and return types and instruct umock_c which functions to use for getting the stringify, are_equal, copy and free.
633
634 Example:
635
636 ```c
637 REGISTER_UMOCK_VALUE_TYPE(TEST_STRUCT*, umockvalue_stringify_TEST_STRUCT_ptr, umockvalue_are_equal_TEST_STRUCT_ptr, umockvalue_copy_TEST_STRUCT_ptr, umockvalue_free_TEST_STRUCT_ptr);
638 ```
639
640 If only the value_type is specified in the macro invocation then the stringify, are_equal, copy and free function names shall be automatically derived from the type as: umockvalue_stringify_value_type, umockvalue_are_equal_value_type, umockvalue_copy_value_type, umockvalue_free_value_type.
641
642 Example:
643
644 ```c
645 REGISTER_UMOCK_VALUE_TYPE(TEST_STRUCT);
646 ```
647
648 If REGISTER_UMOCK_VALUE_TYPE fails, the on_io_error callback shall be called with UMOCK_C_REGISTER_TYPE_FAILED.
649
650 #### REGISTER_UMOCK_ALIAS_TYPE
651
652 ```c
653 REGISTER_UMOCK_ALIAS_TYPE(value_type, is_value_type)
654 ```
655
656 REGISTER_UMOCK_ALIAS_TYPE registers a new alias type for another type. That means that the handlers used for is_value_type will also be used for the new alias value_type.
657
658 If REGISTER_UMOCK_ALIAS_TYPE fails, the on_io_error callback shall be called with UMOCK_C_REGISTER_TYPE_FAILED.
659
660 ### Extra optional C types
661
662 #### umockvalue_charptr
663
664 char\* and const char\* shall be supported out of the box through a separate header, umockvalue_charptr.h.
665
666 In order to enable the usage of char\*, the function umockvalue_charptr_register_types can be used in the test suite init.
667
668 The signature shall be:
669
670 ```c
671 int umockvalue_charptr_register_types(void);
672 ```
673
674 umockvalue_charptr_register_types returns 0 on success and non-zero on failure.
675
676 #### umockvalue_stdint
677
678 The types in stdint.h shall be supported out of the box by including umockvalue_stdint.h.
679
680 In order to enable the usage of stdint types, the function umockvalue_stdint_register_types shall be used in the test suite init.
681
682 ```c
683 int umockvalue_stdint_register_types(void);
684 ```
685
686 umockvalue_stdint_register_types returns 0 on success and non-zero on failure.
687
688 ## Call modifiers
689
690 When an expected call is recorded a call modifier interface in the form of a structure containing function pointers shall be returned to the caller.
691
692 That allows constructs like:
693
694 ```c
695 STRICT_EXPECTED_CALL(test_dependency_1_arg(42))
696 .SetReturn(44)
697 .IgnoreAllArguments();
698 ```
699
700 Note that each modifier function shall return a full modifier structure that allows chaining further call modifiers.
701
702 The last modifier in a chain overrides previous modifiers if any collision occurs. Example: A ValidateAllArguments after a previous IgnoreAllArgument will still validate all arguments.
703
704 ### IgnoreAllArguments(void)
705
706 The IgnoreAllArguments call modifier shall record that for that specific call all arguments will be ignored for that specific call.
707
708 IgnoreAllArguments shall only be available for mock functions that have arguments.
709
710 ### ValidateAllArguments(void)
711
712 The ValidateAllArguments call modifier shall record that for that specific call all arguments will be validated.
713
714 ValidateAllArguments shall only be available for mock functions that have arguments.
715
716 ### IgnoreArgument_{arg_name}(void)
717
718 The IgnoreArgument_{arg_name} call modifier shall record that the argument identified by arg_name will be ignored for that specific call.
719
720 IgnoreArgument_{arg_name} shall only be available for mock functions that have arguments.
721
722 ### ValidateArgument_{arg_name}(void)
723
724 The ValidateArgument_{arg_name} call modifier shall record that the argument identified by arg_name will be validated for that specific call.
725
726 ValidateArgument_{arg_name} shall only be available for mock functions that have arguments.
727
728 ### IgnoreArgument(size_t index)
729
730 The IgnoreArgument call modifier shall record that the indexth argument will be ignored for that specific call.
731
732 If the index is out of range umock_c shall raise an error with the code UMOCK_C_ARG_INDEX_OUT_OF_RANGE.
733
734 IgnoreArgument shall only be available for mock functions that have arguments.
735
736 ### ValidateArgument(size_t index)
737
738 The ValidateArgument call modifier shall record that the indexth argument will be validated for that specific call.
739
740 If the index is out of range umock_c shall raise an error with the code UMOCK_C_ARG_INDEX_OUT_OF_RANGE.
741
742 ValidateArgument shall only be available for mock functions that have arguments.
743
744 ### SetReturn(return_type result)
745
746 The SetReturn call modifier shall record that when an actual call is matched with the specific expected call, it shall return the result value to the code under test.
747
748 SetReturn shall only be available if the return type is not void.
749
750 ### SetFailReturn(return_type result)
751
752 The SetFailReturn call modifier shall record a fail return value.
753 The fail return value can be recorded for more advanced features that would require failing or succeeding certain calls based on decisions made at runtime.
754
755 SetFailReturn shall only be available if the return type is not void.
756
757 ### CopyOutArgumentBuffer(size_t index, const void* bytes, size_t length)
758
759 The CopyOutArgumentBuffer call modifier shall copy the memory pointed to by bytes and being length bytes so that it is later injected as an out argument when the code under test calls the mock function.
760
761 The memory shall be copied.
762 If several calls to CopyOutArgumentBuffer are made, only the last buffer shall be kept.
763
764 The buffers for previous CopyOutArgumentBuffer calls shall be freed.
765
766 CopyOutArgumentBuffer shall only be applicable to pointer types.
767
768 If the index is out of range umock_c shall raise an error with the code UMOCK_C_ARG_INDEX_OUT_OF_RANGE.
769
770 If bytes is NULL or length is 0, umock_c shall raise an error with the code UMOCK_C_INVALID_ARGUMENT_BUFFER.
771
772 The argument targetted by CopyOutArgumentBuffer shall also be marked as ignored.
773
774 If any memory allocation error occurs, umock_c shall raise an error with the code UMOCK_C_MALLOC_ERROR.
775
776 If any other error occurs, umock_c shall raise an error with the code UMOCK_C_ERROR.
777
778 CopyOutArgumentBuffer shall only be available for mock functions that have arguments.
779
780 ### CopyOutArgumentBuffer_{arg_name}(const void* bytes, size_t length)
781
782 The CopyOutArgumentBuffer_{arg_name} call modifier shall copy the memory pointed to by bytes and being length bytes so that it is later injected as an out argument when the code under test calls the mock function.
783
784 The memory shall be copied.
785 If several calls to CopyOutArgumentBuffer are made, only the last buffer shall be kept.
786
787 CopyOutArgumentBuffer_{arg_name} shall only be applicable to pointer types.
788
789 If bytes is NULL or length is 0, umock_c shall raise an error with the code UMOCK_C_INVALID_ARGUMENT_BUFFER.
790
791 The argument targetted by CopyOutArgumentBuffer_{arg_name} shall also be marked as ignored.
792
793 If any memory allocation error occurs, umock_c shall raise an error with the code UMOCK_C_MALLOC_ERROR.
794
795 If any other error occurs, umock_c shall raise an error with the code UMOCK_C_ERROR.
796
797 CopyOutArgumentBuffer_{arg_name} shall only be available for mock functions that have arguments.
798
799 ### CopyOutArgument(arg_type value)
800
801 The CopyOutArgument call modifier shall copy an argument value to be injected as an out argument value when the code under test calls the mock function.
802
803 CopyOutArgument shall only be applicable to pointer types.
804
805 CopyOutArgument shall only be available for mock functions that have arguments.
806
807 ### ValidateArgumentBuffer(size_t index, const void* bytes, size_t length)
808
809 The ValidateArgumentBuffer call modifier shall copy the memory pointed to by bytes and being length bytes so that it is later compared against a pointer type argument when the code under test calls the mock function.
810
811 If the content of the code under test buffer and the buffer supplied to ValidateArgumentBuffer does not match then this should be treated as a mismatch in argument comparison for that argument.
812 ValidateArgumentBuffer shall implicitly perform an IgnoreArgument on the indexth argument.
813
814 The memory pointed by bytes shall be copied. If several calls to ValidateArgumentBuffer are made, only the last buffer shall be kept.
815
816 The buffers for previous ValidateArgumentBuffer calls shall be freed.
817
818 ValidateArgumentBuffer shall only be applicable to pointer types.
819
820 If the index is out of range umock_c shall raise an error with the code UMOCK_C_ARG_INDEX_OUT_OF_RANGE.
821
822 If bytes is NULL or length is 0, umock_c shall raise an error with the code UMOCK_C_INVALID_ARGUMENT_BUFFER.
823
824 ValidateArgumentBuffer shall only be available for mock functions that have arguments.
825
826 ### IgnoreAllCalls(void)
827
828 The IgnoreAllCalls call modifier shall record that all calls matching the expected call shall be ignored. If no matching call occurs no missing call shall be reported. If multiple matching actual calls occur no unexpected calls shall be reported.
829 The call matching shall be done taking into account arguments and call modifiers referring to arguments.
830
831 ### CaptureReturn(return_type* captured_return_value)
832
833 The CaptureReturn call modifier shall copy the return value that is being returned to the code under test when an actual call is matched with the expected call.
834 If CaptureReturn is called multiple times for the same call, an error shall be indicated with the code UMOCK_C_CAPTURE_RETURN_ALREADY_USED.
835 If captured_return_value is NULL, umock_c shall raise an error with the code UMOCK_C_NULL_ARGUMENT.
836 CaptureReturn shall only be available if the return type is not void.
837
838 Example:
839
840 ```c
841 TEST_FUNCTION(capture_return_captures_the_return_value)
842 {
843 // arrange
844 int captured_return;
845
846 STRICT_EXPECTED_CALL(test_dependency_for_capture_return())
847 .CaptureReturn(&captured_return);
848
849 // act
850 test_dependency_for_capture_return();
851
852 // assert
853 ASSERT_ARE_EQUAL(int, 42, captured_return);
854 }
855 ```
856
857 ### ValidateArgumentValue_{arg_name}(arg_type* arg_value)
858
859 The ValidateArgumentValue_{arg_name} shall validate that the value of an argument matches the value pointed by arg_value.
860 If arg_value is NULL, umock_c shall raise an error with the code UMOCK_C_NULL_ARGUMENT.
861 The ValidateArgumentValue_{arg_name} modifier shall inhibit comparing with any value passed directly as an argument in the expected call.
862 The ValidateArgumentValue_{arg_name} shall implicitly do a ValidateArgument for the arg_name argument, making sure the argument is not ignored.
863
864 Example:
865
866 Given a function with the prototype:
867
868 ```c
869 void function_with_int_arg(int a);
870 ```
871
872 ```c
873 TEST_FUNCTION(validate_argument_sample)
874 {
875 // arrange
876 int arg_value = 0;
877
878 STRICT_EXPECTED_CALL(function_with_int_arg(0))
879 .ValidateArgumentValue_a(&arg_value);
880
881 arg_value = 42;
882
883 // act
884 function_with_int_arg(42);
885
886 // assert
887 // ... calls should match ...
888 }
889 ```
890
891 ### ValidateArgumentValue_{arg_name}_AsType(const char* type_name)
892
893 `ValidateArgumentValue_{arg_name}_AsType` shall ensure that validation of the argument `arg_name` is done as if the argument is of type `type_name`.
894 If `type_name` is NULL, umock_c shall raise an error with the code UMOCK_C_NULL_ARGUMENT.
895 If storing the argument value as the new type fails, umock_c shall raise an error with the code UMOCK_C_COPY_ARGUMENT_ERROR.
896 If `ValidateArgumentValue_{arg_name}_AsType` is used multiple times on the same argument, the last call shall apply.
897
898 ```c
899 typedef struct MY_STRUCT_TAG
900 {
901 int x;
902 } MY_STRUCT;
903
904 void function_with_void_ptr(void* argument);
905
906 TEST_FUNCTION(validate_argument_as_type_sample)
907 {
908 // arrange
909 int arg_value = 0;
910 MY_STRUCT x = { 42 };
911
912 STRICT_EXPECTED_CALL(function_with_void_ptr(&x))
913 .ValidateArgumentValue_argument_AsType(UMOCK_TYPE(MY_STRUCT));
914
915 // act
916 function_with_int_arg(&x);
917
918 // assert
919 // ... calls should match ...
920 }
921 ```
922
923 ### CaptureArgumentValue_{arg_name}(arg_type* arg_value)
924
925 The `CaptureArgumentValue_{arg_name}` shall copy the value of the argument at the time of the call to `arg_value`.
926 If `arg_value` is NULL, `umock_c` shall raise an error with the code `UMOCK_C_NULL_ARGUMENT`.
927 The `CaptureArgumentValue_{arg_name}` shall not change the how the argument is validated.
928
929 The copy is done using the copy functions registered with umock for the argument type.
930
931 Example:
932
933 Given a function with the prototype:
934
935 ```c
936 void function_with_int_arg(int a);
937 ```
938
939 ```c
940 TEST_FUNCTION(capture_argument_sample)
941 {
942 // arrange
943 int captured_arg_value = 0;
944
945 STRICT_EXPECTED_CALL(function_with_int_arg(0))
946 .CaptureArgumentValue_a(&captured_arg_value);
947
948 captured_arg_value = 43;
949
950 // act
951 function_with_int_arg(42);
952
953 // assert: captured value should be 43
954 ASSERT_ARE_EQUAL(int, 43, captured_arg_value);
955 }
956 ```
957
958 ### call_cannot_fail_func_{name}
959
960 `call_cannot_fail_func__{name}` call modifier shall record that when performing failure case run, this call should be skipped.
961 If recording that the call cannot fail is unsuccessful, umock shall raise with the error code UMOCK_C_ERROR.
962
963 ### Automatic argument ignore
964
965 If `IGNORED_PTR_ARG` or `IGNORED_NUM_ARG` is used as an argument value with `STRICT_EXPECTED_CALL`, the argument shall be automatically ignored.
966 `IGNORED_PTR_ARG` shall be defined as NULL so that it can be used for pointer type arguments.
967 `IGNORED_NUM_ARG` shall be defined to 0 so that it can be used for numeric type arguments.
968
969 Example:
970
971 ```c
972 STRICT_EXPECTED_CALL(function_name(IGNORED_PTR_ARG, 2, IGNORED_NUM_ARG));
973 ```
974
975 is equivalent to:
976
977 ```c
978 STRICT_EXPECTED_CALL(function_name(NULL, 2, 0))
979 .IgnoreArgument(1)
980 .IgnoreArgument(3);
981 ```
982
983 ## Global mock modifiers
984
985 ### REGISTER_GLOBAL_MOCK_HOOK
986
987 ```c
988 REGISTER_GLOBAL_MOCK_HOOK(mock_function, mock_hook_function)
989 ```
990
991 The REGISTER_GLOBAL_MOCK_HOOK shall register a mock hook to be called every time the mocked function is called by production code. The hook's result shall be returned by the mock to the production code.
992
993 The signature for the hook shall be assumed to have exactly the same arguments and return as the mocked function.
994
995 If there are multiple invocations of REGISTER_GLOBAL_MOCK_HOOK, the last one shall take effect over the previous ones.
996
997 REGISTER_GLOBAL_MOCK_HOOK called with a NULL hook unregisters a previously registered hook.
998
999 All parameters passed to the mock shall be passed down to the mock hook.
1000
1001 ### REGISTER_GLOBAL_MOCK_RETURN
1002
1003 ```c
1004 REGISTER_GLOBAL_MOCK_RETURN(mock_function, return_value)
1005 ```
1006
1007 The REGISTER_GLOBAL_MOCK_RETURN shall register a return value to always be returned by a mock function.
1008
1009 If there are multiple invocations of REGISTER_GLOBAL_MOCK_RETURN, the last one shall take effect over the previous ones.
1010
1011 If any error occurs during REGISTER_GLOBAL_MOCK_RETURN, umock_c shall raise an error with the code UMOCK_C_ERROR.
1012
1013 ### REGISTER_GLOBAL_MOCK_FAIL_RETURN
1014
1015 ```c
1016 REGISTER_GLOBAL_MOCK_FAIL_RETURN(mock_function, fail_return_value)
1017 ```
1018
1019 The REGISTER_GLOBAL_MOCK_FAIL_RETURN shall register a fail return value to be returned by a mock function when marked as failed in the expected calls.
1020
1021 If there are multiple invocations of REGISTER_GLOBAL_FAIL_MOCK_RETURN, the last one shall take effect over the previous ones.
1022
1023 If any error occurs during REGISTER_GLOBAL_MOCK_FAIL_RETURN, umock_c shall raise an error with the code UMOCK_C_ERROR.
1024
1025 ### REGISTER_GLOBAL_MOCK_RETURNS
1026
1027 ```c
1028 REGISTER_GLOBAL_MOCK_RETURNS(mock_function, return_value, fail_return_value)
1029 ```
1030
1031 The REGISTER_GLOBAL_MOCK_RETURNS shall register both a success and a fail return value associated with a mock function.
1032
1033 If there are multiple invocations of REGISTER_GLOBAL_MOCK_RETURNS, the last one shall take effect over the previous ones.
1034
1035 If any error occurs during REGISTER_GLOBAL_MOCK_RETURNS, umock_c shall raise an error with the code UMOCK_C_ERROR.
1036
1037 ## negative tests addon
1038
1039 In order to automate negative tests writing, a separate API surface is provided: umock_c_negative_tests.
1040
1041 Example:
1042
1043 Given a function under test with the following code:
1044 ```c
1045 int function_under_test(void)
1046 {
1047 int result;
1048
1049 if (function_1() != 0)
1050 {
1051 result = __LINE__;
1052 }
1053 else
1054 {
1055 if (function_2() != 0)
1056 {
1057 result = __LINE__;
1058 }
1059 else
1060 {
1061 result = 0;
1062 }
1063 }
1064
1065 return result;
1066 }
1067 ```
1068
1069 The function calls two functions that return int:
1070
1071 ```c
1072 MOCKABLE_FUNCTION(, int, function_1);
1073 MOCKABLE_FUNCTION(, int, function_2);
1074 ```
1075
1076 In order to test that for each case where either function_1 or function_2 fails and returns a non-zero value, one could write the following test that loops through all cases as opposed to writing individual negative tests:
1077
1078 ```c
1079 size_t i;
1080 STRICT_EXPECTED_CALL(function_1())
1081 .SetReturn(0).SetFailReturn(1);
1082 STRICT_EXPECTED_CALL(function_2())
1083 .SetReturn(0).SetFailReturn(1);
1084 umock_c_negative_tests_snapshot();
1085
1086 for (i = 0; i < umock_c_negative_tests_call_count(); i++)
1087 {
1088 // arrange
1089 char temp_str[128];
1090 int result;
1091 umock_c_negative_tests_reset();
1092 umock_c_negative_tests_fail_call(i);
1093
1094 // act
1095 result = function_under_test();
1096
1097 // assert
1098 sprintf(temp_str, "On failed call %zu", i + 1);
1099 ASSERT_ARE_NOT_EQUAL_WITH_MSG(int, 0, result, temp_str);
1100 }
1101 ```
1102
1103 Note that a return value and a fail return value must be specified for the negative tests. If they are not specified that will result in undefined behavior.
1104
1105 ### umock_c_negative_tests_init
1106
1107 ```c
1108 int umock_c_negative_tests_init(void)
1109 ```
1110
1111 umock_c_negative_tests_init shall initialize the negative tests umock_c module.
1112 On success it shall return 0. If any error occurs, it shall return a non-zero value.
1113 This call is typically made in the test function setup.
1114
1115 ### umock_c_negative_tests_deinit
1116
1117 ```c
1118 void umock_c_negative_tests_deinit(void)
1119 ```
1120
1121 umock_c_negative_tests_deinit shall free all resources used by the negative tests module.
1122
1123 ### umock_c_negative_tests_snapshot
1124
1125 ```c
1126 void umock_c_negative_tests_snapshot(void)
1127 ```
1128
1129 umock_c_negative_tests_snapshot shall take a snapshot of the current setup of expected calls (a.k.a happy path).
1130 This is in order for these calls to be replayed as many times as needed, each time allowing different calls to be failed.
1131 If umock_c_negative_tests_snapshot is called without the module being initialized, it shall do nothing.
1132 All errors shall be reported by calling the umock_c on error function.
1133
1134 ### umock_c_negative_tests_reset
1135
1136 ```c
1137 void umock_c_negative_tests_reset(void)
1138 ```
1139
1140 umock_c_negative_tests_reset shall bring umock_c expected and actual calls to the state recorded when umock_c_negative_tests_snapshot was called.
1141 This is done typically in preparation of running each negative test.
1142 If umock_c_negative_tests_reset is called without the module being initialized, it shall do nothing.
1143 All errors shall be reported by calling the umock_c on error function.
1144
1145 ### umock_c_negative_tests_fail_call
1146
1147 ```c
1148 void umock_c_negative_tests_fail_call(size_t index)
1149 ```
1150
1151 umock_c_negative_tests_fail_call shall instruct the negative tests module to fail a specific call.
1152 If umock_c_negative_tests_fail_call is called without the module being initialized, it shall do nothing.
1153 All errors shall be reported by calling the umock_c on error function.
1154
1155 ### umock_c_negative_tests_call_count
1156
1157 ```c
1158 size_t umock_c_negative_tests_call_count(void)
1159 ```
1160
1161 umock_c_negative_tests_call_count shall provide the number of expected calls, so that the test code can iterate through all negative cases.
1162 If umock_c_negative_tests_fail_call is called without the module being initialized, it shall return 0.
1163 All errors shall be reported by calling the umock_c on error function.
1164
1165 ## paired calls addon
1166
1167 The paired calls addon can be used in order to ensure that function calls are paired correctly when needed.
1168 For example, given a create and destroy function pair:
1169
1170 ```c
1171 SOME_HANDLE some_create(void);
1172 void some_destroy(SOME_HANDLE handle, ...);
1173 ```
1174
1175 It is desirable to make sure that all create calls are paired with appropriate destroy calls.
1176 umockc provides the ability for the user to declare that by using a macro like:
1177
1178 ```c
1179 REGISTER_UMOCKC_PAIRED_CREATE_DESTROY_CALLS(some_create, some_destroy);
1180 ```
1181
1182 The paired calls addon can based on this information figure out if any calls are made to some_create without having a counterpart some_destroy.
1183 Typically registering the pairs with umockc would be done in the test suite setup.
1184
1185 ### REGISTER_UMOCKC_PAIRED_CREATE_DESTROY_CALLS(create_call, destroy_call)
1186
1187 ```c
1188 REGISTER_UMOCKC_PAIRED_CREATE_DESTROY_CALLS(create_call, destroy_call)
1189 ```
1190
1191 REGISTER_UMOCKC_PAIRED_CREATE_DESTROY_CALLS shall register with umock two calls that are expected to be paired.
1192 The create call shall have a non-void return type.
1193 The destroy call shall take as argument at least one argument. The type of the first argument shall be of the same type as the return type for the create_call.
1194 If create_call or destroy_call do not obey these rules, at the time of calling REGISTER_UMOCKC_PAIRED_CREATE_DESTROY_CALLS umock_c shall raise an error with the code UMOCK_C_INVALID_PAIRED_CALLS.
1195
1196 At each create_call a memory block shall be allocated so that it can be reported as a leak by any memory checker.
1197 If any error occurs during the create_call related then umock_c shall raise an error with the code UMOCK_C_ERROR.
1198
1199 When a destroy_call happens the memory block associated with the argument passed to it shall be freed.
1200 If the first argument passed to destroy_call is not found in the list of tracked handles (returned by create_call) then umock_c shall raise an error with the code UMOCK_C_INVALID_PAIRED_CALLS.
1201 If any error occurs during the destroy_call related then umock_c shall raise an error with the code UMOCK_C_ERROR.
1202
1203 The type used for the return of create_call and first argument of destroy_call shall be allowed to be any type registered with umock.
1204 Tracking of paired calls shall not be done if the actual call to the `create_call` is using the `SetFailReturn` call modifier.
1205
1206 ## real function support
1207
1208 Sometimes it is desirable to track the mockable function calls and also call the real implementation of those functions.
1209 While that is possible by simply registering a hook function for each of the mockable functions, it is also rather involved and cumbersome.
1210
1211 In order to simplify the process, the macros `MOCKABLE_INTERFACE`, `IMPLEMENT_MOCKABLE_FUNCTION` and `REGISTER_GLOBAL_INTERFACE_HOOKS` can be used.
1212 The basic design is that the unit under test calls all its dependencies with its original function names.
1213 The actual dependency code cannot be linked as is because there would be linker errors. Thus all dependencies will have their APIs renamed to be prefixed with `real_`.
1214 Then umock can be setup to call the `real_` functions whenever the unit under test calls a mocked function.
1215
1216 Example:
1217
1218 Given a test dependency with the below interface:
1219
1220 ```c
1221 MOCKABLE_INTERFACE(test_interface,
1222 FUNCTION(, int, test_dependency_1_arg, int, a),
1223 FUNCTION(, int, test_dependency_2_args, int, a, int, b)
1224 )
1225 ```
1226
1227 A user would write in the unit test code:
1228
1229 ```c
1230 #define ENABLE_MOCKS
1231
1232 #include "test_dependency.h"
1233 #include "test_dependency_real_code.c"
1234
1235 TEST_FUNCTION(reals_are_setup_at_interface_level)
1236 {
1237 // arrange
1238 int result;
1239
1240 REGISTER_GLOBAL_INTERFACE_HOOKS(test_interface);
1241
1242 STRICT_EXPECTED_CALL(test_dependency_1_arg(45));
1243
1244 // act
1245 result = test_dependency_1_arg(45);
1246
1247 // assert
1248 ASSERT_ARE_EQUAL(char_ptr, "", umock_c_get_expected_calls());
1249 ASSERT_ARE_EQUAL(char_ptr, "", umock_c_get_actual_calls());
1250 ASSERT_ARE_EQUAL(int, 42, result);
1251 }
1252 ```
1253
1254 The functions defined in `test_dependency_real_code.c` have to use `IMPLEMENT_MOCKABLE_FUNCTION`.
1255 The inclusion of the `test_dependency_real_code.c` file while `ENABLE_MOCKS` is defined ensures that the functions implemented in that file get automatically renamed to `real_` functions.
1256
1257 ### MOCKABLE_INTERFACE
1258
1259 ```c
1260 #define MOCKABLE_INTERFACE(interface_name, ...) \
1261 ```
1262
1263 `MOCKABLE_INTERFACE` allows grouping several mockable functions in a header in order to be able to register all the hooks into one call for the entire group of functions.
1264
1265 Each item in `...` shall be an entry for one mockable function.
1266
1267 Each item in `...` shall be defined using a macro called `FUNCTION`, which shall be an alias for `MOCKABLE_FUNCTION`.
1268
1269 Example:
1270
1271 ```c
1272 MOCKABLE_INTERFACE(test_interface,
1273 FUNCTION(, int, test_dependency_1_arg, int, a),
1274 FUNCTION(, int, test_dependency_2_args, int, a, int, b)
1275 )
1276 ```
1277
1278 ### IMPLEMENT_MOCKABLE_FUNCTION
1279
1280 ```c
1281 #define IMPLEMENT_MOCKABLE_FUNCTION(modifiers, result, function, ...) \
1282 ...
1283 ```
1284
1285 In the presence of the `ENABLE_MOCKS` define, `IMPLEMENT_MOCKABLE_FUNCTION` shall expand to the signature of the function, but the name shall be changed to be prefix with `real_`.
1286
1287 If `ENABLE_MOCKS` is not defined, `IMPLEMENT_MOCKABLE_FUNCTION` shall expand to the signature of the function.
1288
1289 ### REGISTER_GLOBAL_INTERFACE_HOOKS
1290
1291 ```c
1292 #define REGISTER_GLOBAL_INTERFACE_HOOKS(interface_name) \
1293 ...
1294 ```
1295
1296 `REGISTER_GLOBAL_INTERFACE_HOOKS` shall register as mock hooks the real functions for all the functions in a mockable interface.
1297
1298 ### UMOCK_REAL
1299
1300 ```c
1301 #define UMOCK_REAL(function_name) \
1302 ...
1303 ```
1304
1305 `UMOCK_REAL` shall produce the name of the real function generated by umock.