This file defines a minimalist unit testing framework for C programs. More...

#include <setjmp.h>
#include <stdarg.h>
#include <string.h>

Data Structures
struct	PicoTestMetadata
	Test metadata. More...

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

Test Filters
PicoTest provides a way for client code to select tests to be run using custom filter functions.
#define	PICOTEST_FILTER_DEFAULT
	Default test filter function.
#define	PICOTEST_FILTER
	Define the test filter function.
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.

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.
#define	PICOTEST_TRAVERSE(_testName, _proc)
	Traverse a test hierarchy depth-first.
#define	PICOTEST_VISIT(_testName, _proc)
	Visit a test hierarchy depth-first.
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.

Logging
PicoTest provides a way for client code to intercept test failure events. This can be used for e.g. logging purpose or reporting.
#define	PICOTEST_FAILURE_LOGGER_DEFAULT
	Default test failure log handler.
#define	PICOTEST_FAILURE_LOGGER
	Define the test failure log handler.
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.

Test Case Definitions
#define	PICOTEST_CASE(...)
	Test case declaration.

Test Case Hooks
PicoTest provides a way for client code to intercept test case events. This can be used for e.g. logging purpose or reporting.
#define	PICOTEST_CASE_ENTER_DEFAULT(testName)
	Default test case enter hook.
#define	PICOTEST_CASE_ENTER
	Define the test case enter hook.
#define	PICOTEST_CASE_LEAVE_DEFAULT(testName, fail)
	Default test case enter hook.
#define	PICOTEST_CASE_LEAVE
	Define the test case leave hook.
typedef void	PicoTestCaseEnterProc(const char *testName)
	Function signature of test case enter hooks.
typedef void	PicoTestCaseLeaveProc(const char *testName, int fail)
	Function signature of test case leave hooks.

Assertion Definitions
#define	PICOTEST_ASSERT(x, ...)
	Hard assertion.
#define	PICOTEST_VERIFY(x, ...)
	Soft assertion.
#define	PICOTEST_FAILURE(type, test, ...)
	Generic failure.
#define	PICOTEST_ABORT()
	Abort a test case.

Assertion Hooks
PicoTest provides a way for client code to intercept assertions events. This can be used for e.g. logging purpose or reporting.
#define	PICOTEST_ASSERT_BEFORE_DEFAULT(type, test)
	Default assert before hook.
#define	PICOTEST_ASSERT_BEFORE
	Define the assert before hook.
#define	PICOTEST_ASSERT_AFTER_DEFAULT(type, test, fail)
	Default assert after hook.
#define	PICOTEST_ASSERT_AFTER
	Define the assert after hook.
typedef void	PicoTestAssertBeforeProc(const char type, const char test)
	Function signature of assert before hooks.
typedef void	PicoTestAssertAfterProc(const char type, const char test, int fail)
	Function signature of assert after hooks.

Test Fixture Definitions
#define	PICOTEST_FIXTURE_CONTEXT(_fixtureName)
	Test fixture context declaration.
#define	PICOTEST_FIXTURE_SETUP(...)
	Test fixture initialization.
#define	PICOTEST_FIXTURE_TEARDOWN(...)
	Test fixture cleanup.

Test Fixture Hooks
PicoTest provides a way for client code to intercept test fixture events. This can be used for e.g. logging purpose or reporting.
#define	PICOTEST_FIXTURE_BEFORE_SETUP_DEFAULT(fixtureName, testName)
	Default test fixture before setup hook.
#define	PICOTEST_FIXTURE_BEFORE_SETUP
	Define the test fixture before setup hook.
#define	PICOTEST_FIXTURE_AFTER_SETUP_DEFAULT(fixtureName, testName)
	Default test fixture after setup hook.
#define	PICOTEST_FIXTURE_AFTER_SETUP
	Define the test fixture after setup hook.
#define	PICOTEST_FIXTURE_BEFORE_TEARDOWN_DEFAULT(fixtureName, testName, fail)
	Default test fixture before teardown hook.
#define	PICOTEST_FIXTURE_BEFORE_TEARDOWN
	Define the test fixture before teardown hook.
#define	PICOTEST_FIXTURE_AFTER_TEARDOWN_DEFAULT(fixtureName, testName, fail)
	Default test fixture after teardown hook.
#define	PICOTEST_FIXTURE_AFTER_TEARDOWN
	Define the test fixture after teardown hook.
typedef void	PicoTestFixtureBeforeSetupProc(const char fixtureName, const char testName)
	Function signature of test fixture before setup hooks.
typedef void	PicoTestFixtureAfterSetupProc(const char fixtureName, const char testName)
	Function signature of test fixture after setup hooks.
typedef void	PicoTestFixtureBeforeTeardownProc(const char fixtureName, const char testName, int fail)
	Function signature of test fixture before teardown hooks.
typedef void	PicoTestFixtureAfterTeardownProc(const char fixtureName, const char testName, int fail)
	Function signature of test fixture after teardown hooks.

Test Suite Definitions
#define	PICOTEST_SUITE(_suiteName, ...)
	Test suite declaration.

Test Suite Hooks
PicoTest provides a way for client code to intercept test execution events on test suites and their subtests. This can be used for e.g. logging purpose or reporting.
#define	PICOTEST_SUITE_ENTER_DEFAULT(suiteName, nb)
	Default test suite enter hook.
#define	PICOTEST_SUITE_ENTER
	Define the test suite enter hook.
#define	PICOTEST_SUITE_LEAVE_DEFAULT(suiteName, nb, fail)
	Default test suite leave hook.
#define	PICOTEST_SUITE_LEAVE
	Define the test suite leave hook.
#define	PICOTEST_SUITE_BEFORE_SUBTEST_DEFAULT(suiteName, nb, fail, index, testName)
	Default test suite before subtest hook.
#define	PICOTEST_SUITE_BEFORE_SUBTEST
	Define the test suite before subset hook.
#define	PICOTEST_SUITE_AFTER_SUBTEST_DEFAULT(suiteName, nb, fail, index, testName, sfail)
	Default test suite after subtest hook.
#define	PICOTEST_SUITE_AFTER_SUBTEST
	Define the test suite after subset hook.
typedef void	PicoTestSuiteEnterProc(const char *suiteName, int nb)
	Function signature of test suite enter hooks.
typedef void	PicoTestSuiteLeaveProc(const char *suiteName, int nb, int fail)
	Function signature of test suite leave hooks.
typedef void	PicoTestSuiteBeforeSubtestProc(const char suiteName, int nb, int fail, int index, const char testName)
	Function signature of test suite before subtest hooks.
typedef void	PicoTestSuiteAfterSubtestProc(const char suiteName, int nb, int fail, int index, const char testName, int sfail)
	Function signature of test suite after subtest hooks.

Detailed Description

This file defines a minimalist unit testing framework for C programs.

The assertion mechanism relies on setjmp() / longjmp(). While these functions are discouraged for production code, their usage is acceptable in the context of unit testing: in our case, longjmp() is only called when an assertion fails, a situation where the actual process state is no longer reliable anyway. Moreover, they constitute the only standard exception handling mechanism for plain C code.

License

PicoTest is released under the terms of the The 3-Clause BSD License:

https://opensource.org/licenses/BSD-3-Clause

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Data Structures

Test Functions

Test Filters

Test hierarchy traversal

Logging

Test Case Definitions

Test Case Hooks

Assertion Definitions

Assertion Hooks

Test Fixture Definitions

Test Fixture Hooks

Test Suite Definitions

Test Suite Hooks

Detailed Description