Calculate Code Coverage of xUnit API-Based Tests Using CMake

CMake is a third-party, open source tool for build process management that allows you to specify the build instructions for your code base in a platform and toolchain independent CMake language. When using CMake, you:

1. Create a CMakeLists.txt file that contains the build instructions in the CMake language.

2. Invoke the cmake command that uses the CMakeLists.txt file to generate standard build files. These include makefile and Ninja, as well as Microsoft^® Visual Studio^® and Xcode project builds.

To learn more about CMake, see the CMake Tutorial.

Polyspace^® Test™ includes a CMake package that supplements the standard CMake API with additional variables, targets, and functions. This example shows how to use this package to:

• Instrument source code for profiling

• Link source and test targets to the pstunit target to create an executable

• Convert code profiling results to standard Polyspace Test formats

• Generate XML and HTML reports from code profiling results

Prerequisites

To use the Polyspace Test CMake package, you must have CMake version 13.0.0 or higher.

In this example, you instruct CMake to generate a makefile. To run this example, you must have make installed on your system.

Alternatively, you can instruct CMake generate an IDE build system, for example one that uses Microsoft Visual Studio. For more information on how to modify the cmake command in this example, refer to the CMake documentation.

Example Files

The files used for this example are available in the folder polyspaceroot/polyspace/examples/pstest/Getting_Started_Example. Here, polyspaceroot is the Polyspace Test installation folder, for example /usr/local/Polyspace/R2025a. Copy this folder to a writable location in your file system, such as /usr/data/Getting_Started_Example.

Create CMakeLists.txt File

In the copied Getting_Started_Example folder, create a CMakeLists.txt file that contains these commands:

# Find pstest CMake package.
cmake_minimum_required(VERSION 3.13.0)
project(MyProject)
find_package(pstest PATHS "<polyspaceroot>/polyspace/pstest/pstunit/cmake")

# Create lib target for source code. Instrument this target for MC/DC coverage.
add_library(ecocar sources/utils.c)
target_include_directories(ecocar PUBLIC includes)
pstest_instrument_target(ecocar COVERAGE LEVEL mcdc)

# Create exe target for pstunit tests.
enable_testing()
add_executable(mypstest tests/test.c)
target_link_libraries(mypstest pstest::pstest_c ecocar)

# Add test and set output file names.
set(CMAKE_CTEST_ARGUMENTS "-O;out/pstest_results.mrf;--verbose")
add_test(NAME mypstest COMMAND mypstest -format mrf)
set_tests_properties(mypstest PROPERTIES ENVIRONMENT PSPROFILE_RESULTS_FILE=out/pstest_coverage.bin)

# Create targets for result and report generation.
pstest_add_convert_target(convert RESULTS_DIRS out CONVERTED_RESULTS_DIR results)
pstest_add_report_target(report RESULTS_DIRS results REPORTS_DIR reports HTML XML)

In this file, you use the standard CMake functions cmake_minimum_required, project, set, find_package, add_library, add_executable, target_include_directories, target_link_libraries, enable_testing, add_test, and set_tests_properties.

You also use these targets and functions that are included with the pstest CMake package:

• pstest::pstest_c target — You link the test executable mypstest against this target

• pstest_instrument_target function — You use this function to instrument the target ecocar for your source code

• pstest_add_convert_target function — You use this function to create a target for converting test and code profiling results to the standard Polyspace Test format

• pstest_add_report_target function — You use this function to create a target for generating reports from test and code profiling results

On Windows^® platform, you must also add the location of the Polyspace Test run-time library for code coverage calculation polyspaceroot/polyspace/psprofile/lib/arch to the PATH environment variable. For example, you make this assignment inside the set_tests_properties function.

Build and Run Tests

Create a build folder named Getting_Started_Example_build at the same level as the Getting_Started_Example folder. From the build folder, run the cmake command to generate a build system for your source and test files. Use the -G option to specify the CMake generator. For example, on Linux^® platform, run this command at the shell:

cmake -G "Unix Makefiles" ../Getting_Started_Example

CMake generates a makefile and other supporting files in the Getting_Started_Example_build folder. Run make to execute the makefile and build the executable mypstest. Then invoke the make command three more times to execute the test, convert, and report targets.

make
make test
make convert
make report

The Getting_Started_Example_build folder now contains the subfolders out, results, and reports. Each of these subfolders contains test execution and code coverage data for the source file utils.c in a certain format.

For example, you can now open the .psprof files in the results subfolder using the Polyspace Platform user interface. Alternately, you can inspect the XML and HTML files in the reports subfolder in a web browser.

In particular, note that the tests have achieved 95% statement coverage and 25% MC/DC coverage for utils.c.