It is often beneficial to make sure that functions are called in an order. More...

Collaboration diagram for Call Ordering:

Macros
#define	function_called() _function_called(__func__, __FILE__, __LINE__)

#define	expect_function_calls(function, times) _expect_function_call(#function, __FILE__, __LINE__, times)

#define	expect_function_call(function) _expect_function_call(#function, __FILE__, __LINE__, 1)

#define	expect_function_call_any(function) _expect_function_call(#function, __FILE__, __LINE__, -1)

#define	ignore_function_calls(function) _expect_function_call(#function, __FILE__, __LINE__, -2)

Detailed Description

It is often beneficial to make sure that functions are called in an order.

This is independent of mock returns and parameter checking as both of the aforementioned do not check the order in which they are called from different functions.

expect_function_call(function) - The expect_function_call() macro pushes an expectation onto the stack of expected calls.
function_called() - pops a value from the stack of expected calls. function_called() is invoked within the mock object that uses it.

expect_function_call() and function_called() are intended to be used in pairs. Cmocka will fail a test if there are more or less expected calls created (e.g. expect_function_call()) than consumed with function_called(). There are provisions such as ignore_function_calls() which allow this restriction to be circumvented in tests where mock calls for the code under test are not the focus of the test.

The following example illustrates how a unit test instructs cmocka to expect a function_called() from a particular mock, chef_sing():

void chef_sing(void);
void code_under_test()
{
  chef_sing();
}
void some_test(void **state)
{
    expect_function_call(chef_sing);
    code_under_test();
}

The implementation of the mock then must check whether it was meant to be called by invoking function_called():

void chef_sing()
{
    function_called();
}

Macro Definition Documentation

◆ expect_function_call

#define expect_function_call ( function ) _expect_function_call(#function, __FILE__, __LINE__, 1)

Definition at line 1465 of file cmocka.h.

Referenced by test_does_fail_for_unexpected_call(), test_does_fail_for_unmade_expected_call(), test_does_succeed_for_expected(), test_does_succeed_for_multiple_calls(), test_ordering_does_work_across_different_functions(), and test_ordering_fails_out_of_order().

◆ expect_function_call_any

#define expect_function_call_any ( function ) _expect_function_call(#function, __FILE__, __LINE__, -1)

Definition at line 1479 of file cmocka.h.

Referenced by test_fails_out_of_order_if_no_calls_found_on_any(), test_ordering_does_expect_at_least_one_call(), and test_ordering_fails_out_of_order_for_at_least_once_calls().

◆ expect_function_calls

#define expect_function_calls	(	function,
		times
	)	_expect_function_call(#function, __FILE__, __LINE__, times)

Definition at line 1450 of file cmocka.h.

Referenced by test_does_succeed_for_multiple_calls(), test_fails_if_zero_count_used(), and test_ordering_ignores_out_of_order_properly().

◆ function_called

#define function_called ( ) _function_called(__func__, __FILE__, __LINE__)

Definition at line 1434 of file cmocka.h.

Referenced by mock_test_a_called(), mock_test_b_called(), and mock_test_c_called().

◆ ignore_function_calls

#define ignore_function_calls ( function ) _expect_function_call(#function, __FILE__, __LINE__, -2)

Definition at line 1493 of file cmocka.h.

Referenced by test_fails_out_of_order_if_no_calls_found_on_any(), test_ordering_does_ignore_calls(), test_ordering_does_ignore_no_calls(), test_ordering_fails_out_of_order_for_at_least_once_calls(), and test_ordering_ignores_out_of_order_properly().