Run GoogleTest Tests Using Polyspace Test CMake Package

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 execute GoogleTest tests and collect profiling data. In particular, you use functions in the Polyspace Test CMake package to:

  • Instrument source code for profiling

  • 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

Find the files for this tutorial in the folder polyspaceroot/polyspace/examples/doc_pstest/google_test. Copy these files to a writable location and continue the tutorial. Here, polyspaceroot is the Polyspace installation folder, for instance, /usr/local/Polyspace/R2025a. Copy this folder to a writable location in your file system, such as /usr/data/Getting_Started_Example.

The example folder contains the following:

  • Source file hUserCode.cpp, which contains two functions, return_zero() and tested_function().

  • Header file hUserCode.hpp, which contains declarations of the above functions.

  • Test file hGoogleTest.cpp, which contains tests for the function tested_function().

Create CMakeLists.txt File

In the copied google_test 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(usercode hUserCode.cpp)
target_include_directories(usercode PUBLIC CMAKE_CURRENT_SOURCE_DIR)
pstest_instrument_target(usercode COVERAGE LEVEL mcdc)

# Obtain GoogleTest includes and libraries.
include(FetchContent)
FetchContent_Declare(
    googletest
    URL https://github.com/google/googletest/archive/03597a01ee50ed33e9dfd640b249b4be3799d395.zip
)
# Next line: On Windows, prevent overriding the parent project's compiler and linker settings
set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
FetchContent_MakeAvailable(googletest)
include(GoogleTest)

# Create exe target for GoogleTest tests.
enable_testing()
add_executable(gtest_tests hGoogleTest.cpp)
target_link_libraries(gtest_tests GTest::gtest_main usercode)

# Discover tests and set output file names.
gtest_discover_tests(gtest_tests XML_OUTPUT_DIR out PROPERTIES ENVIRONMENT PSPROFILE_RESULTS_FILE=out/gtest_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, include, add_library, add_executable, target_include_directories, target_link_libraries, enable_testing, add_test, and set_tests_properties.

You also use functions in the FetchContent module to download the GoogleTest includes and libraries. You link your test executable mygtest against the GTest::gtest_main target and automatically add tests from the compiled test executable using the gtest_discover_tests function. See documentation for the GoogleTest and FindGTest modules.

In addition, you also use these functions that are included with the pstest CMake package:

  • pstest_instrument_target function — You use this function to instrument the target usercode 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 gtest_discover_tests function.

Build and Run Tests

Create a build folder named google_test_build at the same level as the google_test 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" ../google_test

CMake downloads GoogleTest includes and libraries, and generates a makefile and other supporting files in the google_test_build folder. Run make to execute the makefile and build the executable mygtest. Then invoke the make command three more times to execute the test, convert, and report targets.

make
make test
make convert
make report

The google_test_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 hUserCode.cpp in a certain format.

For example, you can now open the .pstestr and .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:

  • Both tests in FirstSuite have passed. The single test in SecondSuite has failed.

  • The tests have achieved 88% statement coverage and 75% decision coverage for hUserCode.cpp.

See Also

| |

Topics

External Websites