Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/testtools/micromock/doc/micromock.md

raw
1 # MicroMock
2
3 # Why?
4 Micromock is intended to fulfill the needs of the (connected car networking) developers in mocking dependencies. The following are the main goals:
5 - Allow runtime mocking by using Detours, since this is the main case where mocking is really needed.
6 - Allow a less verbose mode of declaring the mock classes. The main goal here is that for one mocked API, one line of code should be written into the mock class and the line of code should resemble as much as possible the original mocked API.
7 - Writing tests with the framework should not require verbosity.
8 - Comparing expected calls and actual calls should explicitly state what the mismatch is.
9
10 # Cheat sheet
11 ## Declaring a mock class
12 ```c
13 TYPED_MOCK_CLASS(CMultimediaTimerMock, CRuntimeMock)
14 {
15 public:
16 MOCK_HOOK_METHOD_5(WINAPI, timeSetEvent, MMRESULT, UINT, uDelay, UINT, uResolution, LPTIMECALLBACK, lpTimeProc, DWORD_PTR, dwUser, UINT, fuEvent)
17 MOCK_METHOD_END(MMRESULT, 0x0)
18 };
19 ```
20 The above mock class contains one static method that expects 5 arguments and returns a value of type MMRESULT. The method is prefixed with WINAPI in order to specify the __stdcall calling convention.
21 Also the mock method by default returns 0, as specified by the MOCK_METHOD_END macro.
22
23 ## Instantiating mocks
24
25 CRuntimeMock<CMultimediaTimerMock, CNiceCallComparer> multimediaTimerMock;
26
27
28 ## Specifying expected calls in a test
29 Specifying an expected call is done by using the EXPECTED_CALL macro:
30 ```c
31 EXPECTED_CALL(multimediaTimerMock, timeSetEvent(0, TEST_MILLISECONDS_DELAY, NULL, NULL, TIME_CALLBACK_FUNCTION));
32 ```
33
34 ## Overriding a return value for an expected call
35 In order to instruct the mock to return a specific value for an expected call, one can specify the SetReturn modifier on the expected call:
36 ```c
37 EXPECTED_CALL(multimediaTimerMock, timeSetEvent(0, TEST_MILLISECONDS_DELAY, NULL, NULL, TIME_CALLBACK_FUNCTION))
38 .SetReturn(42);
39 ```
40
41 ## Overriding a return value for an expected call with a fail return value
42 In order to instruct the mock to return a specific value for an expected call, one can specify the SetFailReturn modifier on the expected call:
43 ```c
44 EXPECTED_CALL(multimediaTimerMock, timeSetEvent(0, TEST_MILLISECONDS_DELAY, NULL, NULL, TIME_CALLBACK_FUNCTION))
45 .SetFailReturn(42);
46 ```
47 In this case, the code (if any) in body of the mock shall not be executed and the mock shall return the fail return value
48 as soon as it has matched the call.
49
50 ## A simple test
51 ```c
52 TEST_METHOD(When_The_Multimedia_Timer_Creation_Is_Successful_DoWork_Succeeds)
53 {
54 // arrange
55 CClassUnderTest classUnderTest;
56
57 CMultimediaTimerMock multimediaTimerMock;
58
59 EXPECTED_CALL(multimediaTimerMock, timeSetEvent(0, TEST_MILLISECONDS_DELAY, NULL, NULL, TIME_CALLBACK_FUNCTION))
60 // classUnderTest.DoWork will see 0x42 as result to the timeSetEvent call
61 .SetReturn(0x42);
62
63 // act
64 BOOL result = classUnderTest.DoWork(TEST_MILLISECONDS_DELAY);
65
66 // assert
67 Assert::AreEqual(TRUE, result, _T("DoWork should succeed when the timeSetEvent succeeds."));
68 }
69 ```
70 # Mock classes
71 In order to declare a mock class, the TYPED_MOCK_CLASS macro can be used:
72 ```c
73 TYPED_MOCK_CLASS(CTestMock, CRuntimeMock)
74 {
75 public:
76 ...
77 };
78 ```
79 Then the instantiation of the mock in the test looks like:
80 ```c
81 CTestMock testMock;
82 ```
83 There are 4 types of mocks:
84 ## CMock
85 This mock type is the simplest. It provides the ability to setup expected calls, record actual calls and compare the 2 lists.
86 ## CThreadSafeGlobalMock
87 This mock type provides all the CMock functionality and in addition it ensures that only one instance of the same mock exists at one time by using a mutex.
88 ## CRuntimeMock
89 This mock type provides all the CThreadSafeGlobalMock functionality and in addition it allows installing hooks by using Detours.
90 # Mock methods
91 All mock methods start with one of the following macros: MOCK_METHOD_x, MOCK_STATIC_METHOD_x, MOCK_HOOK_METHOD_x or MOCK_HOOK_METHOD_EX_x, where x is the number of arguments for the mock method.
92 Currently methods with up to 10 arguments are supported.
93 A mock method without any arguments uses the MOCK_METHOD_0 macro.
94 ## MOCK_METHOD_x
95 ```c
96 MOCK_METHOD_x(prefix, returnType, name, arg1Type, arg1Value, arg2Type, ...)
97 ```
98 declares a mock class member method.
99 ## MOCK_STATIC_METHOD_x
100 ```c
101 MOCK_STATIC_METHOD_x(prefix, returnType, name, arg1Type, arg1Value, arg2Type, ...)
102 ```
103 declares a mock class member static method. A static method can only be used in a CThreadSafeGlobalMock or CRuntimeMock mock class.
104 ## MOCK_HOOK_METHOD_x
105 ```c
106 MOCK_HOOK_METHOD_x(prefix, returnType, name, arg1Type, arg1Value, arg2Type, ...)
107 ```
108 declares a mock class member static method and declares that the global namespace function with the same name will be hooked/detoured to the declared mock method. A hook method can only be used in a CRuntimeMock mock class.
109 ## MOCK_HOOK_METHOD_EX_x
110 ```c
111 MOCK_HOOK_METHOD_EX_x(prefix, returnType, name, arg1Type, arg1Value, arg2Type, ..., functionToHook)
112 ```
113 declares a hook mock method and additionally instructs the framework to hook a specific function (functionToHook) and redirect all calls to the mock method.
114 # Actual vs Expected call comparison
115 ## CompareActualAndExpectedCalls
116 In order to get the result of the comparison of actual and expected calls, a call to CompareActualAndExpectedCalls can be made and the resulting string can be directly used in an assert statement.
117 ```c
118 tstring result = multimediaTimerMock.CompareActualAndExpectedCalls();
119 Assert::AreEqual(tstring(_T("")), result,
120 _T("Incorrect mock function call result"));
121 ```
122
123 If a call was expected and no actual call was matched with it CompareActualAndExpectedCalls indicates the missing call in a format like "[Missing:timeSetEvent(42)]".
124 If a call was not expected, but an actual call occurred (the code under test called a mock function when not expected), CompareActualAndExpectedCalls indicates the unexpected call in a format like "[Unexpected:timeSetEvent(42)]".
125 ## GetUnexpectedCalls/GetMissingCalls
126 In order to facilitate writing asserts in a natural way, the following syntax can also be used:
127 ```c
128 Assert::AreEqual(testMock.GetMissingCalls(),testMock.GetUnexpectedCalls(),
129 _T("Incorrect mock function call result"));
130 ```
131 ## Arguments in call comparisons
132 When comparing an expected call and an actual call, arguments are taken into account according to what has been setup on the expected call.
133 Using EXPECTED_CALL states that an expected call does not compare any arguments by default. The expected call can be modified to force argument comparison by using the ValidateArgument modifier.
134 Using STRICT_EXPECTED_CALL states an expected call compares all arguments by default. To exclude specific arguments from the comparison the IgnoreArgument modifier can be used.
135 ValidateArgument and IgnoreArgument are mutually exclusive. If both of them are used on the same expected call, the last one sticks.
136 ## Special handling for some argument types
137 ### Structures
138 Since functions can have arguments of other types than the basic ones, sometimes there is a need for specialized comparison. If a mocked function takes a structure argument for example, comparing the contents of the structure should only compare the members, not all the bytes in the structure.
139 For this case in order for the framework to do the comparison and conversion of the call arguments to string, 2 operators are required to be implemented:
140 - The equality operator
141 - The stream insertion << operator
142
143
144 ### Defining pointer equality operators
145 In order to allow the mocking framework to directly compare pointer types, the equality operator for the type itself needs to be defined.
146 ```c
147 _Must_inspect_result_
148 static bool operator==(_In_ SOCKADDR const& lhs, _In_ SOCKADDR const& rhs)
149 {
150 if (lhs.sa_family != rhs.sa_family)
151 {
152 return false;
153 }
154
155
156 if (lhs.sa_family == AF_INET)
157 {
158 return ... ; // more comparison of the structure members should be done here
159 }
160
161 return (memcmp(lhs.sa_data, rhs.sa_data, sizeof(rhs.sa_data)) == 0);
162 }
163 ```
164 Additionally a specialization of the == operator for the MockValue class (internally used by the framework) should be provided:
165 MICROMOCK_POINTER_TYPE_EQUAL(SOCKADDR const);
166 Then any test can specify the arguments of the type SOCKADDR const* to be compared as regular arguments in any expected function calls.
167
168 ## Call comparers
169
170 Several call comparers are available for performing the comparison of expected calls and actual calls. If no comparer is specified then the StrictUnorderedCallComparer is used.
171 ### StrictUnorderedCallComparer
172 This comparer checks that every actual call has a matching expected call and every expected call has a matching actual call, but without caring about the order in which they appeared.
173 Practically, every time an actual call is made by the code under test, the first matching expected call (that was previously not matched) is paired. The search happens in the order in which the expected calls are defined in the test.
174 ### StrictOrderedCallComparer
175 This comparer checks that every actual call has a matching expected call, making sure the actual calls appear in the order specified by the expected calls written in the test.
176 ### NiceCallComparer
177 This comparer checks that every expected call has a matching actual call, and it completely ignores the unexpected calls from the code under test. Also, the order in which the calls happen is not relevant for the comparison.
178 Example test:
179 ```c
180 TEST_METHOD(NiceCallComparer_Ignores_Unexpected_Calls)
181 {
182 // arrange
183 CNiceCallComparer<CTestStaticMock > testMock;
184
185 FunctionUnderTest() // invokes CTestStaticMock::StaticTestFunction(43);
186
187 // act
188
189 tstring result = testMock.CompareActualAndExpectedCalls();
190
191 // assert
192 Assert::AreEqual(tstring(_T("")), result,
193 _T("Incorrect mock function call result"));
194 }
195 ```
196
197 ## Resetting expected and actual calls
198 It is possible to reset the list of actual calls maintained by a mock object by a call to ResetActualCalls. This allows handling corner cases where executing code under test is desired and actual calls should only be taken into account from a certain point on in the test.
199 It is also possible to reset the expected calls by issuing a call to ResetExpectedCalls. This feature is only provided for symmetry with resetting the actual calls.
200 If it is desired to completely reset a mock, this can be achieved by a call to ResetAllCalls, which essentially resets both the actual and expected call list.
201 Good tests do not typically require these features, so they should be used cautiously.
202 # Non-compare actions
203 In some cases it is needed to specify that a certain result is returned by a mocked function from a given point of the test execution forward, without actually checking that actual calls exist to match that call.
204 A typical example is setting up the time for a piece of code under test. For example, let's take the case when the code under test uses GetTickCount64 to retrieve the current system tick count. The test needs to inject a known tick count value to be used by all calls coming from the production code, so that any time dependency and flakiness of the test can be eliminated.
205 Also the test needs in some cases to inject different values of the time to simulate passing of time and test how the code under test behaves.
206 For these cases the construct WHEN_CALLED can be used, as shown below:
207 ```c
208 TEST_METHOD(When_Called_Is_Not_Used_In_Call_Comparison)
209 {
210 // arrange
211 CTestStaticMock tickCountMock;
212
213 WHEN_CALLED(tickCountMock, GetTickCount64())
214 .SetReturn(42);
215
216 FunctionUnderTest(); // invokes GetTickCount64() 7 times and all 7 calls return 42
217
218 // act
219 tstring result = testMock.CompareActualAndExpectedCalls();
220
221 // assert
222 Assert::AreEqual(tstring(_T("")), result,
223
224 _T("Incorrect mock function call result"));
225 }
226 ```
227
228 WHEN_CALLED does not validate argument values by default.
229 Also WHEN_CALLED_STRICT is available, which will by default validate all the call arguments. If the arguments do not match then the action specified by WHEN_CALLED (for example returning a specific value) is ignored.
230 # Custom mocks
231 It is possible to write custom mock code directly in the mock class.
232 ```c
233 TYPED_MOCK_CLASS(CTestStaticMock, CRuntimeMock)
234 {
235 public:
236 MOCK_STATIC_METHOD_1(, UINT8, StaticTestFunctionWith1Arg, UINT8, arg1)
237 if (4200 == arg1)
238 {
239 return 45;
240 }
241 MOCK_METHOD_END(UINT8, 0)
242 };
243 ```
244 # Automatic runtime hooks installation
245 In order to avoid installing the hooks in every test, it is possible to specify in the class declaration which hooks should be installed:
246 ```c
247 TYPED_MOCK_CLASS(CTestStaticMock, CRuntimeMock)
248 {
249 public:
250 MOCK_HOOK_METHOD_0(, UINT64, GetTickCount64)
251 MOCK_METHOD_END(UINT64, 0)
252 };
253 ```
254
255 Runtime hooks work only with the CRuntimeMock class.
256 Hooks can be declared by :
257 - specifying mock hook methods (with MOCK_HOOK_METHOD_x or MOCK_HOOK_METHOD_EX_x)
258 - using the INSTALL_HOOK macro.
259
260 The INSTALL_HOOK macro instructs the framework to hook a function every time the mock class is instantiated. Example:
261 ```c
262 TYPED_MOCK_CLASS(CTestStaticMock, CRuntimeMock)
263 {
264 public:
265 MOCK_HOOK_METHOD_0(, UINT64, MyGetTickCount64)
266 MOCK_METHOD_END(UINT64, 0)
267
268 INSTALL_HOOK(::GetTickCount64, MyGetTickCount64)
269 };
270 ```
271
272
273 All hooks specified by MOCK_HOOK_xxx methods or INSTALL_HOOK are automatically reverted when the mock class is destroyed.
274
275 # Expectation modifier details
276
277 ## SetReturn
278
279 This modifier allows specifying that for a given expected call a certain value should be returned, overriding the default value that would normally be returned by the mock function.
280 Example test:
281 ```c
282 TYPED_MOCK_CLASS(CTestStaticMock, CThreadSafeGlobalMock)
283 {
284 public:
285 MOCK_STATIC_METHOD_0(, UINT8, StaticTestFunction)
286 MOCK_METHOD_END(UINT8, 1)
287 };
288
289 UINT8 FunctionUnderTest()
290 {
291 return StaticTestFunction();
292 }
293
294 TEST_METHOD(SetReturn_Overrides_The_Return_Value_Of_The_Mock)
295 {
296 // arrange
297 CTestStaticMock testMock;
298
299 STRICT_EXPECTED_CALL(testMock, StaticTestFunction())
300 .SetReturn(42);
301
302 // act
303 UINT8 result = FunctionUnderTest(); // StaticTestFunction returns 42
304
305 // assert
306 Assert::AreEqual((UINT8)42, result,
307 _T("Incorrect mock function call result"));
308 }
309 ```
310
311 Test result: Pass
312 ## NeverInvoked
313 This expectation modifier specifies that the call is not expected. Should the call occur, the call comparison will return a mismatch, explicitly stating that the call was unexpected.
314 Example test:
315 ```c
316 TEST_METHOD(NeverInvoked_When_An_Actual_Call_Is_Made_Indicates_A_Mismatch)
317 {
318 // arrange
319 CTestStaticMock testMock;
320
321
322 STRICT_EXPECTED_CALL(testMock, StaticTestFunction())
323 .NeverInvoked();
324
325 FunctionUnderTest(); // invokes StaticTestFunction()
326
327 // act
328 tstring result = testMock.CompareActualAndExpectedCalls();
329
330 // assert
331 Assert::AreEqual(tstring(_T("")), result,
332 _T("Incorrect mock function call result"));
333 }
334 ```
335
336 Test result:
337 Assert failed. Expected:<> Actual:<[Unexpected: CTestStaticMock::StaticTestFunction()]> - Incorrect mock function call result
338 ## IgnoreArgument
339 This expectation modifier specifies that a specific argument is to be ignored when matching expected and actual calls. The argument is identified by its index, starting with the first argument having index 1.
340 Example test:
341 ```c
342 TEST_METHOD(IgnoreArgument_Ignores_An_Argument_By_Its_Index)
343 {
344 // arrange
345 CTestStaticMock testMock;
346
347 STRICT_EXPECTED_CALL(testMock, StaticTestFunction(42))
348 .IgnoreArgument(1);
349
350 FunctionUnderTest(); // invokes StaticTestFunction(43)
351
352 // act
353 tstring result = testMock.CompareActualAndExpectedCalls();
354
355 // assert
356 Assert::AreEqual(tstring(_T("")), result,
357 _T("Incorrect mock function call result"));
358 }
359 ```
360
361 Test result: Pass
362 ## ValidateArgument
363 This expectation modifier specifies that a specific argument is to be validated when matching expected and actual calls. The argument is identified by its index, starting with the first argument having index 1.
364 Example test:
365 ```c
366 TEST_METHOD(ValidateArgument_Forces_Validation_For_An_Argument_By_Its_Index)
367 {
368
369 // arrange
370 CTestStaticMock testMock;
371
372 EXPECTED_CALL(testMock, StaticTestFunction(42))
373 .ValidateArgument(1);
374
375 FunctionUnderTest(); // invokes StaticTestFunction(43)
376
377 // act
378 tstring result = testMock.CompareActualAndExpectedCalls();
379
380 // assert
381 Assert::AreEqual(tstring(_T("")), result,
382 _T("Incorrect mock function call result"));
383 }
384 ```
385
386 Test result:
387 Assert failed. Expected:<> Actual:<[Unexpected: CTestStaticMock::StaticTestFunction(42)] [Missing: CTestStaticMock::StaticTestFunction(43)]> - Incorrect mock function call result
388
389 ## ValidateArgumentBuffer
390
391 This expectation modifier specifies that a specific argument is to be treated as a pointer and its buffer contents should be validated against a user supplied buffer.
392 The modifier takes as arguments the argument number, the expected contents as a buffer, the number of bytes to compare and an offset where the comparison should start.
393 The expected data to be compared against is copied by the mocking framework internally, so there is no need to maintain that data unchanged for the entire test lifetime.
394 Example test:
395 ```c
396 TEST_METHOD(MicroMock_ValidateArgumentBuffer_When_Expected_Memory_Does_Not_Match_Indicate s_A_Call_Mismatch)
397 {
398 // arrange
399 CTestOutArgMock testMock;
400 UINT8 expectedBuffer[1] = {43};
401 UINT8 actualBuffer [1] = {42};
402
403 STRICT_EXPECTED_CALL(testMock, TestFunction(NULL))
404 .ValidateArgumentBuffer(1, expectedBuffer, sizeof(expectedBuffer));
405
406 // act
407 testMock.TestFunction(actualBuffer);
408
409 // assert
410 Assert::AreNotEqual(tstring(_T("")), testMock.CompareActualAndExpectedCalls(),
411 _T("Incorrect mock function call result"));
412 }
413 ```
414
415 Test result:
416
417 Assert failed.
418 To compare only the second byte of a 2 bytes out argument's buffer, a call like below would be used, indicating to start the compare at offset 1:
419 STRICT_EXPECTED_CALL(testMock, TestFunction(expectedBuffer))
420 .ValidateArgumentBuffer(1, expectedBuffer, 1, 1);
421
422 ## CopyOutArgumentBuffer
423
424 This expectation modifier specifies that data should be copied into the buffer pointed to by a specific argument.
425 The modifier takes as arguments the argument number, the data to be injected, the number of bytes to be injected and an offset where the data copy into the out argument buffer should start.
426 The supplied data to be injected is copied by the mocking framework internally, so there is no need to maintain that data unchanged for the entire test lifetime.
427 Example test:
428 ```c
429 TEST_METHOD(MicroMock_CopyOutArgumentBuffer_Only_First_Byte_Out_Of_2_Bytes_Is_Copied)
430 {
431 // arrange
432 CTestArgBufferMock testMock;
433 UINT8 injectedOutBuffer[2] = {0x42, 0x42};
434 UINT8 actualArgumentBuffer[2] = {0, 0};
435
436 STRICT_EXPECTED_CALL(testMock, TestFunction(NULL))
437 .CopyOutArgumentBuffer(1, injectedOutBuffer, 1);
438
439 // act
440 testMock.TestFunction(actualArgumentBuffer);
441
442 // assert
443 Assert::AreEqual(tstring(_T("[42 0]")), BytesToString(actualArgumentBuffer, sizeof(actualArgumentBuffer)),
444 _T("Only the first byte should be copied"));
445 }
446 ```
447 Test result:
448 Pass.
449 To compare only the second byte of a 2 bytes out argument's buffer, a call like below would be used, indicating to start the data copy at offset 1:
450 ```c
451 STRICT_EXPECTED_CALL(testMock, TestFunction(NULL))
452 .CopyOutArgumentBuffer(1, injectedOutBuffer, 1, 1);
453 ```