blob: 145c4ad1196eef936fb26f7f4b148513e1939a5b [file] [log] [blame]
Imre Kis1d2fbdd2019-12-13 11:42:08 +01001CppUMock
2========
3
4CppUMock is the built-in mocking system of CppUTest. This chapter describes the
5basic features of the system. For details please refer the `official CppUMock
6manual`_.
7
8System functions
9----------------
10
11Checking expectations
12^^^^^^^^^^^^^^^^^^^^^
13
14After defining expected calls an invoking actual call the test should check if
15all the expected calls have happened. This can be done by calling
16``mock().checkExpectations()``. The common place to put this function call is
17the ``TEST_TEARDOWN`` function of the test group.
18
19
20Resetting mocking system
21^^^^^^^^^^^^^^^^^^^^^^^^
22
23After the last interaction with the mocking system the developer should reset
24the state of the system by calling ``mock().clear()``. The common place to put
25this function call is the ``TEST_TEARDOWN`` function of the test group after
26calling ``mock().checkExpectations()``.
27
28
29Namespaces
30^^^^^^^^^^
31
32All interactions with the mocking system start by calling ``mock()``. This
33function has an option ``name`` string parameter which can be used for limiting
34the scope of the mocking operation.
35
36.. code-block:: C++
37
38 mock("bl1").expectOneCall("bl1_main");
39
40
41Enable/disable
42^^^^^^^^^^^^^^
43
44The mocking system can be enabled/disabled runtime using the functions below.
45This causes call expected and actual call to be ignored. Default settings are
46restored 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
66String order
67^^^^^^^^^^^^
68
69After defining multiple expected function call the mocking system always
70The mocking system always uses the next matching function when an actual call
71happens but by default it doesn't check if different function calls happen in
72the 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
93Ignoring unspecified calls
94^^^^^^^^^^^^^^^^^^^^^^^^^^
95
96If there are addition actual calls happening in the test case which are
97unrelated to the test case (i.e. log or other messages) the unspecified calls
98can be ignored by adding ``mock().ignoreOtherCalls()`` to the test case. This
99function should be used carefully because it can hide unexpected call which are
100indicating errors in the code. The affect of this call ends by calling
101``mock().clear()``.
102
103
104Specifying object
105-----------------
106
107In object oriented environment member function should validate if the function
108call happened on the suitable object. This is done by adding the following
109function to the mock specification.
110
111- ``onObject(objectPtr)``
112
113
114Validating parameters
115---------------------
116
117Each supported parameter type has a corresponding function. These are the same
118in 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
132If custum types are defined and copier/comparator objects were installed the
133following function can handle these parameters.
134
135- ``withParameterOfType(typeName, name, value)``
136
137There's an option to copying data from the test environment into the mock
138function. When setting expectations the following function can be used to set
139the pointer and the address of the data. **The mocking system will not create a
140copy of this data** so the original data should be kept intact until the actual
141call happens.
142
143- ``withOutputParameterReturning(name, value, size)``
144- ``withOutputParameterOfTypeReturning(typeName, name, value)``
145
146In the actual call the pair of these function are shown below.
147
148- ``withOutputParameter(name, output)``
149- ``withOutputParameterOfType(typeName, name, output)``
150
151
152Ignoring parameters
153^^^^^^^^^^^^^^^^^^^
154
155There are cases when the developer doesn't want to specify all parameters. The
156following function can set this behaviour in the expected call.
157
158- ``ignoreOtherParameters()``
159
160
161Specifying return values
162------------------------
163
164Using 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
179Returning value in actual calls
180-------------------------------
181
182All of these function have version with ``OrDefault(type default_value)``
183suffix. These version return a default value if the return value was not
184specified 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
198Debugging CppUMock errors
199-------------------------
200
201Debugging CppUMock errors can be hard unlike assertion errors because a mocking
202failure can happen multiple layers of function calls under the test case. The
203mocking 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
205mocking 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