greatest

A testing system for C, contained in 1 header file.

Key Features and Project Goals

Small, Portable, Lightweight

greatest doesn't depend on anything beyond ANSI C89, and the test scaffolding should build without warnings when compiled with -Wall -Wextra -pedantic. It is under 1,000 LOC (SLOCCount), and does no dynamic allocation.
Permissive License

greatest is released under the ISC License. You can use it freely, even for commercial purposes.
Easy To Set Up

To use, just #include "greatest.h" in your project. There is very little boilerplate. Most features are optional.
Un-Opinionated

When a command-line test runner is useful, greatest can provide one, but it can also run as part of other programs. It doesn't depend on a particular build system or other tooling, and should accommodate a variety of testing approaches. It actively avoids imposing architectural choices on code under test. While greatest was designed with C in mind, it attempts to be usable from C++.
Modular

Tests can be run individually, or grouped into suites. Suites can share common setup, and can be in distinct compilation units.
Low Friction

Specific tests or suites can be run by name, for focused and rapid iteration during development. greatest adds very little startup latency.

There are some compile-time options, and slightly nicer syntax for parametric testing (running tests with arguments) if compiled with a C99 or later language standard.

I wrote a blog post with more information. While it's several years old, it's still accurate about the main functionality.

theft, a related project, adds property-based testing.

Basic Usage

#include "greatest.h"

/* A test runs various assertions, then calls PASS(), FAIL(), or SKIP(). */
TEST x_should_equal_1(void) {
    int x = 1;
    /* Compare, with an automatic "1 != x" failure message */
    ASSERT_EQ(1, x);

    /* Compare, with a custom failure message */
    ASSERT_EQm("Yikes, x doesn't equal 1", 1, x);

    /* Compare, and if they differ, print both values,
     * formatted like `printf("Expected: %d\nGot: %d\n", 1, x);` */
    ASSERT_EQ_FMT(1, x, "%d");
    PASS();
}

/* Suites can group multiple tests with common setup. */
SUITE(the_suite) {
    RUN_TEST(x_should_equal_1);
}

/* Add definitions that need to be in the test runner's main file. */
GREATEST_MAIN_DEFS();

int main(int argc, char **argv) {
    GREATEST_MAIN_BEGIN();      /* command-line options, initialization. */

    /* Individual tests can be run directly in main, outside of suites. */
    /* RUN_TEST(x_should_equal_1); */

    /* Tests can also be gathered into test suites. */
    RUN_SUITE(the_suite);

    GREATEST_MAIN_END();        /* display results */
}

Output:

$ make simple && ./simple
cc -g -Wall -Werror -pedantic    simple.c   -o simple

* Suite the_suite:
.
1 test - 1 passed, 0 failed, 0 skipped (5 ticks, 0.000 sec)

Total: 1 test (47 ticks, 0.000 sec), 3 assertions
Pass: 1, fail: 0, skip: 0.

Tests are run with RUN_TEST(test_name), which can be called directly from the test runner's main function or grouped into suites (which are run with RUN_SUITE(suite_name)). (Calls to RUN_TEST from inside another test are ignored.)

Test cases can be run with arguments: RUN_TEST1(test_name, arg) passes a single argument, and if C99 features are supported, then RUN_TESTp(test_name, ...) uses __VA_ARGS__ to run a test case with one or mare arguments. greatest_set_test_suffix sets a name suffix, so output from the test runner can include info about arguments.

Test cases should call assertions and then end with PASS(), SKIP(), FAIL(), or their custom message variants (e.g. SKIPm("TODO");). If there are any test failures, the test runner will return 1, otherwise it will return 0. (Skips do not cause the test runner to report failure.)

PASS(), SKIP(), FAIL(), and their custom message variants are macros that updating internal bookkeeping and then returning and enum value, such as GREATEST_TEST_RES_FAIL. They all return from the current test case function.

PASS()/PASSm("msg") prints as a dot when verbosity is zero, or the test name and custom message (if any) with verbosity >= 1.

FAIL()/FAILm("msg") always prints "FAIL test_name: msg file:line".

SKIP()/SKIPm("msg") prints as an 's' when verbosity is zero, or the test name and custom message (if any) with verbosity >= 1. Because skips are not treated as a failure by the test runner, they can be used to skip test cases that aren't relevant in a particular build or environment, a way to temporarily disable broken tests, or as a sort of todo list for tests and functionality under active development.

Tests and suites are just functions, so normal C scoping rules apply. For example, a test or suite named main will have a name collision.

(For more examples, look at example.c and example_suite.c.)

Filtering By Name

greatest runs all tests by default, but can be configured to only run suites or tests whose names contain a filter string, and/or exclude tests whose name contains a filter string. When test name filtering and exclusion are used together, exclusion takes precedence.

void greatest_set_suite_filter(const char *name);
void greatest_set_test_filter(const char *name);
void greatest_set_test_exclude(const char *name);

These correspond to the following command line test runner options:

`-s SUITE`:   Only run suites whose names contain the string "SUITE"
`-t TEST`:    Only run tests whose names contain the string "TEST"
`-x EXCLUDE`: Exclude tests whose names contain the string "EXCLUDE"

For example, to run any tests with "tree" in the name, in suites with "pars" in the name (such as "parser"), but exclude any tests whose names also contain "slow":

./test_project -s pars -t tree -x slow

The string matching includes optional test name suffixes.

The greatest_set_exact_name_match() function and corresponding -e command line runner flag can be used to only run tests and/or suites whose names exactly match the name filter(s). Note: exact-match suite filtering by name will not skip tests that are run outside of any suite.

Available Assertions

Assertions fail the current test unless some condition holds. All assertions have a custom message variant (with an m suffix), which takes a message string as its first argument. For example, the assertion ASSERT_EQ(apple, orange); could instead be used like ASSERT_EQm("these should match", apple, orange). Non-message assertions create a default message.

`ASSERT(COND)`

Assert that COND evaluates to a true (non-zero) value.

`ASSERT_FALSE(COND)`

Assert that COND evaluates to a false (zero) value.

`ASSERT_EQ(EXPECTED, ACTUAL)`

Assert that EXPECTED == ACTUAL. To print the values if they differ, use ASSERT_EQ_FMT. To compare with custom equality test and print functions, use ASSERT_EQUAL_T instead.

`ASSERT_NEQ(EXPECTED, ACTUAL)`

Assert that EXPECTED != ACTUAL.

`ASSERT_GT(EXPECTED, ACTUAL)`

Assert that EXPECTED > ACTUAL.

`ASSERT_GTE(EXPECTED, ACTUAL)`

Assert that EXPECTED >= ACTUAL.

`ASSERT_LT(EXPECTED, ACTUAL)`

Assert that EXPECTED < ACTUAL.

`ASSERT_LTE(EXPECTED, ACTUAL)`

Assert that EXPECTED <= ACTUAL.

`ASSERT_EQ_FMT(EXPECTED, ACTUAL, FORMAT)`

Assert that EXPECTED == ACTUAL. If they are not equal, print their values using FORMAT as the printf format string.

For example: ASSERT_EQ_FMT(123, result, "%d"); will call printf like printf("Expected: %d\nGot: %d\n", 123, result); if its EXPECTED and ACTUAL arguments don't match.

Note: EXPECTED and ACTUAL will be evaluated more than once on failure, so they should not be a function call with side effects. (Since their type is not known by the macro, they cannot be captured in a local variable. typeof is a GCC extension.)

`ASSERT_IN_RANGE(EXPECTED, ACTUAL, TOLERANCE)`

Assert that ACTUAL is within EXPECTED +/- TOLERANCE, once the values have been converted to a configurable floating point type (GREATEST_FLOAT).

greatest does not depent on floating point math. It is only used within ASSERT_IN_RANGE's macro expansion.

`ASSERT_STR_EQ(EXPECTED, ACTUAL)`

Assert that the strings are equal (i.e., strcmp(EXPECTED, ACTUAL) == 0).

`ASSERT_STRN_EQ(EXPECTED, ACTUAL, SIZE)`

Assert that the first SIZE bytes of the strings are equal (i.e., strncmp(EXPECTED, ACTUAL, SIZE) == 0).

`ASSERT_MEM_EQ(EXPECTED, ACTUAL, SIZE)`

Assert that the first SIZE bytes of memory pointed to by EXPECTED and ACTUAL are equal. If their memory differs, print a hexdump and highlight the lines and individual bytes which do not match.

`ASSERT_ENUM_EQ(EXPECTED, ACTUAL, ENUM_STR_FUN)`

Assert that the enum value EXPECTED is equal to ACTUAL. If not, convert each enum value to a string using ENUM_STR_FUN before printing them.

ENUM_STR_FUN should have a type like:

const char *FUN(int x);

`ASSERT_EQUAL_T(EXPECTED, ACTUAL, TYPE_INFO, UDATA)`

Assert that EXPECTED and ACTUAL are equal, using the greatest_equal_cb function pointed to by TYPE_INFO->equal to compare them. The assertion's UDATA argument can be used to pass in arbitrary user data (or NULL) to the callbacks. If the values are not equal and the TYPE_INFO->print function is defined, it will be used to print an "Expected: X, Got: Y" message.

`ASSERT_OR_LONGJMP(COND)`

Assert that COND evaluates to a true

Greatest

Install / Use

README