Tutorial

How to use PCUT

This page will guide you through the process of creating tests with PCUT, starting from the simplest ones to more complicated settings.

All the examples are expected to be created inside tut/ directory inside PCUT repository (you need to create this directory first).

Empty test, a.k.a. skeleton

Following code must be present (with single alternation mentioned later at multi-source-files tests) in each source code with PCUT tests:

#include <pcut/pcut.h>
PCUT_INIT
PCUT_MAIN()

The meaning of the individual lines is following.

1. First, we need to include the header that defines the PCUT-related macros.
2. Next, PCUT is initialized. This creates some global variables etc. and it must be used before any other PCUT macro.
3. PCUT_MAIN() is the terminating macro - it expands to main() and ensures that the produced binary actually runs all the tests.

Assuming this text is stored in empty.c, following command would compile the code on Linux and produce an empty executable. The output is in Test-Anything-Protocol format and is thus very brief:

$ gcc -o empty -I../include -L.. -lpcut empty.c
$ ./empty
1..0
$ 

Adding a test

Adding a new test is very straightforward: the PCUT_TEST macro handles most of the work, you just append the actual code as it would declare a function (which it actually does, among other things). The code has to be placed between PCUT_INIT and PCUT_MAIN().

PCUT_TEST(empty) {
}

This test does nothing and thus it shall pass: the executable after the modification prints following:

1..1
#> Starting suite Default.
ok 1 empty
#> Finished suite Default (failed 0 of 1).

This TAP output tells that there was one test run and its result was ok. The comments denotes that the test was part of a default test suite.

As was already mentioned the PCUT_TEST actually start a function. As the name of the function is used the parameter, prefixed with pcut_test__. Thus, when adding other tests you need to use unique naming.

Adding assertions

Empty test does not test much. You need to add some assertions (see here for complete list) comparing expectations with the real (computed) output. In our example we would use one specifically targeted at integers: PCUT_ASSERT_INT_EQUALS.

Let's extend our empty test with a simple assertion:

PCUT_TEST(simple_multiplication) {
        PCUT_ASSERT_INT_EQUALS(10, 5 * 2);
}

As this assertion is valid, the output would be the same. But what would happen if the integers are not equal? Let's change the code a bit:

PCUT_TEST(simple_multiplication_failing) {
        PCUT_ASSERT_INT_EQUALS(100, 5 * 2);
}

and recompile. The output would now report that the assertion failed:

1..1
#> Starting suite Default.
not ok 1 simple_multiplication_failing failed
# error: mult.c:6: Expected <100> but got <10> (100 != 5 * 2)
#> Finished suite Default (failed 1 of 1).

As you can see, the output explicitly prints both the computed values as well as corresponding portion of the source code and also informs that the test failed by printing not ok.