picotestRunner.inc File Reference

This file provides a fully functional test runner and hooks for picotest suites. More...

#include <picotest.h>

Macros
#define	PICOTEST_MAINSUITE
	Defining PICOTEST_MAINSUITE before including picotestRunner.inc will define the main() function with standard option parsing and run the provided test suite.

Detailed Description

This file provides a fully functional test runner and hooks for picotest suites.

It's the easiest way to add PicoTest support to a new or existing project with minimal effort. See PicoTest's own test suite for an example of how to do it.

Getting started

• Include this file in all files that define test cases and suites. It is idempotent and can be safely included more than once.
• Define PICOTEST_MAINSUITE in the main file

That's it!

Usage

The generated executable expects the following command line arguments:

<test_runner> ?option? ?test names?

If the leading argument starts with -, it is interpreted as an option; the remaining arguments provide the test names to execute.

Options

Options are mutually exclusive.

Test lists:

• -l, --list: Lists all test cases (names only)
• -a, --list-all: Lists all test cases and suites (names only)
• -h, --hierarchy: Lists all test cases (/-separated paths)
• -j, --list-json: Lists all test cases and suites in JSON format (names, file paths, line numbers, subtests)

Test output:

• -J, --json: Outputs a newline-delimited JSON event stream instead of plain text.

License

This file is public domain.

Copyright (c) 2025 Frederic Bonnet

Macro Definition Documentation

PICOTEST_MAINSUITE

#define PICOTEST_MAINSUITE

Defining PICOTEST_MAINSUITE before including picotestRunner.inc will define the main() function with standard option parsing and run the provided test suite.

Only do it once per executable.

Example

The PicoTest test suite is a good example of how to use this macro from the main entry point:

#include <picotest.h>
 
#include "hooks.h"
 
PICOTEST_SUITE(mainSuite, testAssertions, testAssertionHooks, testCases,
               testCaseHooks, testFixtures, testFixtureHooks, testNamespaces,
               testSuites, testSuiteHooks, testFilters, testTraversal,
               testLoggers, testMetadata);
 
#define PICOTEST_MAINSUITE mainSuite
#include <picotestRunner.inc>