This module is the test suite framework, which provides a set of standard functions and macros for defining and running test suites.

A test suite consists of test cases. Each test case consists of a set of functions that are called in a specific order by the framework when the test suite is run. The runtime environment of a test is referred to as the test fixture. A setup function can be defined for the purpose of fulfilling preconditions that are needed for the test to run. To free up or reset resources which were used in the test case, a cleanup function can be defined.

The following three functions can be defined for each test case:

fixture setup
test run
fixture cleanup

The setup and/or cleanup functions may be skipped if they are not needed.

A function may report an error or failure by use of the macros test_fail , test_assert_true and test_assert_false. Note that only the first macro allows for the result value to be specified, while the two latter will automatically return TEST_FAIL if the specified condition is false.

If any of the functions return a failure/error result, execution of that specific function is ended. However, depending on which function did not pass, execution of the test case may continue:

if the setup does not pass, the rest of the test case is skipped
if the test itself does not pass, cleanup will still be executed

The result of the first function in the test case which does not pass determines the end result.

Example code for definition of a test suite:

void setup_1(const struct test_case *test);
void run_1(const struct test_case *test);
void cleanup_1(const struct test_case *test);
void run_2(const struct test_case *test);
...
DEFINE_TEST_CASE(test_1,
       setup_1,
       run_1,
       cleanup_1,
       "First test");
DEFINE_TEST_CASE(test_2,
       NULL,
       run_2,
       NULL,
       "Second test");
DEFINE_TEST_ARRAY(my_tests) = {
   &test_1,
   &test_2,
};
DEFINE_TEST_SUITE(my_suite, my_tests, "Two-test suite");
test_suite_run(&my_suite);
...

Example code for definition of a test case:

void setup_1(const struct test_case *test)
{
   void *resource = allocate_test_resource();
   if (resource == NULL) {
       test_fail(test, TEST_ERROR,
           "Could not allocate test resource");
   }
   test_set_data(resource);
}
void run_1(const struct test_case *test)
{
   void *resource = test_get_data();
   int8_t test_result;
     ...
   // TEST CODE
     ...
   test_assert_true(test, test_result > 0,
           "Test result is not larger than 0: %i", test_result);
   test_assert_false(test, test_result > 2,
           "Test result is larger than 2: %i", test_result);
}
void cleanup_1(const struct test_case *test)
{
   void *resource = test_get_data();
   free_test_resource(resource);
}

Data Structures
struct	test_case
	A test case. More...

struct	test_suite
	A test suite. More...

Functions
static int	test_call (void(func)(const struct test_case ), const struct test_case *test)
	Call a test or fixture function. More...

void	test_case_fail (const struct test_case test, int result, const char file, unsigned int line, const char *fmt,...)
	Report a failure and jump out of current test case function. More...

static int	test_case_run (const struct test_case *test)
	Run a test case. More...

static void	test_report_failure (const struct test_case test, const char stage, int result)
	Report a failing test stage. More...

Variables
struct test_case *	test_case_ptr = NULL
	Pointer to current test case. More...

static jmp_buf	test_failure_jmpbuf
	Context saved before executing a test or fixture function. More...

void *	test_priv_data
	Data pointer for test cases. More...

Wrappers for printing debug information
Note The test suite framework feeds its output to printf. It is left up to the test application to set up the stream.
#define	dbg(__fmt_) printf_P(PROGMEM_STRING(__fmt_))

#define	dbg_info(__fmt_,...) printf_P(PROGMEM_STRING(__fmt_), __VA_ARGS__)

#define	dbg_error(_x,...) printf_P(PROGMEM_STRING(_x), __VA_ARGS__)

#define	dbg_putchar(c) putc(c, stdout)

#define	dbg_vprintf_pgm(...) vfprintf_P(stdout, __VA_ARGS__)

Test suite definition macros
#define	DEFINE_TEST_CASE(_sym, _setup, _run, _cleanup, _name)
	Create a test case struct. More...

#define	DEFINE_TEST_ARRAY(_sym) const struct test_case *const _sym[]
	Create an array of test case pointers. More...

#define	DEFINE_TEST_SUITE(_sym, _test_array, _name)
	Create a test suite. More...

Test data access
void *	test_priv_data
	Data pointer for test cases. More...

static void	test_set_data (void *data)
	Set private data pointer for the current test. More...

static void *	test_get_data (void)
	Get the private data pointer for the current test. More...

Test case pointer access
struct test_case *	test_case_ptr
	Pointer to current test case. More...

static void	test_set_case (const struct test_case *test)
	Set pointer to current test. More...

static struct test_case *	test_get_case (void)
	Get pointer to current test. More...

Test result reporting
enum	test_status { TEST_ERROR = -1, TEST_PASS = 0, TEST_FAIL = 1 }
	Status codes returned by test cases and fixtures. More...

#define	test_fail(test, result,...) test_case_fail(test, result, __FILE__, __LINE__, __VA_ARGS__)
	Fail the test. More...

#define	test_assert_true(test, condition,...)
	Verify that condition is true. More...

#define	test_assert_false(test, condition,...) test_assert_true(test, !(condition), __VA_ARGS__)
	Verify that condition is false. More...

Test suite interaction
int	test_suite_run (const struct test_suite *suite)
	Run a test suite. More...

#define dbg ( __fmt_ ) printf_P(PROGMEM_STRING(__fmt_))

Referenced by test_case_run().

#define dbg_error	(	_x,
		...
	)	printf_P(PROGMEM_STRING(_x), __VA_ARGS__)

Referenced by test_case_fail(), and test_report_failure().

#define dbg_info	(	__fmt_,
		...
	)	printf_P(PROGMEM_STRING(__fmt_), __VA_ARGS__)

Referenced by test_case_run(), and test_suite_run().

#define dbg_putchar ( c ) putc(c, stdout)

Referenced by test_case_fail().

#define dbg_vprintf_pgm ( ... ) vfprintf_P(stdout, __VA_ARGS__)

Referenced by test_case_fail().

#define DEFINE_TEST_ARRAY ( _sym ) const struct test_case *const _sym[]

Create an array of test case pointers.

Parameters

_sym	Variable name of the resulting array

Referenced by main().

#define DEFINE_TEST_CASE	(	_sym,
		_setup,
		_run,
		_cleanup,
		_name
	)

Value:

static const char _test_str_##_sym[] = _name;                          \
    static const struct test_case _sym = {                                 \
        .setup   = _setup,                                             \
        .run     = _run,                                               \
        .cleanup = _cleanup,                                           \
        .name    = _test_str_##_sym,                                   \
    }

Create a test case struct.

Parameters

_sym	Variable name of the resulting struct
_setup	Function which sets up a test case environment. Can be NULL.
_run	Test function
_cleanup	Function which cleans up what was set up. Can be NULL.
_name	String describing the test case.

Referenced by main().

#define DEFINE_TEST_SUITE	(	_sym,
		_test_array,
		_name
	)

Value:

static const char _test_str_##_sym[] = _name;                          \
    const struct test_suite _sym = {                                       \
        .nr_tests = ARRAY_LEN(_test_array),                            \
        .tests    = _test_array,                                       \
        .name     = _test_str_##_sym,                                  \
    }

Create a test suite.

Parameters

_sym	Variable name of the resulting struct
_test_array	Array of test cases, created with DEFINE_TEST_ARRAY()
_name	String describing the test suite.

Referenced by main().

#define test_assert_false	(	test,
		condition,
		...
	)	test_assert_true(test, !(condition), __VA_ARGS__)

Verify that condition is false.

If condition is true, fail the test with an error message indicating the condition which failed.

Parameters

test	The test case currently being run
condition	Expression to be validated
...	Format string and arguments

#define test_assert_true	(	test,
		condition,
		...
	)

Value:

do {                                                                   \
        if (!(condition)) {                                            \
			test_fail(test, TEST_FAIL, __VA_ARGS__);               \
        }                                                              \
    } while (0)

Verify that condition is true.

If condition is false, fail the test with an error message indicating the condition which failed.

Parameters

test	The test case currently being run
condition	Expression to be validated
...	Format string and arguments

Referenced by run_eic_test().

#define test_fail	(	test,
		result,
		...
	)	test_case_fail(test, result, __FILE__, __LINE__, __VA_ARGS__)

Fail the test.

Calling this function will cause the test to terminate with a failure. It will return directly to the test suite core, not to the caller.

Parameters

test	Test case which failed
result	The result of the test (may not be 0)
...	printf()-style format string and arguments

enum test_status

Status codes returned by test cases and fixtures.

Note that test cases and especially fixtures may return any of the status codes defined by status_code as well.

Enumerator
TEST_ERROR	Test error.
TEST_PASS	Test success.
TEST_FAIL	Test failure.

static int test_call	(	void()(const struct test_case )	func,
		const struct test_case *	test
	)

static

Call a test or fixture function.

This function will initialize test_failure_jmpbuf and call func with test as the parameter.

Parameters

func	Pointer to function to call.
test_case	Pointer to the function's originating test case.

Returns: TEST_PASS if func was executed successfully, or the result value passed to test_fail() on failure.

References test_failure_jmpbuf, and TEST_PASS.

Referenced by test_case_run().

void test_case_fail	(	const struct test_case *	test,
		int	result,
		const char *	file,
		unsigned int	line,
		const char *	fmt,
			...
	)

Report a failure and jump out of current test case function.

Parameters

test	Current test case.
result	Result value of failure.

Note: Should not be TEST_PASS.

Parameters

file	Name of file in which function resides.
line	Line number at which failure occurred.
fmt	Failure message, as printf-formatted string.
...	Values to insert into failure message.

References dbg_error, dbg_putchar, dbg_vprintf_pgm, test_case::name, and test_failure_jmpbuf.

static int test_case_run ( const struct test_case * test )

static

Run a test case.

This function will call the setup, run and cleanup functions of the specified test case, outputting debug information as it goes, then returning the result value of the test case.

If the setup stage does not pass, the rest of the test case if skipped. If the test stage itself does not pass, the cleanup is still executed.

The result from the first non-passing function in the test case is returned, meaning a failing cleanup will override a successful test.

Parameters

test_case Test case to run.