pico_unit.h File Reference

A bare-bones unit testing framework written in C99. More...

#include <stdbool.h>
#include <stddef.h>
#include <string.h>

Include dependency graph for pico_unit.h:

Go to the source code of this file.

Macros
#define	TEST_CASE(name)   static bool name(void)
	Defines a unit test. More...
#define	REQUIRE(expr)
	Asserts that a condition is true. More...
#define	RUN_TEST_CASE(test_fp)   (pu_run_test(#test_fp, test_fp))
	Runs a unit test function. More...
#define	TEST_SUITE(name)   void name(void)
	Declares a test suite. More...
#define	RUN_TEST_SUITE(suite_fp)   pu_run_suite(#suite_fp, suite_fp)
	Runs a series of unit tests. The test suite function has the signature, void suite_func(void). More...

Typedefs
typedef void(*	pu_setup_fn) (void)
	Functions that are run before or after a number of unit tests execute. More...
typedef bool(*	pu_test_fn) (void)
typedef void(*	pu_suite_fn) (void)

Functions
void	pu_setup (pu_setup_fn setup_fp, pu_setup_fn teardown_fp)
	Sets the current setup and teardown functions. More...
void	pu_clear_setup (void)
	Disables the setup and teardown functions by setting them to NULL. More...
void	pu_display_colors (bool enabled)
	Turns on terminal colors. NOTE: Off by default. More...
void	pu_display_time (bool enabled)
	Turns on time measurement. NOTE: Off by default. More...
void	pu_print_stats (void)
	Prints test statistics. More...
bool	pu_test_failed (void)
	Check whether at least one test failed. More...
bool	pu_require (bool passed, const char *const expr, const char *const file, int line)
	Used internally. More...
void	pu_run_test (const char *const name, pu_test_fn test_fp)
	Used internally. More...
void	pu_run_suite (const char *const name, pu_suite_fn suite_fp)
	Used internally. More...

Detailed Description

A bare-bones unit testing framework written in C99.

---

Licensing information at end of header

Features:

Written in C99 and compatible with C++ Single-header for easy integration into any build system Tiny memory and code footprint Simple and minimalistic API All unit tests are run during execution and failures are indicated On demand setup and teardown function support Ability to group tests into test suites Ability to print test statistics Optional color coded output Optional time measurement Permissive licensing (zlib or public domain)

Summary:

This library is a minimal unit testing framework. It should compile and run on just about any platform with a standard C99 compiler.

Writing tests is simple: 1) Use the TEST_CASE macro and define the test using using REQUIRE to test boolean expressions; 2) Run the test inside the body of a test suite or other function (e.g. main) using RUN_TEST_CASE. How you group tests and test suites is entirely up to you.

In order to keep the library portable and nimble, certain features were dispensed with, namely automatic test registration and predicates more complex than REQUIRE. Experience has shown these are not serious defects.

There are a number of display options available: color coded output, test elapsed time (unless PICO_UNIT_NO_CLOCK is defined), and printing test statistics.

A test suite is simply a group of tests. These contain calls to RUN_TEST_CASE. The advantage of using test suites is that it divides unit tests into logical groups. There are helper macros for declaring and defining test suites. Test suites help with formatting the output and the number of suites shows up in the test statistics. There is also the option to flexibly define setup and teardown functions for groups of tests.

Please see the examples for more details.

Usage:

To use this library in your project, add the following

#define PICO_UNIT_IMPLEMENTATION #include "pico_unit.h"

to a source file (once), then simply include the header normally.

Macro Definition Documentation

TEST_CASE

#define TEST_CASE

(

name

)

static bool name(void)

Defines a unit test.

Parameters

name	The name of the test. Must be a valid C function name

REQUIRE

#define REQUIRE

(

expr

)

Value:

    do  { \
        if (!pu_require((expr) ? true : false, (#expr), __FILE__, __LINE__)) \
            return false; \
    } while(false)

Asserts that a condition is true.

Asserts that the given expression evaluates to true. If the expression evalutes to false, execution of the current test aborts and an error message is displayed.

Parameters

expr	The expression to evaluate

RUN_TEST_CASE

#define RUN_TEST_CASE

(

test_fp

)

(pu_run_test(#test_fp, test_fp))

Runs a unit test function.

IMPORTANT: The function test_fp must return true. The test function has the signature, bool test_func(void).

Parameters

test_fp

The test function to execute

TEST_SUITE

#define TEST_SUITE

(

name

)

void name(void)

Declares a test suite.

Parameters

name	The name of the test suite

RUN_TEST_SUITE

#define RUN_TEST_SUITE

(

suite_fp

)

pu_run_suite(#suite_fp, suite_fp)

Runs a series of unit tests. The test suite function has the signature, void suite_func(void).

Parameters

suite_fp

The test suite function to run

Typedef Documentation

pu_setup_fn

typedef void(* pu_setup_fn) (void)

Functions that are run before or after a number of unit tests execute.

pu_test_fn

typedef bool(* pu_test_fn) (void)

pu_suite_fn

typedef void(* pu_suite_fn) (void)

Function Documentation

pu_setup()

void pu_setup	(	pu_setup_fn	setup_fp,
		pu_setup_fn	teardown_fp
	)

Sets the current setup and teardown functions.

Sets the current setup and teardown functions. The setup function is called prior to each unit test and the teardown function after. Either of these functions can be NULL. The setup and teardown functions have the signature, void func(void).

Parameters

setup_fp	The setup function
teardown_fp	The teardown function

pu_clear_setup()

void pu_clear_setup

(

void

)

Disables the setup and teardown functions by setting them to NULL.

pu_display_colors()

void pu_display_colors

(

bool

enabled

)

Turns on terminal colors. NOTE: Off by default.

pu_display_time()

void pu_display_time

(

bool

enabled

)

Turns on time measurement. NOTE: Off by default.

pu_print_stats()

void pu_print_stats

(

void

)

Prints test statistics.

pu_test_failed()

bool pu_test_failed

(

void

)

Check whether at least one test failed.

Returns

true if any test failed, false if they all passed

pu_require()

bool pu_require	(	bool	passed,
		const char *const	expr,
		const char *const	file,
		int	line
	)

Used internally.

pu_run_test()

void pu_run_test	(	const char *const	name,
		pu_test_fn	test_fp
	)

Used internally.

pu_run_suite()

void pu_run_suite	(	const char *const	name,
		pu_suite_fn	suite_fp
	)

Used internally.