Creating your tests

How to register your first test with CST

The recommended way to register tests is with the TEST macro that is included in cst.h.

test.c

#include "cst.h"

TEST("Category name", "Test name") {
    // Test code
}

As you can see, registering a test doesn't require a function. You can see the TEST macro as a "function" itself that will run isolated on a different process.

Tests can be grouped in categories. Categories are optional, you can always use NULL to create tests that don't belong to any category.

Tests also have a name in order to display their results. A test can also have a NULL name, in which case the test will be displayed as "???". This is, of course, not recommended.

You can learn exactly how test registration works on a technical level here.

Test execution order

Because of how CST works, tests will always be registered in the same order. Take a look at this command: gcc test1.c test2.c cst.c -o test_run.

As you can see, we compile test1.c first, then test2.c. This means that all tests within test1.c will be registered first. Then, tests within test2.c are registered. The order at which tests are found in the file is also relevant.

test1.c

#include "cst.h"

TEST("Example", "First test") {
    // This will run first
}

TEST("Example", "Second test") {
    // This will run second
}

Lifecycle hooks can be used in order to initialize everything before your tests.

You can learn exactly how test execution works on a technical level here.

Tips for clean tests

If you want to keep your tests clean, I recommend:

• Separating your tests from your source code, ideally in different directories such as src/ and test/.

• Having one file per category of tests.

• Defining a constant string for the category to avoid typos.

A clean test file should look something like this:

clean_test.c

#include "cst.h"

static const char *category = "Some awesome tests";

TEST(category, "Descriptive test name") {
    // Test code
}

TEST(category, "Another cool test name") {
    // Test code
}