Write C/C++ Unit Tests Using Polyspace Test xUnit API and Run Tests at Command Line

This example shows how to write and execute a C/C++ test using the Polyspace® Test™ xUnit-based API. The test calls a function with input parameter values and verifies if the function returns an expected value.

The Polyspace Test xUnit API consists of macros that you can invoke in C/C++ code to:

  • Specify test configurations or fixtures (for instance, test setup and teardown).

  • Encapsulate a test body.

  • Specify test assessments.

And so on. In addition to the macros available with C code, the API for C++ code also provides test fixture classes that you can instantiate for each test.

Example Files

To follow this tutorial, you can copy code into .c files as stated in the tutorial.

Alternatively, files used in this tutorial are provided in the folder polyspaceroot\polyspace\examples\doc_pstest\getting_started. Copy these files to a writable location and continue the tutorial. Here, polyspaceroot is the Polyspace installation folder, for instance, C:\Program Files\Polyspace\R2026a.

Write Test Case

In this example, you test the function saturate_and_cache in the file algo.c with the input value of 5 and check if the function returns the expected value of 5.

The following code shows a simple test written using the xUnit API. To run the test, save the code in a file test.c.

#include <pstunit.h>

/* Tested function. */
extern int saturate_and_cache(int value);

PST_SIMPLE_TEST(test_value_not_saturated) {
    int value_not_saturated = 5;
    int actual_value;
    
    actual_value = saturate_and_cache(value_not_saturated);
    PST_VERIFY_EQ_INT(actual_value, value_not_saturated);
}

#ifndef PSTEST_BUILD
int main(int argc, char *argv[]) {
    PST_ADD_SIMPLE_TEST(test_value_not_saturated);
    return PST_MAIN(argc, argv);
}
#endif

The test case consists of these macros from the Polyspace Test xUnit API:

  • PST_SIMPLE_TEST – This macro allows you to define test code for the new test test_value_not_saturated.

  • PST_VERIFY_EQ_INT – This macro checks if its first integer argument is equal to its second argument.

  • PST_ADD_SIMPLE_TEST – This macro adds a test to the list of registered tests.

  • PST_MAIN – This macro represents the Polyspace Test main function that runs the registered tests.

  • PSTEST_BUILD – This macro allows building the test from a project in the Polyspace Platform user interface. If you do not enclose the main function in a preprocessor directive #ifndef PSTEST_BUILD #endif, you see a multiple main error during project build. For more information, see Add C/C++ xUnit Tests to Projects in Polyspace Platform User Interface.

For more information on macros available with the Polyspace Test API, see:

Generate Test Case Executable

To generate the test case executable, build your source files (algo.c and saturate.c) along with:

  • The file test.c that contains your test.

  • The file pstunit.c that comes with Polyspace Test. The file is in the folder polyspaceroot\polyspace\pstest\pstunit\src. Here, polyspaceroot is the Polyspace installation folder, for instance, C:\Program Files\Polyspace\R2026a.

Add the folder polyspaceroot\polyspace\pstest\pstunit\include as an include folder when building the code. For instance, if you are using a GCC compiler, run this command:

gcc algo.c saturate.c test.c polyspaceroot\polyspace\pstest\pstunit\src\pstunit.c -I . -I polyspaceroot\polyspace\pstest\pstunit\include -o testrunner
This command generates an executable named testrunner, which can execute the tests.

Run Test Case Executable

Run the executable generated in the previous step. For instance, if you ran the previous GCC command, enter the following:

testrunner.exe
(or ./testrunner in Linux®).

You see this log with passing test results:

| Running tests   |            |
|-----------------|------------|
| Running         | suite      | pst_default_suite
|-----------------|------------|
| Running         | test       | test_value_not_saturated
|            PASS | test       | test_value_not_saturated
|-----------------|------------|
|            PASS | suite      | pst_default_suite

|        |  Total | Passed | Failed | Incomplete
|--------|--------|--------|--------|------------
| Suites |      1 |      1 |      0 |          0
|  Tests |      1 |      1 |      0 |          0

You can modify the test results format by appending flags to the executable. For instance, if you want to print a brief summary with details of failing tests only, append the flag -format brief to the executable. To see all available flags, enter:

testrunner.exe -h

For more information on the results format, see Results Format of Tests Written Using Polyspace Test API.

Further Exploration

In this example, you registered the test directly in the main function. Instead, you can register the tests separately and call a registered group of tests from the main function. That way, you can continue adding new tests to the group without modifying the main function.

You can use the macro PST_REGFCN to register a group of tests and another macro PST_REGFCN_CALL to call them from the main function. In the previous example, replace:

int main(int argc, char *argv[]) {
    PST_ADD_SIMPLE_TEST(test_value_not_saturated);
    return PST_MAIN(argc, argv);
}
With:

PST_REGFCN(myRegFcn) {
    PST_ADD_SIMPLE_TEST(test_value_not_saturated);
}

int main(int argc, char *argv[]) {
    PST_REGFCN_CALL(myRegFcn);
    return PST_MAIN(argc, argv);
}

See Also

Topics