Skip to content

Assertions & Runners

This page is a reference for how test cases fail in AceUnit 3.1.0 and for the C API declared in aceunit.h.

AceUnit has no assertion library of its own beyond a single assert() macro. You can fail a test case in several ways; whether the runner catches the failure depends on the runner.

If assert is not already defined when aceunit.h is included, aceunit.h defines assert(cond). When cond is false it calls AceUnit_fail(). In hosted environments it first prints a message to stderr:

file.c:12: testFoo: Assertion `x == 1' failed.

(Before C99, the function name is omitted.) In freestanding environments it prints nothing.

To use AceUnit’s assert(), include aceunit.h instead of <assert.h>:

#include <aceunit.h>
void testAddition(void) {
assert(1 + 1 == 2);
}

If you include <assert.h> first, you get the C library’s assert(), which usually calls abort().

How the test fails Simple SetJmp Abort Fork
assert() from aceunit.h stop yes yes yes
assert() from <assert.h> stop no yes yes
abort() stop no yes yes
exit() stop no no yes
longjmp() no yes yes no
Abnormal termination, for example SIGSEGV no no no yes
  • yes: the test case fails and the runner continues with the next test case.
  • stop: the test case fails, but the whole run stops.
  • no: not supported; the failure is not reported as a test failure and test execution is aborted.

The Fork runner does not need longjmp(): each test function runs in its own process, which already gives you exception-like isolation.

The runner’s main() prints a one-line summary to stderr and returns EXIT_SUCCESS when there were no failures, EXIT_FAILURE otherwise:

./leapyear_test: 2 test cases, 1 successful, 1 failed.

All declarations are in aceunit.h.

Declaration Purpose
typedef void (*aceunit_func_t)(void); A test function.
AceUnit_Fixture_t Struct with beforeAll, afterAll, beforeEach, afterEach (each may be NULL) and testcases, a NULL-terminated array.
AceUnit_Result_t Struct with int testCaseCount, successCount, failureCount.
extern const AceUnit_Fixture_t *fixtures[]; The generated fixture table.
void AceUnit_run(const AceUnit_Fixture_t *fixtures[], AceUnit_Result_t *result); Runs all fixtures and adds to result. It does not initialize result, so you can accumulate several runs.
void AceUnit_fail(void); Fails and aborts the current test case. Each runner implements it differently (for example longjmp() or exit()).
bool runCatching(void (*code)(void)); Runner hook: runs code and returns true only if it completed successfully. NULL counts as success.

aceunit.h provides bool, true, and false before C99 if <stdbool.h> is unavailable.

If none of the four runners fits your target, implement runCatching() and AceUnit_fail() yourself and link them with AceUnit_Runner.c (which provides AceUnit_run()) and, if you want the standard summary, AceUnit_Main.c. The existing runners in lib/ are short and are the best starting point.