Skip to content
zaerlPublic

About

Attractor is a lightweight single-header unit test framework written in C11, usable from C++17 (or later) too.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Latest commit

 

History

96 Commits

Folders and files

Repository files navigation

Attractor

Attractor is a lightweight single-header unit test framework written in C11, usable from C++17 (or later) too.

Installation

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.

Usage

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:

  1. char
  2. unsigned char
  3. signed char (int8_t)
  4. char*
  5. const char*
  6. short
  7. unsigned short
  8. int
  9. unsigned int
  10. long
  11. unsigned long
  12. long long
  13. unsigned long long
  14. float
  15. double
  16. long double
  17. void*
  18. const void*
  19. _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.

Test cases

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.

API

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 as ATT_ASSERT but 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 of size bytes are equal. Two NULL pointers are equal, a NULL and a non-NULL one 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 contains filter (all of them when NULL); return the number of failed cases, or -1 when 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 at index, or NULL when 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 with data.
  • void att_set_test_start_callback(att_test_start_callback callback) set a void callback(const char *name) to call before each test case run by att_run_tests.

Reporting:

  • int att_report(void) print the Tests valid/run: X/Y summary and return 0 if every test passed, 1 otherwise. Meant to be used as the return value of main().
  • 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 the Execution time line printed by att_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) and double att_get_double_epsilon(void) the float tolerance as a double, for callers without a long double type.

Callbacks. Pass NULL to remove one:

  • void att_set_output_callback(att_output_callback callback, void *data) send the output to a void callback(const char *text, void *data) instead of stdout.
  • void att_set_generic_callback(att_generic_callback callback) set an int 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 an int callback(int test, const char *description, const char *expression, const char *file, unsigned int line) that is called for every assertion: test is non-zero when it passed and expression is 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).

Examples

#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:

  • 0 prints only the failures.
  • 1 adds the test case names, printed by att_run_tests() before each case.
  • 2 adds a . per valid assertion and an F per failed one, on the same line as the case name.
  • 3 prints an OK/FAIL line per assertion instead of the dots.
  • 4 behaves like 3 and additionally closes every test case with its own Valid/run: X/Y summary 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, 4

Outside 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

Examples with errors

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

Advanced usage

Check the tests folder for advanced examples.

Threading

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.

Strings

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.

Floats

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 equality

TAP output

For 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

Colors

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.

Output callback

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.

Custom types

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.

Custom callback

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);
}

About

Attractor is a lightweight single-header unit test framework written in C11, usable from C++17 (or later) too.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages