Convert GoogleTest Tests to Polyspace Test xUnit Tests

In the Polyspace Platform user interface, you can run C/C++ tests written using the Polyspace® Test™ xUnit framework or an external framework such as GoogleTest. You can review the test results directly in the user interface and collect code coverage with respect to these tests. In addition, if you have existing tests authored using GoogleTest, you can also migrate them to Polyspace Test xUnit tests. Migrating to xUnit tests unlocks additional features in Polyspace Platform such as ability to execute individual tests, on-target execution, and links from coverage results to test information.

This topic shows how to migrate existing tests authored using GoogleTest to the Polyspace Test xUnit framework.

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, C:\Program Files\Polyspace\R2026a.

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().

To run tests authored using the GoogleTest framework, you also need GoogleTest includes and libraries. You can install all required files from the GoogleTest repository. In this topic, the term googleTestInstallFolder refers to the main folder containing GoogleTest files. For instance, if you run this command:

git clone https://github.com/google/googletest.git -b v1.13.0
The folder from which you run the command will contain a googletests subfolder. In this case, googleTestInstallFolder is the full path to the googletests subfolder.

Build and Run GoogleTest Tests in Polyspace Platform Project

Before converting GoogleTest tests to xUnit tests, you must run the original tests to completion using a Polyspace Platform project. The converter leverages information from the project, in particular, the project build configuration, to identify GoogleTest macros and convert them to equivalent Polyspace Test macros.

In brief, the steps to run GoogleTest tests from a Polyspace Platform project are as follows:

  1. Create a new project and add source files to the project.

  2. Right-click the root node of the project and select Add External Test Files or Add External Test Folders to add GoogleTest tests to the project.

  3. Open the project configuration. On the Build tab, set appropriate options on the External Tests node (in addition to other options you might need to set).

  4. Build the tests in the project.

For more details on these steps, see Run GoogleTest Tests Using Polyspace Platform Projects.

Convert GoogleTest Tests in Project

Once the GoogleTest tests build successfully, you can convert the tests in the project.

  1. Open a terminal and navigate to the project file (.psprjx file) location.

  2. Enter the following command to convert the tests in the project:

    polyspace-test -convert-external-tests -project projectName.psprjx
    Here, projectName is the name of the project file.

    This command attempts to convert all GoogleTest tests in the project to Polyspace Test xUnit tests. After conversion, for each GoogleTest test file testFile.cpp, you see an equivalent Polyspace Test xUnit test file testFile.pstest.cpp in the same folder as the original test. For more information on the command syntax, enter:

    polyspace-test -convert-external-tests -help

    If a macro cannot be automatically converted, the command prints the location of the macro so that you can convert these macros manually later. At the end of the conversion log, you see a message such as the following:

    Analyzed files: 1
Converted files: 1
Files skipped because of errors: 0
Files not requiring conversion: 0
    You can use this information to check if all files in the project were analyzed and converted, or if some files were skipped because of compilation errors.

  3. Add the converted tests to the Polyspace Platform project (and optionally remove the GoogleTest tests). When you build and run the tests, you should see the same results as the original GoogleTest tests, with additional capabilities such as ability to execute a single test, and so on.

See Also

Topics