Arbiter

Arbiter is a lightweight unit-test library written in C. Arbiter isn't a command-line tool. Rather, it is a header file and a single C source file that you compile with your unit tests and source code to generate an executable.

Usage

See /example for an example test suite written using Arbiter.

Using Arbiter

To use Arbiter, we recommend cloning this repository to the root of your project. Then include arbiter/include/arbiter.h as an include path during the compilation step and compile arbiter/src/arbiter.c along with your unit tests. See /example for a more detailed walkthrough.

Writing unit tests

Unit tests should be written as functions with the signature void unit_test(). Inside a unit test, you can use arbiter_assert to evoke an assertion test; the test is considered to have failed if the asserted expression evaluates to false.

For example:

/**
 * This test succeeds
 */
void unit_test() {
    arbiter_assert(1 == 1);
}

/**
 * This test fails
 */
void failing_unit_test() {
    arbiter_assert(1 == 0);
}

See /example/tests/test-integer-pow.c for more detailed examples.

Running a suite of unit tests

A test suite can be run by using the arbiter_run_tests function. arbiter_run_tests has the following signature:

void arbiter_run_tests(int num_tests, char* name, void (*tests[])());

For example, the tests above can be run using:

void (*tests[2])() = {
        unit_test,
        failing_unit_test,
};

arbiter_run_tests(2, "example_test_suite", tests);

See /example/tests/test-integer-pow.c for more detailed examples.

This function must be called inside a main function. You can then compile your library sources, the arbiter and the test suite source (that contains the main function that calls arbiter_run_tests) to an executable.

Types of errors that are caught

Currently, Arbiter catches the following types of failed states

Failed state	Description
Assertion failures	These occur when the boolean condition passed to arbiter_assert is false.
Aborts	Arbiter catches the SIGABRT signal and reports these as an abort failure.
Segmentation Faults	Arbiter catches the SIGSEGV signal and reports these as a Segmentation fault.

Available options

Arbiter uses the following object-like preprocessor macros to modify its behaviour:

Option name	Possilbe Values	Description	Default
ARBITER_VERBOSE	0	Prints all status of all unit tests and summary.	0
	1	Prints only failed unit tests and summary.
ARBITER_STDERR_LOG_DIR	"<location>"	Location of folder to store the stderr logs. NOTE: The double quotation marks are necessary.	"tests-stderr"

These object-like macros can be set in arbiter.h or passed in during your compile step:

gcc -D'ARBITER_VERBOSE=1' -D'ARBITER_STDERR_LOG_DIR="tests-stderr-logs"' -Iarbiter/include/arbiter.h -o tests unit-tests.c arbiter/src/arbiter.c