Mock Objects

Collaboration diagram for Mock Objects:

Functions
LargestIntegralType	mock (void)
	Retrieve a return value of the current function.
type	mock_ptr_type (#type)
	Retrieve a typed return value of the current function.
void	will_return (#function, LargestIntegralType value)
	Store a value to be returned by mock() later.
void	will_return_count (#function, LargestIntegralType value, int count)
	Store a value to be returned by mock() later.
void	will_return_always (#function, LargestIntegralType value)
	Store a value that will be always returned by mock().
void	will_return_maybe (#function, LargestIntegralType value)
	Store a value that may be always returned by mock().

Detailed Description

Mock objects are simulated objects that mimic the behavior of real objects. Instead of calling the real objects, the tested object calls a mock object that merely asserts that the correct methods were called, with the expected parameters, in the correct order.

• will_return(function, value) - The will_return() macro pushes a value onto a stack of mock values. This macro is intended to be used by the unit test itself, while programming the behaviour of the mocked object.

• mock() - the mock macro pops a value from a stack of test values. The user of the mock() macro is the mocked object that uses it to learn how it should behave.

Because the will_return() and mock() are intended to be used in pairs, the cmocka library would fail the test if there are more values pushed onto the stack using will_return() than consumed with mock() and vice-versa.

The following unit test stub illustrates how would a unit test instruct the mock object to return a particular value:

will_return(chef_cook, "hotdog");
will_return(chef_cook, 0);

Now the mock object can check if the parameter it received is the parameter which is expected by the test driver. This can be done the following way:

int chef_cook(const char *order, char **dish_out)
{
    check_expected(order);
}

For a complete example please take a look here.

Function Documentation

mock()

LargestIntegralType mock

(

void

)

Retrieve a return value of the current function.

Returns

The value which was stored to return by this function.

See also

will_return()

mock_ptr_type()

type mock_ptr_type

(

#

type

)

Retrieve a typed return value of the current function.

The value would be casted to type internally to avoid having the caller to do the cast manually.

Parameters

[in]

type

The expected type of the return value

Returns

The value which was stored to return by this function.

int param;
 
param = mock_type(int);

See also

will_return()

mock()

mock_ptr_type()

Retrieve a typed return value of the current function.

The value would be casted to type internally to avoid having the caller to do the cast manually but also casted to uintptr_t to make sure the result has a valid size to be used as a pointer.

Parameters

[in]

type

The expected type of the return value

Returns

The value which was stored to return by this function.

char *param;
 
param = mock_ptr_type(char *);

See also

will_return()

mock()

mock_type()

will_return()

void will_return	(	#	function,
		LargestIntegralType	value
	)

Store a value to be returned by mock() later.

Parameters

[in]		function	The function which should return the given value.
[in]		value	The value to be returned by mock().

int return_integer(void)
{
     return (int)mock();
}
 
static void test_integer_return(void **state)
{
     will_return(return_integer, 42);
 
     assert_int_equal(my_function_calling_return_integer(), 42);
}

See also

mock()

will_return_count()

will_return_always()

void will_return_always	(	#	function,
		LargestIntegralType	value
	)

Store a value that will be always returned by mock().

Parameters

[in]		function	The function which should return the given value.
[in]		value	The value to be returned by mock().

This is equivalent to:

will_return_count(function, value, -1);

See also

will_return_count()

mock()

will_return_count()

void will_return_count	(	#	function,
		LargestIntegralType	value,
		int	count
	)

Store a value to be returned by mock() later.

Parameters

[in]		function	The function which should return the given value.
[in]		value	The value to be returned by mock().
[in]		count	The parameter indicates the number of times the value should be returned by mock(). If count is set to -1, the value will always be returned but must be returned at least once. If count is set to -2, the value will always be returned by mock(), but is not required to be returned.

See also

mock()

will_return_maybe()

void will_return_maybe	(	#	function,
		LargestIntegralType	value
	)

Store a value that may be always returned by mock().

This stores a value which will always be returned by mock() but is not required to be returned by at least one call to mock(). Therefore, in contrast to will_return_always() which causes a test failure if it is not returned at least once, will_return_maybe() will never cause a test to fail if its value is not returned.

Parameters

[in]		function	The function which should return the given value.
[in]		value	The value to be returned by mock().

This is equivalent to:

will_return_count(function, value, -2);

See also

will_return_count()

mock()