# MicroMock # Why? Micromock is intended to fulfill the needs of the (connected car networking) developers in mocking dependencies. The following are the main goals: - Allow runtime mocking by using Detours, since this is the main case where mocking is really needed. - 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. - Writing tests with the framework should not require verbosity. - Comparing expected calls and actual calls should explicitly state what the mismatch is. # Cheat sheet ## Declaring a mock class ```c TYPED_MOCK_CLASS(CMultimediaTimerMock, CRuntimeMock) { public: MOCK_HOOK_METHOD_5(WINAPI, timeSetEvent, MMRESULT, UINT, uDelay, UINT, uResolution, LPTIMECALLBACK, lpTimeProc, DWORD_PTR, dwUser, UINT, fuEvent) MOCK_METHOD_END(MMRESULT, 0x0) }; ``` 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. Also the mock method by default returns 0, as specified by the MOCK_METHOD_END macro. ## Instantiating mocks CRuntimeMock multimediaTimerMock; ## Specifying expected calls in a test Specifying an expected call is done by using the EXPECTED_CALL macro: ```c EXPECTED_CALL(multimediaTimerMock, timeSetEvent(0, TEST_MILLISECONDS_DELAY, NULL, NULL, TIME_CALLBACK_FUNCTION)); ``` ## Overriding a return value for an expected call 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: ```c EXPECTED_CALL(multimediaTimerMock, timeSetEvent(0, TEST_MILLISECONDS_DELAY, NULL, NULL, TIME_CALLBACK_FUNCTION)) .SetReturn(42); ``` ## Overriding a return value for an expected call with a fail return value 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: ```c EXPECTED_CALL(multimediaTimerMock, timeSetEvent(0, TEST_MILLISECONDS_DELAY, NULL, NULL, TIME_CALLBACK_FUNCTION)) .SetFailReturn(42); ``` 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 as soon as it has matched the call. ## A simple test ```c TEST_METHOD(When_The_Multimedia_Timer_Creation_Is_Successful_DoWork_Succeeds) { // arrange CClassUnderTest classUnderTest; CMultimediaTimerMock multimediaTimerMock; EXPECTED_CALL(multimediaTimerMock, timeSetEvent(0, TEST_MILLISECONDS_DELAY, NULL, NULL, TIME_CALLBACK_FUNCTION)) // classUnderTest.DoWork will see 0x42 as result to the timeSetEvent call .SetReturn(0x42); // act BOOL result = classUnderTest.DoWork(TEST_MILLISECONDS_DELAY); // assert Assert::AreEqual(TRUE, result, _T("DoWork should succeed when the timeSetEvent succeeds.")); } ``` # Mock classes In order to declare a mock class, the TYPED_MOCK_CLASS macro can be used: ```c TYPED_MOCK_CLASS(CTestMock, CRuntimeMock) { public: ... }; ``` Then the instantiation of the mock in the test looks like: ```c CTestMock testMock; ``` There are 4 types of mocks: ## CMock This mock type is the simplest. It provides the ability to setup expected calls, record actual calls and compare the 2 lists. ## CThreadSafeGlobalMock 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. ## CRuntimeMock This mock type provides all the CThreadSafeGlobalMock functionality and in addition it allows installing hooks by using Detours. # Mock methods 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. Currently methods with up to 10 arguments are supported. A mock method without any arguments uses the MOCK_METHOD_0 macro. ## MOCK_METHOD_x ```c MOCK_METHOD_x(prefix, returnType, name, arg1Type, arg1Value, arg2Type, ...) ``` declares a mock class member method. ## MOCK_STATIC_METHOD_x ```c MOCK_STATIC_METHOD_x(prefix, returnType, name, arg1Type, arg1Value, arg2Type, ...) ``` declares a mock class member static method. A static method can only be used in a CThreadSafeGlobalMock or CRuntimeMock mock class. ## MOCK_HOOK_METHOD_x ```c MOCK_HOOK_METHOD_x(prefix, returnType, name, arg1Type, arg1Value, arg2Type, ...) ``` 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. ## MOCK_HOOK_METHOD_EX_x ```c MOCK_HOOK_METHOD_EX_x(prefix, returnType, name, arg1Type, arg1Value, arg2Type, ..., functionToHook) ``` declares a hook mock method and additionally instructs the framework to hook a specific function (functionToHook) and redirect all calls to the mock method. # Actual vs Expected call comparison ## CompareActualAndExpectedCalls 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. ```c tstring result = multimediaTimerMock.CompareActualAndExpectedCalls(); Assert::AreEqual(tstring(_T("")), result, _T("Incorrect mock function call result")); ``` 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)]". 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)]". ## GetUnexpectedCalls/GetMissingCalls In order to facilitate writing asserts in a natural way, the following syntax can also be used: ```c Assert::AreEqual(testMock.GetMissingCalls(),testMock.GetUnexpectedCalls(), _T("Incorrect mock function call result")); ``` ## Arguments in call comparisons When comparing an expected call and an actual call, arguments are taken into account according to what has been setup on the expected call. 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. 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. ValidateArgument and IgnoreArgument are mutually exclusive. If both of them are used on the same expected call, the last one sticks. ## Special handling for some argument types ### Structures 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. 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: - The equality operator - The stream insertion << operator ### Defining pointer equality operators In order to allow the mocking framework to directly compare pointer types, the equality operator for the type itself needs to be defined. ```c _Must_inspect_result_ static bool operator==(_In_ SOCKADDR const& lhs, _In_ SOCKADDR const& rhs) { if (lhs.sa_family != rhs.sa_family) { return false; } if (lhs.sa_family == AF_INET) { return ... ; // more comparison of the structure members should be done here } return (memcmp(lhs.sa_data, rhs.sa_data, sizeof(rhs.sa_data)) == 0); } ``` Additionally a specialization of the == operator for the MockValue class (internally used by the framework) should be provided: MICROMOCK_POINTER_TYPE_EQUAL(SOCKADDR const); Then any test can specify the arguments of the type SOCKADDR const* to be compared as regular arguments in any expected function calls. ## Call comparers 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. ### StrictUnorderedCallComparer 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. 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. ### StrictOrderedCallComparer 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. ### NiceCallComparer 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. Example test: ```c TEST_METHOD(NiceCallComparer_Ignores_Unexpected_Calls) { // arrange CNiceCallComparer testMock; FunctionUnderTest() // invokes CTestStaticMock::StaticTestFunction(43); // act tstring result = testMock.CompareActualAndExpectedCalls(); // assert Assert::AreEqual(tstring(_T("")), result, _T("Incorrect mock function call result")); } ``` ## Resetting expected and actual calls 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. 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. 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. Good tests do not typically require these features, so they should be used cautiously. # Non-compare actions 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. 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. 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. For these cases the construct WHEN_CALLED can be used, as shown below: ```c TEST_METHOD(When_Called_Is_Not_Used_In_Call_Comparison) { // arrange CTestStaticMock tickCountMock; WHEN_CALLED(tickCountMock, GetTickCount64()) .SetReturn(42); FunctionUnderTest(); // invokes GetTickCount64() 7 times and all 7 calls return 42 // act tstring result = testMock.CompareActualAndExpectedCalls(); // assert Assert::AreEqual(tstring(_T("")), result, _T("Incorrect mock function call result")); } ``` WHEN_CALLED does not validate argument values by default. 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. # Custom mocks It is possible to write custom mock code directly in the mock class. ```c TYPED_MOCK_CLASS(CTestStaticMock, CRuntimeMock) { public: MOCK_STATIC_METHOD_1(, UINT8, StaticTestFunctionWith1Arg, UINT8, arg1) if (4200 == arg1) { return 45; } MOCK_METHOD_END(UINT8, 0) }; ``` # Automatic runtime hooks installation In order to avoid installing the hooks in every test, it is possible to specify in the class declaration which hooks should be installed: ```c TYPED_MOCK_CLASS(CTestStaticMock, CRuntimeMock) { public: MOCK_HOOK_METHOD_0(, UINT64, GetTickCount64) MOCK_METHOD_END(UINT64, 0) }; ``` Runtime hooks work only with the CRuntimeMock class. Hooks can be declared by : - specifying mock hook methods (with MOCK_HOOK_METHOD_x or MOCK_HOOK_METHOD_EX_x) - using the INSTALL_HOOK macro. The INSTALL_HOOK macro instructs the framework to hook a function every time the mock class is instantiated. Example: ```c TYPED_MOCK_CLASS(CTestStaticMock, CRuntimeMock) { public: MOCK_HOOK_METHOD_0(, UINT64, MyGetTickCount64) MOCK_METHOD_END(UINT64, 0) INSTALL_HOOK(::GetTickCount64, MyGetTickCount64) }; ``` All hooks specified by MOCK_HOOK_xxx methods or INSTALL_HOOK are automatically reverted when the mock class is destroyed. # Expectation modifier details ## SetReturn 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. Example test: ```c TYPED_MOCK_CLASS(CTestStaticMock, CThreadSafeGlobalMock) { public: MOCK_STATIC_METHOD_0(, UINT8, StaticTestFunction) MOCK_METHOD_END(UINT8, 1) }; UINT8 FunctionUnderTest() { return StaticTestFunction(); } TEST_METHOD(SetReturn_Overrides_The_Return_Value_Of_The_Mock) { // arrange CTestStaticMock testMock; STRICT_EXPECTED_CALL(testMock, StaticTestFunction()) .SetReturn(42); // act UINT8 result = FunctionUnderTest(); // StaticTestFunction returns 42 // assert Assert::AreEqual((UINT8)42, result, _T("Incorrect mock function call result")); } ``` Test result: Pass ## NeverInvoked 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. Example test: ```c TEST_METHOD(NeverInvoked_When_An_Actual_Call_Is_Made_Indicates_A_Mismatch) { // arrange CTestStaticMock testMock; STRICT_EXPECTED_CALL(testMock, StaticTestFunction()) .NeverInvoked(); FunctionUnderTest(); // invokes StaticTestFunction() // act tstring result = testMock.CompareActualAndExpectedCalls(); // assert Assert::AreEqual(tstring(_T("")), result, _T("Incorrect mock function call result")); } ``` Test result: Assert failed. Expected:<> Actual:<[Unexpected: CTestStaticMock::StaticTestFunction()]> - Incorrect mock function call result ## IgnoreArgument 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. Example test: ```c TEST_METHOD(IgnoreArgument_Ignores_An_Argument_By_Its_Index) { // arrange CTestStaticMock testMock; STRICT_EXPECTED_CALL(testMock, StaticTestFunction(42)) .IgnoreArgument(1); FunctionUnderTest(); // invokes StaticTestFunction(43) // act tstring result = testMock.CompareActualAndExpectedCalls(); // assert Assert::AreEqual(tstring(_T("")), result, _T("Incorrect mock function call result")); } ``` Test result: Pass ## ValidateArgument 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. Example test: ```c TEST_METHOD(ValidateArgument_Forces_Validation_For_An_Argument_By_Its_Index) { // arrange CTestStaticMock testMock; EXPECTED_CALL(testMock, StaticTestFunction(42)) .ValidateArgument(1); FunctionUnderTest(); // invokes StaticTestFunction(43) // act tstring result = testMock.CompareActualAndExpectedCalls(); // assert Assert::AreEqual(tstring(_T("")), result, _T("Incorrect mock function call result")); } ``` Test result: Assert failed. Expected:<> Actual:<[Unexpected: CTestStaticMock::StaticTestFunction(42)] [Missing: CTestStaticMock::StaticTestFunction(43)]> - Incorrect mock function call result ## ValidateArgumentBuffer 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. 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. 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. Example test: ```c TEST_METHOD(MicroMock_ValidateArgumentBuffer_When_Expected_Memory_Does_Not_Match_Indicate s_A_Call_Mismatch) { // arrange CTestOutArgMock testMock; UINT8 expectedBuffer[1] = {43}; UINT8 actualBuffer [1] = {42}; STRICT_EXPECTED_CALL(testMock, TestFunction(NULL)) .ValidateArgumentBuffer(1, expectedBuffer, sizeof(expectedBuffer)); // act testMock.TestFunction(actualBuffer); // assert Assert::AreNotEqual(tstring(_T("")), testMock.CompareActualAndExpectedCalls(), _T("Incorrect mock function call result")); } ``` Test result: Assert failed. 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: STRICT_EXPECTED_CALL(testMock, TestFunction(expectedBuffer)) .ValidateArgumentBuffer(1, expectedBuffer, 1, 1); ## CopyOutArgumentBuffer This expectation modifier specifies that data should be copied into the buffer pointed to by a specific argument. 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. 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. Example test: ```c TEST_METHOD(MicroMock_CopyOutArgumentBuffer_Only_First_Byte_Out_Of_2_Bytes_Is_Copied) { // arrange CTestArgBufferMock testMock; UINT8 injectedOutBuffer[2] = {0x42, 0x42}; UINT8 actualArgumentBuffer[2] = {0, 0}; STRICT_EXPECTED_CALL(testMock, TestFunction(NULL)) .CopyOutArgumentBuffer(1, injectedOutBuffer, 1); // act testMock.TestFunction(actualArgumentBuffer); // assert Assert::AreEqual(tstring(_T("[42 0]")), BytesToString(actualArgumentBuffer, sizeof(actualArgumentBuffer)), _T("Only the first byte should be copied")); } ``` Test result: Pass. 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: ```c STRICT_EXPECTED_CALL(testMock, TestFunction(NULL)) .CopyOutArgumentBuffer(1, injectedOutBuffer, 1, 1); ```