docs/components/cppumock.rst

CppUMock
========

CppUMock is the built-in mocking system of CppUTest. This chapter describes the
basic features of the system. For details please refer the `official CppUMock
manual`_.

System functions
----------------

Checking expectations
^^^^^^^^^^^^^^^^^^^^^

After defining expected calls an invoking actual call the test should check if
all the expected calls have happened. This can be done by calling
``mock().checkExpectations()``. The common place to put this function call is
the ``TEST_TEARDOWN`` function of the test group.


Resetting mocking system
^^^^^^^^^^^^^^^^^^^^^^^^

After the last interaction with the mocking system the developer should reset
the state of the system by calling ``mock().clear()``. The common place to put
this function call is the ``TEST_TEARDOWN`` function of the test group after
calling ``mock().checkExpectations()``.


Namespaces
^^^^^^^^^^

All interactions with the mocking system start by calling ``mock()``. This
function has an option ``name`` string parameter which can be used for limiting
the scope of the mocking operation.

.. code-block:: C++

  mock("bl1").expectOneCall("bl1_main");


Enable/disable
^^^^^^^^^^^^^^

The mocking system can be enabled/disabled runtime using the functions below.
This causes call expected and actual call to be ignored. Default settings are
restored by ``mock().clear()``.

- ``enable()``
- ``disable()``

.. code-block:: C++

  mock().disable();
  // All CppUMock calls are ignored after this point
  mock().enable();
  // CppUMock calls are working again

  mock().disable();
  // All CppUMock calls are ignored after this point
  [...]

  mock().clear();
  // Default settings are restored


String order
^^^^^^^^^^^^

After defining multiple expected function call the mocking system always
The mocking system always uses the next matching function when an actual call
happens but by default it doesn't check if different function calls happen in
the order of definition. This behaviour can be turned on using the
``mock().strictOrder()`` function. This option is also set to default by the
``mock().clear()`` function.

.. code-block:: C++

  mock().expectOneCall("A");
  mock().expectOneCall("B");

  mock().actualCall("B");
  mock().actualCall("A");
  // No error

  mock().strictOrder();
  mock().expectOneCall("A");
  mock().expectOneCall("B");

  mock().actualCall("B"); // Error generated here
  mock().actualCall("A");


Ignoring unspecified calls
^^^^^^^^^^^^^^^^^^^^^^^^^^

If there are addition actual calls happening in the test case which are
unrelated to the test case (i.e. log or other messages) the unspecified calls
can be ignored by adding ``mock().ignoreOtherCalls()`` to the test case. This
function should be used carefully because it can hide unexpected call which are
indicating errors in the code. The affect of this call ends by calling
``mock().clear()``.


Specifying object
-----------------

In object oriented environment member function should validate if the function
call happened on the suitable object. This is done by adding the following
function to the mock specification.

- ``onObject(objectPtr)``


Validating parameters
---------------------

Each supported parameter type has a corresponding function. These are the same
in the expected and actual calls.

- ``withBoolParameter(name, bool value)``
- ``withIntParameter(name, int value)``
- ``withUnsignedIntParameter(name, unsigned int value)``
- ``withLongIntParameter(name, long int value)``
- ``withUnsignedLongIntParameter(name, unsigned long int value)``
- ``withDoubleParameter(name, double value)``
- ``withStringParameter(name, const char* value)``
- ``withPointerParameter(name, void* value)``
- ``withFunctionPointerParameter(name, void (*value)())``
- ``withConstPointerParameter(name, const void* value)``
- ``withMemoryBufferParameter(name, const unsigned char* value, size_t size)``

If custum types are defined and copier/comparator objects were installed the
following function can handle these parameters.

- ``withParameterOfType(typeName, name, value)``

There's an option to copying data from the test environment into the mock
function. When setting expectations the following function can be used to set
the pointer and the address of the data. **The mocking system will not create a
copy of this data** so the original data should be kept intact until the actual
call happens.

- ``withOutputParameterReturning(name, value, size)``
- ``withOutputParameterOfTypeReturning(typeName, name, value)``

In the actual call the pair of these function are shown below.

- ``withOutputParameter(name, output)``
- ``withOutputParameterOfType(typeName, name, output)``


Ignoring parameters
^^^^^^^^^^^^^^^^^^^

There are cases when the developer doesn't want to specify all parameters. The
following function can set this behaviour in the expected call.

- ``ignoreOtherParameters()``


Specifying return values
------------------------

Using function name overloading the return values are specified by calling
``andReturnValue`` and the parameter type will determine the exact function.

- ``andReturnValue(bool value)``
- ``andReturnValue(int value)``
- ``andReturnValue(unsigned int value)``
- ``andReturnValue(long int value)``
- ``andReturnValue(unsigned long int value)``
- ``andReturnValue(double value)``
- ``andReturnValue(const char* value)``
- ``andReturnValue(void* value)``
- ``andReturnValue(const void* value)``
- ``andReturnValue(void (*value)())``


Returning value in actual calls
-------------------------------

All of these function have version with ``OrDefault(type default_value)``
suffix. These version return a default value if the return value was not
specified in the expected call.

- ``bool returnBoolValue()``
- ``int returnIntValue()``
- ``unsigned int returnUnsignedIntValue()``
- ``long int returnLongIntValue()``
- ``unsigned long int returnUnsignedLongIntValue()``
- ``double returnDoubleValue()``
- ``const char * returnStringValue()``
- ``void * returnPointerValue()``
- ``const void * returnConstPointerValue()``
- ``void (*returnFunctionPointerValue())()``


Debugging CppUMock errors
-------------------------

Debugging CppUMock errors can be hard unlike assertion errors because a mocking
failure can happen multiple layers of function calls under the test case. The
mocking system has a very similar feature to CppUTest's ``UT_CRASH()`` which is
``mock().crashOnFailure()``. By enabling this feature the code will crash on
mocking errors and the developer could easily catch it with the debugger.


--------------

*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*

.. _`official CppUMock manual`: https://cpputest.github.io/mocking_manual.html