How long can we maintain? I wonder. How long before one of us starts raving and jabbering at this boy? What will he think then? This same lonely desert was the last known home of the Manson family. Will he make that grim connection...
fff is a micro-framework for creating fake C functions for tests. Because life is too short to spend time hand-writing fake functions for testing.
Say you are testing an embedded user interface and you have a function that you want to create a fake for:
// UI.c
...
void DISPLAY_init();
...
Here's how you would define a fake function for this in your test suite:
// test.c(pp)
#include "fff.h"
DEFINE_FFF_GLOBALS;
FAKE_VOID_FUNC(DISPLAY_init);
And the unit test might look something like this:
TEST_F(GreeterTests, init_initialises_display)
{
UI_init();
ASSERT_EQ(DISPLAY_init_fake.call_count, 1);
}
So what has happened here? The first thing to note is that the framework is header only, all you need to do to use it is download fff.h and include it in your test suite.
The magic is in the FAKE_VOID_FUNC. This expands a macro that defines a function returning void which has zero arguments. It also defines a struct "function_name"_fake which contains all the information about the fake. For instance, DISPLAY_init_fake.call_countis incremented every time the faked function is called.
Under the hood it generates a struct that looks like this:
typedef struct DISPLAY_init_Fake {
unsigned int call_count;
unsigned int arg_history_len;
unsigned int arg_histories_dropped;
void(*custom_fake)();
} DISPLAY_init_Fake;
DISPLAY_init_Fake DISPLAY_init_fake;
Ok, enough with the toy examples. What about faking functions with arguments?
// UI.c
...
void DISPLAY_output(char * message);
...
Here's how you would define a fake function for this in your test suite:
FAKE_VOID_FUNC(DISPLAY_output, char *);
And the unit test might look something like this:
TEST_F(UITests, write_line_outputs_lines_to_display)
{
char msg[] = "helloworld";
UI_write_line(msg);
ASSERT_EQ(DISPLAY_output_fake.call_count, 1);
ASSERT_EQ(strncmp(DISPLAY_output_fake.arg0_val, msg, 26), 0);
}
There is no more magic here, the FAKE_VOID_FUNC works as in the previous example. The number of arguments that the function takes is calculated, and the macro arguments following the function name defines the argument type (a char pointer in this example).
A variable is created for every argument in the form "function_name"fake.argN_val
When you want to define a fake function that returns a value, you should use the FAKE_VALUE_FUNC macro. For instance:
// UI.c
...
unsigned int DISPLAY_get_line_capacity();
unsigned int DISPLAY_get_line_insert_index();
...
Here's how you would define fake functions for these in your test suite:
FAKE_VALUE_FUNC(unsigned int, DISPLAY_get_line_capacity);
FAKE_VALUE_FUNC(unsigned int, DISPLAY_get_line_insert_index);
And the unit test might look something like this:
TEST_F(UITests, when_empty_lines_write_line_doesnt_clear_screen)
{
// given
DISPLAY_get_line_insert_index_fake.return_val = 1;
char msg[] = "helloworld";
// when
UI_write_line(msg);
// then
ASSERT_EQ(DISPLAY_clear_fake.call_count, 0);
}
Of course you can mix and match these macros to define a value function with arguments, for instance to fake:
double pow(double base, double exponent);
you would use a syntax like this:
FAKE_VALUE_FUNC(double, pow, double, double);
Good tests are isolated tests, so it is important to reset the fakes for each unit test. All the fakes have a reset function to reset their arguments and call counts. It is good prectice is to call the reset function for all the fakes in the setup function of your test suite.
void setup()
{
// Register resets
RESET_FAKE(DISPLAY_init);
RESET_FAKE(DISPLAY_clear);
RESET_FAKE(DISPLAY_output_message);
RESET_FAKE(DISPLAY_get_line_capacity);
RESET_FAKE(DISPLAY_get_line_insert_index);
}
Say you want to test that a function calls functionA, then functionB, then functionA again, how would you do that? Well fff maintains a call history so that it is easy to assert these expectations.
Here's how it works:
FAKE_VOID_FUNC(voidfunc2, char, char);
FAKE_VALUE_FUNC(long, longfunc0);
TEST_F(FFFTestSuite, calls_in_correct_order)
{
longfunc0();
voidfunc2();
longfunc0();
ASSERT_EQ(fff.call_history[0], (void *)longfunc0);
ASSERT_EQ(fff.call_history[1], (void *)voidfunc2);
ASSERT_EQ(fff.call_history[2], (void *)longfunc0);
}
They are reset by calling FFF_RESET_HISTORY();
The framework will by default store the arguments for the last ten calls made to a fake function.
TEST_F(FFFTestSuite, when_fake_func_called_then_arguments_captured_in_history)
{
voidfunc2('g', 'h');
voidfunc2('i', 'j');
ASSERT_EQ('g', voidfunc2_fake.arg0_history[0]);
ASSERT_EQ('h', voidfunc2_fake.arg1_history[0]);
ASSERT_EQ('i', voidfunc2_fake.arg0_history[1]);
ASSERT_EQ('j', voidfunc2_fake.arg1_history[1]);
}
There are two ways to find out if calls have been dropped. The first is to check the dropped histories counter:
TEST_F(FFFTestSuite, when_fake_func_called_max_times_plus_one_then_one_argument_history_dropped)
{
int i;
for(i = 0; i < 10; i++)
{
voidfunc2('1'+i, '2'+i);
}
voidfunc2('1', '2');
ASSERT_EQ(1u, voidfunc2_fake.arg_histories_dropped);
}
The other is to check if the call count is greater than the history size:
ASSERT(voidfunc2_fake.arg_history_len < voidfunc2_fake.call_count);
The argument histories for a fake function are reset when the RESET_FAKE function is called
If you wish to control how many calls to capture for argument history you can override the default by defining it before include the fff.h like this:
// Want to keep the argument history for 13 calls
#define FFF_ARG_HISTORY_LEN 13
// Want to keep the call sequence history for 17 function calls
#define FFF_CALL_HISTORY_LEN 17
#include "../fff.h"
Often in testing we would like to test the behaviour of sequence of function call events. One way to do this with fff is to specify a sequence of return values with for the fake function. It is probably easier to describe with an example:
// faking "long longfunc();"
FAKE_VALUE_FUNC(long, longfunc0);
TEST_F(FFFTestSuite, return_value_sequences_exhausted)
{
long myReturnVals[3] = { 3, 7, 9 };
SET_RETURN_SEQ(longfunc0, myReturnVals, 3);
ASSERT_EQ(myReturnVals[0], longfunc0());
ASSERT_EQ(myReturnVals[1], longfunc0());
ASSERT_EQ(myReturnVals[2], longfunc0());
ASSERT_EQ(myReturnVals[2], longfunc0());
ASSERT_EQ(myReturnVals[2], longfunc0());
}
By specifying a return value sequence using the SET_RETURN_SEQ macro, the fake will return the values given in the parameter array in sequence. When the end of the sequence is reached the fake will continue to return the last value in the sequence indefinitely.
Look under the examlples directory for full length examples in both C and C++. There is also a test suite for the framework under the test directory.
So whats the point?
- To make it easy to create fake functions for testing C code.
- To be simple
- To work in both C and C++ test environments
- It maintains a call count for each fake function
- It captures the arguments sent in each function call
- It captures a call history
- It is simple - just include a header file and you are good to go.
- The fff.h header file is generated by a ruby script
- There are tests under src/test
- There are examples for testing an embedded UI under src/examples
| Macro | Description | Example |
|---|---|---|
| FAKE_VOID_FUNC(fn [,arg_types*]); | Define a fake function named fn returning void with n arguments | FAKE_VOID_FUNC(DISPLAY_output_message, const char*); |
| FAKE_VALUE_FUNC(return_type, fn [,arg_types*]); | Define a fake function returning a value with type return_type taking n arguments | FAKE_VALUE_FUNC(int, DISPLAY_get_line_insert_index); |
| RESET_FAKE(fn); | Reset the state of fake function called fn | RESET_FAKE(DISPLAY_init); |