A Fake Function Framework Plug-in for Ceedling

This is a plug-in for Ceedling to use the Fake Function Framework for mocking instead of CMock.

Using fff provides less strict mocking than CMock, and allows for more loosely-coupled tests. And, when tests fail -- since you get the actual line number of the failure -- it's a lot easier to figure out what went wrong.

Installing the plug-in

To use the plugin you need to 1) get the contents of this repo and 2) configure your project to use it.

Get the source

The easiest way to get the source is to just clone this repo into the Ceedling plugin folder for your existing Ceedling project. (Don't have a Ceedling project already? Here are instructions to create one.) From within <your-project>/vendor/ceedling/plugins, run:

git clone https://github.com/ElectronVector/fake_function_framework.git

This will create a new folder named fake_function_framework in the plugins folder.

Enable the plug-in.

The plug-in is enabled from within your project.yml file.

In the :plugins configuration, add fake_function_framework to the list of enabled plugins:

:plugins:
:load_paths:
- vendor/ceedling/plugins:enabled:
- stdout_pretty_tests_report
- module_generator
- fake_function_framework

Note that you could put the plugin source in some other loaction. In that case you'd need to add a new path the :load_paths.

How to use it

You use fff with Ceedling the same way you used to use CMock. Modules can still be generated with the default module generator: rake module:create[my_module]. If you want to "mock" some_module.h in your tests, just #include "mock_some_module.h". This creates a fake function for each of the functions defined in some_module.h.

The name of each fake is the original function name with an appended _fake. For example, if we're generating fakes for a stack module with push and pop functions, we would have the fakes push_fake and pop_fake. These fakes are linked into our test executable so that any time our unit under test calls push or pop our fakes are called instead.

Each of these fakes is actually a structure containing information about how the function was called, and what it might return. We can use Unity to inspect these fakes in our tests, and verify the interactions of our units. There is also a global structure named fff which we can use to check the sequence of calls.

The fakes can also be configured to return particular values, so you can exercise the unit under test however you want.

The examples below explain how to use fff to test a variety of module interactions. Each example uses fakes for a "display" module, created from a display.h file with #include "mock_display.h". The display.h file must exist and must contain the prototypes for the functions to be faked.

Test that a function was called once

voidtest_whenTheDeviceIsReset_thenTheStatusLedIsTurnedOff()
{
// Whenevent_deviceReset();
// ThenTEST_ASSERT_EQUAL(1, display_turnOffStatusLed_fake.call_count);
}

Test that a function was NOT called

voidtest_whenThePowerReadingIsLessThan5_thenTheStatusLedIsNotTurnedOn(void)
{
// Whenevent_powerReadingUpdate(4);
// ThenTEST_ASSERT_EQUAL(0, display_turnOnStatusLed_fake.call_count);
}

Test that a single function was called with the correct argument

voidtest_whenTheVolumeKnobIsMaxed_thenVolumeDisplayIsSetTo11(void)
{
// Whenevent_volumeKnobMaxed();
// ThenTEST_ASSERT_EQUAL(1, display_setVolume_fake.call_count);
TEST_ASSERT_EQUAL(11, display_setVolume_fake.arg0_val);
}

Test that calls are made in a particular sequence

voidtest_whenTheModeSelectButtonIsPressed_thenTheDisplayModeIsCycled(void)
{
// Whenevent_modeSelectButtonPressed();
event_modeSelectButtonPressed();
event_modeSelectButtonPressed();
// ThenTEST_ASSERT_EQUAL_PTR((void*)display_setModeToMinimum, fff.call_history[0]);
TEST_ASSERT_EQUAL_PTR((void*)display_setModeToMaximum, fff.call_history[1]);
TEST_ASSERT_EQUAL_PTR((void*)display_setModeToAverage, fff.call_history[2]);
}

Fake a return value from a function

voidtest_givenTheDisplayHasAnError_whenTheDeviceIsPoweredOn_thenTheDisplayIsPoweredDown(void)
{
// Givendisplay_isError_fake.return_val= true;
// Whenevent_devicePoweredOn();
// ThenTEST_ASSERT_EQUAL(1, display_powerDown_fake.call_count);
}

Fake a function with a value returned by reference

voidtest_givenTheUserHasTypedSleep_whenItIsTimeToCheckTheKeyboard_theDisplayIsPoweredDown(void)
{
// GivencharmockedEntry[] ="sleep";
voidreturn_mock_value(char*entry, intlength)
{
if (length>strlen(mockedEntry))
{
strncpy(entry, mockedEntry, length);
}
}
display_getKeyboardEntry_fake.custom_fake=return_mock_value;
// Whenevent_keyboardCheckTimerExpired();
// ThenTEST_ASSERT_EQUAL(1, display_powerDown_fake.call_count);
}

Fake a function with a function pointer parameter

void
test_givenNewDataIsAvailable_whenTheDisplayHasUpdated_thenTheEventIsComplete(void)
{
// A mock function for capturing the callback handler function pointer.
void(*registeredCallback)(void) = 0;
void mock_display_updateData(int data, void(*callback)(void))
{
//Save the callback function.
registeredCallback = callback;
}
display_updateData_fake.custom_fake = mock_display_updateData;
// Given
event_newDataAvailable(10);
// When
if (registeredCallback != 0)
{
registeredCallback();
}
// Then
TEST_ASSERT_EQUAL(true, eventProcessor_isLastEventComplete());
}

Helper macros

For convenience, there are also some helper macros that create new Unity-style asserts:

• TEST_ASSERT_CALLED(function): Asserts that a function was called once.
• TEST_ASSERT_NOT_CALLED(function): Asserts that a function was never called.
• TEST_ASSERT_CALLED_TIMES(times, function): Asserts that a function was called a particular number of times.
• TEST_ASSERT_CALLED_IN_ORDER(order, function): Asserts that a function was called in a particular order.

Here's how you might use one of these instead of simply checking the call_count value:

voidtest_whenTheDeviceIsReset_thenTheStatusLedIsTurnedOff()
{
// Whenevent_deviceReset();
// Then// This how to directly use fff...TEST_ASSERT_EQUAL(1, display_turnOffStatusLed_fake.call_count);
// ...and this is how to use the helper macro.TEST_ASSERT_CALLED(display_turnOffStatusLed);
}

Test setup

All of the fake functions, and any fff global state are all reset automatically between each test.

CMock configuration

Use still use some of the CMock configuration options for setting things like the mock prefix, and for including additional header files in the mock files.

:cmock:
:mock_prefix: mock_:includes:
-
:includes_h_pre_orig_header:
-
:includes_h_post_orig_header:
-
:includes_c_pre_header:
-
:includes_c_post_header:

Running the tests

There are unit and integration tests for the plug-in itself. These are run with the default rake task. The integration test runs the tests for the example project in examples/fff_example. For the integration tests to succeed, this repository must be placed in a Ceedling tree in the plugins folder.

More examples

There is an example project in examples/fff_example. It shows how to use the plug-in with some full-size examples.