Topics
	Test Cases
	Assertions
	Test Fixtures
	Test Suites

Data Structures
struct	PicoTestMetadata
	Test metadata. More...

Test Filters
PicoTest provides a way for client code to select tests to be run using custom filter functions.
enum	PicoTestFilterResult { PICOTEST_FILTER_SKIP , PICOTEST_FILTER_PASS , PICOTEST_FILTER_SKIP_PROPAGATE , PICOTEST_FILTER_PASS_PROPAGATE }
	Result of test filter functions. More...
typedef PicoTestFilterResult	PicoTestFilterProc(PicoTestProc test, const char testName, const char *cond)
	Signature of test filter functions.
#define	PICOTEST_FILTER_DEFAULT
	Default test filter function.
#define	PICOTEST_FILTER
	Define the test filter function.

Test hierarchy traversal
Tests can form hierarchies of test suites and test cases. PicoTest provides two ways to traverse such hierarchies with a simple visitor pattern. This can be used for e.g. test list discovery in build systems.
enum	PicoTestVisitStep { PICOTEST_VISIT_ENTER , PICOTEST_VISIT_LEAVE }
	Test visit step. More...
typedef void	PicoTestTraverseProc(const char *name, int nb)
	Function signature of test traversal proc.
typedef void	PicoTestVisitProc(const PicoTestMetadata *metadata, PicoTestVisitStep step)
	Function signature of test visit proc.
#define	PICOTEST_TRAVERSE(_testName, _proc)
	Traverse a test hierarchy depth-first.
#define	PICOTEST_VISIT(_testName, _proc)
	Visit a test hierarchy depth-first.

Test Functions
typedef int	PicoTestProc(const char *cond)
	Signature of test functions.
#define	PICOTEST_EXTERN(_testName)
	Declare an extern test for metadata access.
#define	PICOTEST_METADATA(_testName)
	Get test metadata.

Logging
PicoTest provides a way for client code to intercept test failure events. This can be used for e.g. logging purpose or reporting.
typedef void	PicoTestFailureLoggerProc(const char file, int line, const char type, const char test, const char msg, va_list args)
	Function signature of test failure log handlers.
#define	PICOTEST_FAILURE_LOGGER_DEFAULT
	Default test failure log handler.
#define	PICOTEST_FAILURE_LOGGER
	Define the test failure log handler.

Namespaces
#define	PICOTEST_NAMESPACE
	Activate namespacing for the current file (disabled by default).
#define	PICOTEST_NAMESPACE_DELIMITER
	String delimiter between namespace and test names (defaults to ".").
#define	PICOTEST_EXPORT(_testName)
	Export a test to make it globally accessible.

Detailed Description

Data Structure Documentation

◆ PicoTestMetadata

struct PicoTestMetadata

Test metadata.

Data Fields
const char *	name	Test name.
const char *	file	Test file location.
int	line	Test line location.
PicoTestProc *const	test	Test function.
int	nbSubtests	Number of subtests.
const struct PicoTestMetadata **	subtests	Subtests (NULL-terminated array for test suites, NULL pointer for test cases).

Macro Definition Documentation

◆ PICOTEST_NAMESPACE

#define PICOTEST_NAMESPACE

Activate namespacing for the current file (disabled by default).

Defining PICOTEST_NAMESPACE before including picotest.h will use the provided value as a prefix for all the symbols in the file to avoid name clashes. This is useful with large test suites to keep local test names short.

◆ PICOTEST_NAMESPACE_DELIMITER

#define PICOTEST_NAMESPACE_DELIMITER

String delimiter between namespace and test names (defaults to ".").

◆ PICOTEST_EXPORT

#define PICOTEST_EXPORT ( _testName )

Export a test to make it globally accessible.

This creates a global wrapper around the namespaced test, allowing it to be referenced externally.

Parameters

_testName Test name.

◆ PICOTEST_EXTERN

#define PICOTEST_EXTERN ( _testName )

Declare an extern test for metadata access.

Parameters

_testName Test name.

See also: PICOTEST_METADATA

◆ PICOTEST_METADATA

#define PICOTEST_METADATA ( _testName )

Get test metadata.

Note: Tests in other modules need to be declared first with PICOTEST_EXTERN.

Parameters

_testName Test name.

See also: PicoTestMetadata; PICOTEST_EXTERN

◆ PICOTEST_FILTER_DEFAULT

#define PICOTEST_FILTER_DEFAULT

Default test filter function.

Does a simple string equality test between testName and cond, and propagates to subtests if it doesn't match.

See also: PicoTestFilterProc; PICOTEST_FILTER

◆ PICOTEST_FILTER

#define PICOTEST_FILTER

Define the test filter function.

Called before calling a test with a non- NULL condition.

The default filter does a simple string equality test between its testName and cond arguments, and propagates to subtests if it doesn't match. Redefine this macro to use a custom filter function, which must follow the PicoTestFilterProc signature.

Note: Custom functions only apply to the tests defined after the macro redefinition. As macros can be redefined several times, this means that different functions may apply for the same source.

Usage: /* Custom test filter declaration. */

PicoTestFilterProc matchSubstring;

#undef PICOTEST_FILTER

#define PICOTEST_FILTER matchSubstring

/* Test filter function. */

PicoTestFilterResult matchSubstring(PicoTestProc *test, const char *testName, const char *cond) {

/* Match tests containing **cond** substring. */

return (strstr(testName, cond) == NULL

? PICOTEST_FILTER_SKIP_PROPAGATE

: PICOTEST_FILTER_PASS_PROPAGATE);

}

Examples: filter.c Example of PicoTest test filter, allows custom filtering of test functions.
tags.c Advanced example of PicoTest test filter, implements a primitive tagging feature for test filtering.

See also: PicoTestFilterProc; PICOTEST_FILTER_DEFAULT

◆ PICOTEST_TRAVERSE

#define PICOTEST_TRAVERSE	(		_testName,
			_proc )

Traverse a test hierarchy depth-first.

This feature covers simple use cases such as getting the flat list of all test names. For more advanced usage, see PICOTEST_VISIT.

Parameters

_testName	Name of the traversed test.
_proc	Test traversal proc. Must follow the PicoTestTraverseProc signature.

Examples: traverse.c Example of PicoTest hierarchy traversal, prints traversed tests to stdout.

See also: PicoTestTraverseProc; PICOTEST_VISIT

◆ PICOTEST_VISIT

#define PICOTEST_VISIT	(		_testName,
			_proc )

Visit a test hierarchy depth-first.

This feature covers more advanced use cases than PICOTEST_TRAVERSE, such as exporting the test hierarchy as a structured format such as XML or JSON, or accessing test metadata.

Parameters

_testName	Name of the visited test.
_proc	Test visit proc. Must follow the PicoTestVisitProc signature.

See also: PicoTestVisitProc; PICOTEST_TRAVERSE

◆ PICOTEST_FAILURE_LOGGER_DEFAULT

#define PICOTEST_FAILURE_LOGGER_DEFAULT

Default test failure log handler.

Does nothing.

See also: PicoTestFailureLoggerProc; PICOTEST_FAILURE_LOGGER

◆ PICOTEST_FAILURE_LOGGER

#define PICOTEST_FAILURE_LOGGER

Define the test failure log handler.

Called when a test fails.

The default handler does nothing. Redefine this macro to use a custom handler, which must follow the PicoTestFailureLoggerProc signature.

Note: Custom functions only apply to the tests defined after the macro redefinition. As macros can be redefined several times, this means that different functions may apply for the same source.

Usage: /* Test failure logger declaration. */

PicoTestFailureLoggerProc logFailure;

#undef PICOTEST_FAILURE_LOGGER

#define PICOTEST_FAILURE_LOGGER logFailure

/* Test failure logger function. */

void logFailure(const char *file, int line, const char *type, const char *test, const char *msg, va_list args) {

/* Error type. */

printf("[%s] ", type);

/* Location in source code. */

printf("%s(%d) : ", file, line);

/* Failed expression. */

printf("%s", test);

/* Optional message. */

if (msg) {

printf(" | ");

vprintf(msg, args);

}

printf("\n");

}

Examples: logger.c Example of PicoTest error logging, prints location and info of failed assertions to stdout.

See also: PicoTestFailureLoggerProc; PICOTEST_FAILURE_LOGGER_DEFAULT

Typedef Documentation

◆ PicoTestProc

typedef int PicoTestProc(const char *cond)

Signature of test functions.

Both Test Suites and Test Cases follow this signature.

Parameters

cond	Test filtering condition, or NULL. In the former case, passed to the active test filter before running the test.

Returns: Number of failed tests.

See also: PICOTEST_SUITE; PICOTEST_CASE; PICOTEST_FILTER

◆ PicoTestFilterProc

typedef PicoTestFilterResult PicoTestFilterProc(PicoTestProc *test, const char *testName, const char *cond)

Signature of test filter functions.

A test called with a non- NULL condition must match this condition to be run. The test filter is set using the PICOTEST_FILTER macro.

Parameters

test	Test function to filter.
testName	Name of test to filter.
cond	Test filtering condition.

Returns: a PicoTestFilterResult value

Usage: /* Custom test filter declaration. */

PicoTestFilterProc matchSubstring;

#undef PICOTEST_FILTER

#define PICOTEST_FILTER matchSubstring

/* Test filter function. */

PicoTestFilterResult matchSubstring(PicoTestProc *test, const char *testName, const char *cond) {

/* Match tests containing **cond** substring. */

return (strstr(testName, cond) == NULL

? PICOTEST_FILTER_SKIP_PROPAGATE

: PICOTEST_FILTER_PASS_PROPAGATE);

}

Examples: filter.c Example of PicoTest test filter, allows custom filtering of test functions.
tags.c Advanced example of PicoTest test filter, implements a primitive tagging feature for test filtering.

See also: PICOTEST_SUITE; PICOTEST_CASE; PICOTEST_FILTER; PicoTestFilterResult

◆ PicoTestTraverseProc

typedef void PicoTestTraverseProc(const char *name, int nb)

Function signature of test traversal proc.

Parameters

name	Name of traversed test.
nb	Number of subtests (zero for simple test cases, at least one for test suites).

Usage: /* Test traversal function declaration. */

PicoTestTraverseProc printTestCase;

PicoTestTraverseProc printTestName;

/* Traversal function, will print test cases only. */

void printTestCase(const char *name, int nb) {

if (nb == 0) printf("%s\n", name);

}

/* Traversal function, will print all tests. */

void printTestName(const char *name, int nb) {

printf("%s\n", name);

}

Examples: traverse.c Example of PicoTest hierarchy traversal, prints traversed tests to stdout.

See also: PICOTEST_TRAVERSE

◆ PicoTestVisitProc

typedef void PicoTestVisitProc(const PicoTestMetadata *metadata, PicoTestVisitStep step)

Function signature of test visit proc.

Proc is called once for each value of PicoTestVisitStep.

Parameters

metadata	Metadata of the visited test.
step	Visit step.

See also: PICOTEST_VISIT; PicoTestVisitStep

◆ PicoTestFailureLoggerProc

typedef void PicoTestFailureLoggerProc(const char *file, int line, const char *type, const char *test, const char *msg, va_list args)

Function signature of test failure log handlers.

Parameters

file	File name where the test was defined.
line	Location of test in file.
type	Type of test that failed (e.g. "ASSERT").
test	Tested expression.
msg	Optional message format string, or NULL.
args	Optional message string parameter list, or NULL.

Note: msg and args are suitable arguments to vprintf().

Usage: /* Test failure logger declaration. */

PicoTestFailureLoggerProc logFailure;

#undef PICOTEST_FAILURE_LOGGER

#define PICOTEST_FAILURE_LOGGER logFailure

/* Test failure logger function. */

void logFailure(const char *file, int line, const char *type, const char *test, const char *msg, va_list args) {

/* Error type. */

printf("[%s] ", type);

/* Location in source code. */

printf("%s(%d) : ", file, line);

/* Failed expression. */

printf("%s", test);

/* Optional message. */

if (msg) {

printf(" | ");

vprintf(msg, args);

}

printf("\n");

}

Examples: logger.c Example of PicoTest error logging, prints location and info of failed assertions to stdout.

See also: PICOTEST_FAILURE_LOGGER

Enumeration Type Documentation

◆ PicoTestFilterResult

enum PicoTestFilterResult

Result of test filter functions.

Examples: filter.c Example of PicoTest test filter, allows custom filtering of test functions.
tags.c Advanced example of PicoTest test filter, implements a primitive tagging feature for test filtering.

See also: PicoTestFilterProc

Enumerator
PICOTEST_FILTER_SKIP	Test does not match the condition, skip this test and all its subtests.
PICOTEST_FILTER_PASS	Test matches the condition, run this test and all its subtests.
PICOTEST_FILTER_SKIP_PROPAGATE	Test does not match the condition, skip this test but filter its subtests.
PICOTEST_FILTER_PASS_PROPAGATE	Test matches the condition, run this test but filter its subtests.

◆ PicoTestVisitStep

enum PicoTestVisitStep

Test visit step.

See also: PicoTestVisitProc; PICOTEST_VISIT

Enumerator
PICOTEST_VISIT_ENTER	Enter the test.
PICOTEST_VISIT_LEAVE	Leave the test.

Topics

Data Structures

Test Filters

Test hierarchy traversal

Test Functions

Logging

Namespaces

Detailed Description

Data Structure Documentation

◆ PicoTestMetadata

Macro Definition Documentation

◆ PICOTEST_NAMESPACE

◆ PICOTEST_NAMESPACE_DELIMITER

◆ PICOTEST_EXPORT

◆ PICOTEST_EXTERN

◆ PICOTEST_METADATA

◆ PICOTEST_FILTER_DEFAULT

◆ PICOTEST_FILTER

◆ PICOTEST_TRAVERSE

◆ PICOTEST_VISIT

◆ PICOTEST_FAILURE_LOGGER_DEFAULT

◆ PICOTEST_FAILURE_LOGGER

Typedef Documentation

◆ PicoTestProc

◆ PicoTestFilterProc

◆ PicoTestTraverseProc

◆ PicoTestVisitProc

◆ PicoTestFailureLoggerProc

Enumeration Type Documentation

◆ PicoTestFilterResult

◆ PicoTestVisitStep