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.
Failing a test case
Section titled “Failing a test case”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.
assert() from aceunit.h
Section titled “assert() from aceunit.h”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().
Which runner catches what
Section titled “Which runner catches what”| 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.
Test run results
Section titled “Test run results”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.
Write your own runner
Section titled “Write your own runner”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.
Next steps
Section titled “Next steps”- Core Concepts: choosing a runner.
- Mocking: replacing dependencies in tests.