Attractor is a lightweight single-header unit test framework written in C11, usable from C++17 (or later) too.
Attractor is a single-header library: copy attractor.h into your test folder. In exactly one
.c/.cpp source file define ATT_IMPLEMENTATION before including the header:
// define ATT_IMPLEMENTATION for only *one* .c/.cpp
#define ATT_IMPLEMENTATION
#include "attractor.h"Every other source file just includes attractor.h.
Attractor provides an ATT_ASSERT macro that you can use to test your code. The macro is an
expression that evaluates to a number different from zero if the test passes:
ATT_ASSERT(the_value_to_test, the_expected_value, "description");
// Or, being an expression:
if(!ATT_ASSERT(the_value_to_test, the_expected_value, "description")) {
// React to the failure
}The ATT_ASSERT macro accepts these types:
charunsigned charsigned char(int8_t)char*const char*shortunsigned shortintunsigned intlongunsigned longlong longunsigned long longfloatdoublelong doublevoid*const void*_Bool(bool)
In case of unknown type the input is assumed to be const void*.
Important
The expected value is never silently converted (type coercion) to the type of the tested one. An
integer compared with a floating point value is compared as floating point, and a signed integer
compared with an unsigned one is compared mathematically: ATT_ASSERT_LT(-1, 1u, ...) passes,
because a negative number is smaller than every unsigned one.
In C++ the two values are converted to their common type, std::string is accepted too, and
comparing two non-pointer values of an unsupported type is a compile error.
Enumerations are compared by their value. In C they are plain integers; in C++ both unscoped and
scoped (enum class) enumerations are accepted and compared through their underlying type, against
a value of the same enumeration or against an integer. Comparing two different enumeration types is
a compile error.
enum class color { red, green };
ATT_ASSERT(parse_color("green"), color::green, "green is parsed");
ATT_ASSERT_NE(parse_color("green"), color::red, "green is not red");Beyond equality, the ATT_ASSERT_NE, ATT_ASSERT_LT, ATT_ASSERT_LE, ATT_ASSERT_GT and
ATT_ASSERT_GE macros compare with the other operators, accepting the same types and keeping the
typed failure output (Expected < 10, got 12):
ATT_ASSERT_NE(errno, 0, "errno was set");
ATT_ASSERT_LT(elapsed_ms, 100l, "fast enough");
ATT_ASSERT_GE(count, 1u, "at least one result");Strings compare lexicographically (via strcmp), so ATT_ASSERT_LT("abc", "abd", ...) passes.
Floats keep the epsilon semantics for NE (values equal within the tolerance are not "not equal"),
while LT/LE/GT/GE compare plainly. void*, _Bool and unknown types support only equality
and inequality; the other operators fail with an Operator < is not supported for this type
message.
Two more assertion macros cover the common cases that are not a typed comparison:
ATT_ASSERT_TRUE(is_valid(input), "input is valid");
ATT_ASSERT_MEM(buffer, expected_buffer, sizeof(buffer), "buffers are equal");ATT_ASSERT_TRUE passes when the condition is true. ATT_ASSERT_MEM compares two memory regions
byte by byte and, on failure, reports the offset and value of the first differing byte.
Assertions can be grouped into named test cases. ATT_TEST(name) defines a test case function and
registers it automatically before main() runs:
#define ATT_IMPLEMENTATION
#include "attractor.h"
ATT_TEST(math_add) {
ATT_ASSERT(2 + 2, 4, "2 + 2 == 4");
}
ATT_TEST(strings_hello) {
ATT_ASSERT("hello", "hello", "hello == hello");
}
int main(void) {
att_run_tests(NULL);
return att_report();
}att_run_tests(filter) runs the registered cases whose name contains filter, or all of them when
filter is NULL. A test case fails when at least one of its assertions fails; failed cases are
listed in a recap and counted in a Test cases valid/run: X/Y summary. The function returns the
number of failed cases and composes with att_report(), which keeps printing the assertion summary
and producing the exit code.
A filter that matches no test case is reported (No test case matches the filter "..."), counted as
a failed assertion and makes att_run_tests() return -1:
$ ./test
Test: math_add .
Test: strings_hello .
Execution time: 0.0001 seconds
Test cases valid/run: 2/2
Tests valid/run: 2/2
Define ATT_SHOW_EXECUTION_TIME to 0 or call att_set_show_execution_time(0) to hide that
execution time line.
For per-case setup or logging, att_set_test_start_callback() registers a callback that
att_run_tests() calls before each test case, passing the case name. Assertions made inside the
callback count toward the case that is about to run.
The registry holds ATT_MAX_TESTS cases (512 by default). Define a bigger value in the
ATT_IMPLEMENTATION file if you need more. In TAP mode each case is announced with a # test: name
diagnostic line.
Assertions. Each one is an expression that evaluates to non-zero when it passes:
ATT_ASSERT(value, expected, description)you pass the value to test, the expected one and a description of the test.ATT_ASSERT_NE/LT/LE/GT/GE(value, expected, description)same asATT_ASSERTbut compare with!=,<,<=,>or>=.ATT_ASSERT_TRUE(condition, description)assert that a condition is true.ATT_ASSERT_MEM(value, expected, size, description)assert that two memory regions ofsizebytes are equal. TwoNULLpointers are equal, aNULLand a non-NULLone are not.
Test cases:
ATT_TEST(name)define a named test case and register it automatically.int att_run_tests(const char *filter)run the registered test cases whose name containsfilter(all of them whenNULL); return the number of failed cases, or-1when the filter matches no test case.unsigned int att_get_test_count(void)return the count of registered test cases.const char *att_get_test_name(unsigned int index)return the name of the test case atindex, orNULLwhen out of range.void att_register_test(const char *name, att_test_fn fn)register a test case manually.void att_register_test_data(const char *name, att_test_data_fn fn, void *data)register a test case that is called withdata.void att_set_test_start_callback(att_test_start_callback callback)set avoid callback(const char *name)to call before each test case run byatt_run_tests.
Reporting:
int att_report(void)print theTests valid/run: X/Ysummary and return0if every test passed,1otherwise. Meant to be used as the return value ofmain().unsigned int att_get_valid_tests(void)return the count of valid tests.unsigned int att_get_total_tests(void)return the count of run tests.
Settings:
void att_set_verbose(unsigned int verbose)set verbosity (0 to 4).void att_set_show_error(unsigned int show_error)set to show errors.void att_set_show_execution_time(unsigned int show_execution_time)set to show theExecution timeline printed byatt_run_tests.void att_set_tap(unsigned int tap)enable TAP (Test Anything Protocol) output.void att_set_float_epsilon(long double epsilon)set the tolerance for float comparisons.long double att_get_float_epsilon(void)return the current float comparison tolerance.void att_set_double_epsilon(double epsilon)anddouble att_get_double_epsilon(void)the float tolerance as adouble, for callers without along doubletype.
Callbacks. Pass NULL to remove one:
void att_set_output_callback(att_output_callback callback, void *data)send the output to avoid callback(const char *text, void *data)instead of stdout.void att_set_generic_callback(att_generic_callback callback)set anint callback(void *result, void *expected, att_op op, const char *description)that compares the values of unknown types; it returns non-zero when the assertion passes. See Custom callback.void att_set_test_callback(att_test_callback callback)set anint callback(int test, const char *description, const char *expression, const char *file, unsigned int line)that is called for every assertion:testis non-zero when it passed andexpressionis the source text of the tested value. The return value is ignored.
Compile-time configuration. Define these before including the header in the ATT_IMPLEMENTATION
file:
| Macro | Default | Meaning |
|---|---|---|
ATT_VERBOSE |
2 |
Initial verbosity (0 to 4). |
ATT_SHOW_ERROR |
1 |
Print the failure details. |
ATT_SHOW_EXECUTION_TIME |
1 |
Print the Execution time line. |
ATT_TAP |
0 |
Emit TAP output. |
ATT_FLOAT_EPSILON |
0 |
Initial tolerance for float comparisons. |
ATT_STRING_AS_POINTERS |
0 |
Print strings as pointer addresses. |
ATT_MAX_TESTS |
512 |
Size of the test case registry. |
ATT_API |
empty | Prefix of every public declaration (e.g. an export macro). |
ATT_CUSTOM_TYPES is different: it changes the ATT_ASSERT macros, so it must be defined before
every include of the header. See Custom types.
The header also defines its version: ATT_VERSION (the "1.2.0" string), ATT_VERSION_MAJOR,
ATT_VERSION_MINOR, ATT_VERSION_REVISION and ATT_VERSION_NUMBER
(MAJOR << 8 | MINOR << 4 | REVISION, so 0x120).
#define ATT_IMPLEMENTATION
#include "attractor.h"
int main(void) {
int var_to_test_1 = 1;
float var_to_test_2 = 2.0;
ATT_ASSERT(var_to_test_1, 1, "one == one");
ATT_ASSERT(var_to_test_2, 2.0, "2.0 == 2.0");
ATT_ASSERT(3ll, 3ll, "long long 3 == long long 3");
// Print "Tests valid/run: 3/3" and exit non-zero if a test failed
return att_report();
}The default verbosity is 2. Each level adds output on top of the previous one:
0prints only the failures.1adds the test case names, printed byatt_run_tests()before each case.2adds a.per valid assertion and anFper failed one, on the same line as the case name.3prints anOK/FAILline per assertion instead of the dots.4behaves like 3 and additionally closes every test case with its ownValid/run: X/Ysummary counting only that case's assertions.
You can change the level using:
// By defining:
#define ATT_VERBOSE 2 // 0, 1, 2, 3, 4
// Or by calling:
att_set_verbose(2); // 0, 1, 2, 3, 4Outside of att_run_tests() there are no case names, so levels 0 and 1 print only the failures and
level 2 prints the plain dots:
...
Tests valid/run: 3/3
With verbose = 3 the code outputs:
OK [int] one == one
OK [float] 2.0 == 2.0
OK [long long] long long 3 == long long 3
Tests valid/run: 3/3
And this is verbose = 4 with two test cases:
Test: math_add
OK [int] 2 + 2 == 4
Valid/run: 1/1
Test: strings_hello
OK [char *] hello == hello
Valid/run: 1/1
Execution time: 0.0001 seconds
Test cases valid/run: 2/2
Tests valid/run: 2/2
Failures are reported independently of the verbosity level: they are shown whenever att_show_error
is set (the default). Set att_set_show_error(0) if you really want complete silence.
If we change var_to_test_2 in 1.0 this is the output with verbose = 2. Each failure is prefixed
with the source file:line and, below verbose 3, the test description, so it is self-contained:
.F
test.c:9: 2.0 == 2.0: Expected 2, got 1
.
Tests valid/run: 2/3
With verbose = 0 only the failures are printed (no . for the passing tests):
test.c:9: 2.0 == 2.0: Expected 2, got 1
Tests valid/run: 2/3
And with verbose = 3 the description is already on the result line, so it is not repeated:
OK [int] one == one
FAIL [float] 2.0 == 2.0
test.c:9: Expected 2, got 1
OK [long long] long long 3 == long long 3
Tests valid/run: 2/3
Check the tests folder for advanced examples.
The valid/total test counters are atomic, so ATT_ASSERT can be used from several threads at once
without losing updates. att_get_valid_tests() and att_get_total_tests() therefore report the
exact number of assertions run, even when tests execute concurrently. att_run_tests() itself runs
the registered test cases sequentially, on the calling thread.
Attractor treats strings as strings. So the content of the string is output to the terminal as it is
in case of error. By defining #define ATT_STRING_AS_POINTERS 1, it will simply output the pointer
address.
float, double and long double are compared for exact equality by default. Because computed
floating point results are rarely bit-exact, you can define a tolerance. Values are then considered
equal when their absolute difference is within ATT_FLOAT_EPSILON:
// 1e-6 is usually enough
#define ATT_FLOAT_EPSILON 1e-6
ATT_ASSERT(0.1 + 0.2, 0.3, "sum within epsilon");The default is 0 (exact equality). The compile-time ATT_FLOAT_EPSILON is just the initial value;
you can also change the tolerance at runtime, the same way you change verbosity:
att_set_float_epsilon(1e-6);
ATT_ASSERT(0.1 + 0.2, 0.3, "sum within epsilon");
att_set_float_epsilon(0); // back to exact equalityFor machine-readable output, enable TAP (Test Anything Protocol) mode with #define ATT_TAP 1 or
att_set_tap(1). It replaces the dot/OK reporting: every assertion prints an ok N - description
or not ok N - description line, error details become # diagnostic lines, and att_report()
emits the trailing 1..N plan. The output plugs directly into prove and other TAP harnesses:
ok 1 - one == one
not ok 2 - 2.0 == 2.5
# example.c:12: Expected 2.5, got 2
1..2
# Tests valid/run: 1/2
When stdout is a terminal the test case names, the F marks, the OK/FAIL labels and the
summaries are colored. Colors are turned off when the output is redirected, when the NO_COLOR
environment variable is set and, outside Windows, when TERM is unset or dumb.
By default everything is printed to stdout. att_set_output_callback(callback, data) sends the
output to a function instead, for example to capture it or to print it through another runtime's
own stdout. The callback receives fragments of text, not necessarily whole lines:
static void to_stderr(const char *text, void *data) {
fputs(text, stderr);
}
att_set_output_callback(to_stderr, NULL);Pass NULL to print to stdout again.
In C, a type that is not in the list falls back to const void* and is compared by address. To
route one of your types to a specific assertion function, define ATT_CUSTOM_TYPES as a list of
_Generic associations, each followed by a comma, before including the header:
typedef struct custom_struct {
int value;
} custom_struct;
#define ATT_CUSTOM_TYPES custom_struct*: att_assert_p_p,
#include "attractor.h"ATT_CUSTOM_TYPES is not used in C++, where any pointer type is already accepted.
You can register a custom function to be called when a type is not one of the list.
#include "attractor.h"
typedef struct unknown_struct {
int unknown;
} unknown_struct;
int assert_unknown(void* result, void* expected, att_op op, const char *description) {
if(!result || !expected) {
return 0;
}
int equal = ((unknown_struct*)result)->unknown == ((unknown_struct*)expected)->unknown;
// The callback receives the operator, so ATT_ASSERT_NE works too
return op == ATT_OP_NE ? !equal : equal;
}
void test_unknown_callback() {
unknown_struct sa;
unknown_struct sb;
sa.unknown = 1;
sb.unknown = 1;
att_set_generic_callback(&assert_unknown);
ATT_ASSERT(&sa, &sb, "Unknown struct sa = sb");
att_set_generic_callback(NULL);
}