Debug Test Failures from Polyspace Platform User Interface

You can author and run C/C++ tests using projects in the Polyspace Platform user interface. To diagnose test failures, you can run the same tests in debug mode and open a debugger for stepping through the test execution. This topic shows how to diagnose test failures by stepping through tests in a debugger.

Supported Debuggers

You can only attach the following debug tools to a Polyspace® Platform project for debugging test failures.

Operating SystemSupported Debugger
Windows®

The debugger used depends on your choice of host compiler in your Polyspace Platform settings.

  • Microsoft® Visual Studio® IDE, if you specify a Microsoft Visual C++® compiler as host compiler.

  • Visual Studio Code debugger, if you specify a MinGW compiler as host compiler.

For more information on host compilers, see Specify C/C++ Compilers for Testing in Polyspace Platform User Interface.

macOS

Visual Studio Code debugger if configured, otherwise LLDB.

Linux®

Visual Studio Code debugger if configured, otherwise GNU® Data Display Debugger (DDD).

To use the Visual Studio Code debugger, you must install the Visual Studio Code extension, MATLAB Coder Interface for Visual Studio Code Debugging. To install the extension:

  1. In Visual Studio Code, select View > Extensions.

  2. On the EXTENSIONS pane, click the ellipsis on the upper right and select Install from VSIX.

  3. Navigate to polyspaceroot\toolbox\targetframework\supportpackage\vscodedebug\extension and select matlab-coder-interface-vscode-debugging.vsix. Here, polyspaceroot is the Polyspace installation folder, for instance, C:\Program Files\Polyspace\R2026a.

The debuggers listed above are for debugging tests that execute on the host. To debug tests that execute on a target, you can use the Lauterbach TRACE32 Instruction Set Simulator (ISS) with the DebugIOTool API. For more information, see Adapt Polyspace Test Target Package for TRACE32 Instruction Set Simulator.

Build and Run Tests in Debug Mode

Suppose that one or more tests in your project failed. You can debug the test failures by executing the tests in debug mode. During test execution in debug mode, the test code opens in a debugger allowing you to step through the test. You can debug all kinds of tests: graphical tests, tests written using the C/C++ xUnit API or tests written using an external API such as GoogleTest.

To execute tests in debug mode:

  1. On the Polyspace Platform toolstrip, select Debug.

  2. Select Build Project.

    Your test code is instrumented for execution in debug mode, and the sources and tests are built together into a test executable.

    If you run into errors during build, see Compilers and Debugging.

  3. On the Projects pane, right-click the test that you want to debug and select Run Test.

    The test code opens in the debugger in a function that is auto-generated during test build and has a name such as pst_host_main_action(). You can start from this function and step into your test code and function under test.

Step Through Function in Debugger

In your debugger, continue from the main test execution function to the next breakpoint in the function. You can also open a file in the debugger and place your own breakpoints. To place a breakpoint in a file, make sure you open the file from the already open instance of the debugger instead of a new instance.

Once you understand the cause of the failure, you can close the debugger or use the Stop button in the Polyspace Platform toolstrip to kill the debugger.

The following sections outline the debugging steps for some of the supported debuggers.

Microsoft Visual Studio Debugger

If you use the Microsoft Visual Studio IDE as your debugger, when you start debugging, the IDE opens at a function such as pst_host_main_action().

  1. Click the Continue button button or select Debug > Continue to reach the next breakpoint.

    This breakpoint occurs in the test file and points to the beginning of your test body (PST_TEST_BODY or PST_SIMPLE_TEST_BODY).

  2. From this point onwards, you can place breakpoints, continue to the newly placed breakpoint and evaluate values of variables in the code. You can continue this process until you understand the reason for the test failure.

    For instance, to inspect the function under test starting from the test file:

    1. Find the call to the function under test by searching with the function name or by another means.

      If you are debugging a graphical test, the test body with the final breakpoint contains a PST_CALL_BLOCK macro. Search with the macro argument name to find the corresponding PST_BLOCK macro that contains the function call.

    2. Place a breakpoint at the call to the function under test, and continue to this breakpoint using the Continue button button.

    3. Click the Step into button button or select Debug > Step Into to step into the function under test and continue the inspection. At each stage, you can inspect values of variables by hovering over them.

  3. Close the Visual Studio to resume test execution.

GNU Data Display Debugger

If you use the GNU Data Display Debugger (DDD) as your debugger, when you start debugging, the debugger opens at a function such as pst_host_main_action().

  1. Click the Cont button in the palette on the right or select Program > Continue to reach the next breakpoint.

    This breakpoint occurs in the test file and points to the beginning of your test body (PST_TEST_BODY or PST_SIMPLE_TEST_BODY).

  2. From this point onwards, you can place breakpoints, continue to the newly placed breakpoint and evaluate values of variables in the code. You can continue this process until you understand the reason for the test failure.

    For instance, to inspect the function under test starting from the test file:

    1. Find the call to the function under test by searching with the function name or another means.

      If you are debugging a graphical test, the test body with the final breakpoint contains a PST_CALL_BLOCK macro. Search with the macro argument name to find the corresponding PST_BLOCK macro that contains the function call.

    2. Place a breakpoint at the call to the function under test by right-clicking the line and selecting Set breakpoint. Continue to this breakpoint using the Cont button in the palette on the right.

    3. Click the Step button in the palette on the right or select Program > Step to step into the function under test and continue the inspection. At each stage, you can inspect values of variables by selecting items such as Data > Display Local Variables or Data > Display Arguments.

  3. Click the Cont button in the palette on the right or select Program > Continue to close the Data Display Debugger and resume test execution.

Visual Studio Code Debugger (Windows)

If you use Visual Studio Code as your debugger on Windows, when you start debugging, the debugger opens at a function such as PST_REGFCN_CALL.

  1. Click the Continue button a few times to reach the breakpoint at the call to the function test_case_fcn(). This call appears inside another function pst_run_test_case_function().

  2. Click the Step into button button to step into the function test_case_fcn() and thereby open your test file.

  3. From this point onwards, you can place breakpoints, continue to the newly placed breakpoint and evaluate values of variables in the code. You can continue this process until you understand the reason for the test failure.

    For instance, to inspect the function under test starting from the test file:

    1. Find the call to the function under test by searching with the function name or by another means.

      If you are debugging a graphical test, the test body contains a PST_CALL_BLOCK macro. Search with the macro argument name to find the corresponding PST_BLOCK macro that contains the function call.

    2. Place a breakpoint at the call to the function under test, and continue to this breakpoint using the Continue button .

    3. Click the Step into button button to step into the function under test and continue the inspection. At each stage, you can inspect values of variables by hovering over them.

  4. Close Visual Studio Code to resume test execution.

Note that in Linux and macOS, the final breakpoint appears in the test file itself. So, you can click the Continue button in the debugger till you reach the test file, and then start placing your own breakpoints.

See Also

Topics