Imre Kis | 1d2fbdd | 2019-12-13 11:42:08 +0100 | [diff] [blame^] | 1 | CppUMock |
| 2 | ======== |
| 3 | |
| 4 | CppUMock is the built-in mocking system of CppUTest. This chapter describes the |
| 5 | basic features of the system. For details please refer the `official CppUMock |
| 6 | manual`_. |
| 7 | |
| 8 | System functions |
| 9 | ---------------- |
| 10 | |
| 11 | Checking expectations |
| 12 | ^^^^^^^^^^^^^^^^^^^^^ |
| 13 | |
| 14 | After defining expected calls an invoking actual call the test should check if |
| 15 | all the expected calls have happened. This can be done by calling |
| 16 | ``mock().checkExpectations()``. The common place to put this function call is |
| 17 | the ``TEST_TEARDOWN`` function of the test group. |
| 18 | |
| 19 | |
| 20 | Resetting mocking system |
| 21 | ^^^^^^^^^^^^^^^^^^^^^^^^ |
| 22 | |
| 23 | After the last interaction with the mocking system the developer should reset |
| 24 | the state of the system by calling ``mock().clear()``. The common place to put |
| 25 | this function call is the ``TEST_TEARDOWN`` function of the test group after |
| 26 | calling ``mock().checkExpectations()``. |
| 27 | |
| 28 | |
| 29 | Namespaces |
| 30 | ^^^^^^^^^^ |
| 31 | |
| 32 | All interactions with the mocking system start by calling ``mock()``. This |
| 33 | function has an option ``name`` string parameter which can be used for limiting |
| 34 | the scope of the mocking operation. |
| 35 | |
| 36 | .. code-block:: C++ |
| 37 | |
| 38 | mock("bl1").expectOneCall("bl1_main"); |
| 39 | |
| 40 | |
| 41 | Enable/disable |
| 42 | ^^^^^^^^^^^^^^ |
| 43 | |
| 44 | The mocking system can be enabled/disabled runtime using the functions below. |
| 45 | This causes call expected and actual call to be ignored. Default settings are |
| 46 | restored by ``mock().clear()``. |
| 47 | |
| 48 | - ``enable()`` |
| 49 | - ``disable()`` |
| 50 | |
| 51 | .. code-block:: C++ |
| 52 | |
| 53 | mock().disable(); |
| 54 | // All CppUMock calls are ignored after this point |
| 55 | mock().enable(); |
| 56 | // CppUMock calls are working again |
| 57 | |
| 58 | mock().disable(); |
| 59 | // All CppUMock calls are ignored after this point |
| 60 | [...] |
| 61 | |
| 62 | mock().clear(); |
| 63 | // Default settings are restored |
| 64 | |
| 65 | |
| 66 | String order |
| 67 | ^^^^^^^^^^^^ |
| 68 | |
| 69 | After defining multiple expected function call the mocking system always |
| 70 | The mocking system always uses the next matching function when an actual call |
| 71 | happens but by default it doesn't check if different function calls happen in |
| 72 | the order of definition. This behaviour can be turned on using the |
| 73 | ``mock().strictOrder()`` function. This option is also set to default by the |
| 74 | ``mock().clear()`` function. |
| 75 | |
| 76 | .. code-block:: C++ |
| 77 | |
| 78 | mock().expectOneCall("A"); |
| 79 | mock().expectOneCall("B"); |
| 80 | |
| 81 | mock().actualCall("B"); |
| 82 | mock().actualCall("A"); |
| 83 | // No error |
| 84 | |
| 85 | mock().strictOrder(); |
| 86 | mock().expectOneCall("A"); |
| 87 | mock().expectOneCall("B"); |
| 88 | |
| 89 | mock().actualCall("B"); // Error generated here |
| 90 | mock().actualCall("A"); |
| 91 | |
| 92 | |
| 93 | Ignoring unspecified calls |
| 94 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 95 | |
| 96 | If there are addition actual calls happening in the test case which are |
| 97 | unrelated to the test case (i.e. log or other messages) the unspecified calls |
| 98 | can be ignored by adding ``mock().ignoreOtherCalls()`` to the test case. This |
| 99 | function should be used carefully because it can hide unexpected call which are |
| 100 | indicating errors in the code. The affect of this call ends by calling |
| 101 | ``mock().clear()``. |
| 102 | |
| 103 | |
| 104 | Specifying object |
| 105 | ----------------- |
| 106 | |
| 107 | In object oriented environment member function should validate if the function |
| 108 | call happened on the suitable object. This is done by adding the following |
| 109 | function to the mock specification. |
| 110 | |
| 111 | - ``onObject(objectPtr)`` |
| 112 | |
| 113 | |
| 114 | Validating parameters |
| 115 | --------------------- |
| 116 | |
| 117 | Each supported parameter type has a corresponding function. These are the same |
| 118 | in the expected and actual calls. |
| 119 | |
| 120 | - ``withBoolParameter(name, bool value)`` |
| 121 | - ``withIntParameter(name, int value)`` |
| 122 | - ``withUnsignedIntParameter(name, unsigned int value)`` |
| 123 | - ``withLongIntParameter(name, long int value)`` |
| 124 | - ``withUnsignedLongIntParameter(name, unsigned long int value)`` |
| 125 | - ``withDoubleParameter(name, double value)`` |
| 126 | - ``withStringParameter(name, const char* value)`` |
| 127 | - ``withPointerParameter(name, void* value)`` |
| 128 | - ``withFunctionPointerParameter(name, void (*value)())`` |
| 129 | - ``withConstPointerParameter(name, const void* value)`` |
| 130 | - ``withMemoryBufferParameter(name, const unsigned char* value, size_t size)`` |
| 131 | |
| 132 | If custum types are defined and copier/comparator objects were installed the |
| 133 | following function can handle these parameters. |
| 134 | |
| 135 | - ``withParameterOfType(typeName, name, value)`` |
| 136 | |
| 137 | There's an option to copying data from the test environment into the mock |
| 138 | function. When setting expectations the following function can be used to set |
| 139 | the pointer and the address of the data. **The mocking system will not create a |
| 140 | copy of this data** so the original data should be kept intact until the actual |
| 141 | call happens. |
| 142 | |
| 143 | - ``withOutputParameterReturning(name, value, size)`` |
| 144 | - ``withOutputParameterOfTypeReturning(typeName, name, value)`` |
| 145 | |
| 146 | In the actual call the pair of these function are shown below. |
| 147 | |
| 148 | - ``withOutputParameter(name, output)`` |
| 149 | - ``withOutputParameterOfType(typeName, name, output)`` |
| 150 | |
| 151 | |
| 152 | Ignoring parameters |
| 153 | ^^^^^^^^^^^^^^^^^^^ |
| 154 | |
| 155 | There are cases when the developer doesn't want to specify all parameters. The |
| 156 | following function can set this behaviour in the expected call. |
| 157 | |
| 158 | - ``ignoreOtherParameters()`` |
| 159 | |
| 160 | |
| 161 | Specifying return values |
| 162 | ------------------------ |
| 163 | |
| 164 | Using function name overloading the return values are specified by calling |
| 165 | ``andReturnValue`` and the parameter type will determine the exact function. |
| 166 | |
| 167 | - ``andReturnValue(bool value)`` |
| 168 | - ``andReturnValue(int value)`` |
| 169 | - ``andReturnValue(unsigned int value)`` |
| 170 | - ``andReturnValue(long int value)`` |
| 171 | - ``andReturnValue(unsigned long int value)`` |
| 172 | - ``andReturnValue(double value)`` |
| 173 | - ``andReturnValue(const char* value)`` |
| 174 | - ``andReturnValue(void* value)`` |
| 175 | - ``andReturnValue(const void* value)`` |
| 176 | - ``andReturnValue(void (*value)())`` |
| 177 | |
| 178 | |
| 179 | Returning value in actual calls |
| 180 | ------------------------------- |
| 181 | |
| 182 | All of these function have version with ``OrDefault(type default_value)`` |
| 183 | suffix. These version return a default value if the return value was not |
| 184 | specified in the expected call. |
| 185 | |
| 186 | - ``bool returnBoolValue()`` |
| 187 | - ``int returnIntValue()`` |
| 188 | - ``unsigned int returnUnsignedIntValue()`` |
| 189 | - ``long int returnLongIntValue()`` |
| 190 | - ``unsigned long int returnUnsignedLongIntValue()`` |
| 191 | - ``double returnDoubleValue()`` |
| 192 | - ``const char * returnStringValue()`` |
| 193 | - ``void * returnPointerValue()`` |
| 194 | - ``const void * returnConstPointerValue()`` |
| 195 | - ``void (*returnFunctionPointerValue())()`` |
| 196 | |
| 197 | |
| 198 | Debugging CppUMock errors |
| 199 | ------------------------- |
| 200 | |
| 201 | Debugging CppUMock errors can be hard unlike assertion errors because a mocking |
| 202 | failure can happen multiple layers of function calls under the test case. The |
| 203 | mocking system has a very similar feature to CppUTest's ``UT_CRASH()`` which is |
| 204 | ``mock().crashOnFailure()``. By enabling this feature the code will crash on |
| 205 | mocking errors and the developer could easily catch it with the debugger. |
| 206 | |
| 207 | |
| 208 | -------------- |
| 209 | |
| 210 | *Copyright (c) 2019-2020, Arm Limited. All rights reserved.* |
| 211 | |
| 212 | .. _`official CppUMock manual`: https://cpputest.github.io/mocking_manual.html |