polyspace-test -monitor

(System Command) Monitor execution of C/C++ xUnit tests and retrieve test and code profiling results

Since R2025a

collapse all in page

Syntax

polyspace-test -monitor [-results-dir <resultsFolder>] [-results-name <resultFile>] [testOptions]-- <testCommand>
polyspace-test -monitor [-results-dir <resultsFolder>] [-results-name <resultFile>] -com serial [-com-timeout <timeInSecs>] [-read-timeout <timeInSecs>] [testOptions] [serialCommOptions] -- <testCommand>
polyspace-test -monitor [-results-dir <resultsFolder>] [-results-name <resultFile>] -com tcpip [-com-timeout <timeInSecs>] [-read-timeout <timeInSecs>] [testOptions] [tcpipCommOptions] -- <testCommand>
polyspace-test -monitor -instrum-dir <instrumFolder> [-results-dir <resultsFolder>] [-results-name <resultFile>] -- <testCommand>
polyspace-test -monitor -instrum-dir <instrumFolder> [-results-dir <resultsFolder>] [-results-name <resultFile>] -com serial [-com-timeout <timeInSecs>] [-read-timeout <timeInSecs>] [testOptions] [serialCommOptions] -- <testCommand>
polyspace-test -monitor -instrum-dir <instrumFolder> [-results-dir <resultsFolder>] [-results-name <resultFile>] -com tcpip [-com-timeout <timeInSecs>] [-read-timeout <timeInSecs>] [testOptions] [tcpipCommOptions] -- <testCommand>

Description

The system command polyspace-test -monitor monitors execution of C/C++ xUnit tests on a host computer or target board, and retrieves test and code profiling results for review in the Polyspace® Platform user interface.

polyspace-test -monitor [-results-dir <resultsFolder>] [-results-name <resultFile>] [testOptions]-- <testCommand> runs the test command or script <testCommand> and generates test results (.pstestr format) in <resultsFolder>. This action allows you to monitor the execution of C/C++ xUnit tests without going through a Polyspace Platform project and retrieve results for viewing in the user interface, for uploading to Polyspace Access™, or for generating reports. To use this action, you must have previously compiled xUnit tests using specific compilation options.

example

polyspace-test -monitor [-results-dir <resultsFolder>] [-results-name <resultFile>] -com serial [-com-timeout <timeInSecs>] [-read-timeout <timeInSecs>] [testOptions] [serialCommOptions] -- <testCommand> runs the test command or script <testCommand> on a target board, retrieves the results and converts them to a form suitable for review and report generation. The data transfer to and from the target board is done using serial communication protocols.

polyspace-test -monitor [-results-dir <resultsFolder>] [-results-name <resultFile>] -com tcpip [-com-timeout <timeInSecs>] [-read-timeout <timeInSecs>] [testOptions] [tcpipCommOptions] -- <testCommand> runs the test command or script <testCommand> on a target board, retrieves the results and converts them to a form suitable for review and report generation. The data transfer to and from the target board is done using TCP/IP communication protocols.

polyspace-test -monitor -instrum-dir <instrumFolder> [-results-dir <resultsFolder>] [-results-name <resultFile>] -- <testCommand> runs the test command or script <testCommand> and generates test (.pstestr format) and code profiling results (.psprof format). This action allows you to monitor the execution of C/C++ xUnit tests for both testing and code profiling without going through a Polyspace Platform project. To use this action, you must have previously compiled xUnit tests using specific compilation options and instrumented your source code for code profiling.

example

polyspace-test -monitor -instrum-dir <instrumFolder> [-results-dir <resultsFolder>] [-results-name <resultFile>] -com serial [-com-timeout <timeInSecs>] [-read-timeout <timeInSecs>] [testOptions] [serialCommOptions] -- <testCommand> runs the test command or script <testCommand> on a target board, retrieves the test and code profiling results, and converts them to a form suitable for review and report generation. The data transfer to and from the target board is done using serial communication protocols.

polyspace-test -monitor -instrum-dir <instrumFolder> [-results-dir <resultsFolder>] [-results-name <resultFile>] -com tcpip [-com-timeout <timeInSecs>] [-read-timeout <timeInSecs>] [testOptions] [tcpipCommOptions] -- <testCommand> runs the test command or script <testCommand> on a target board, retrieves the test and code profiling results, and converts them to a form suitable for review and report generation. The data transfer to and from the target board is done using TCP/IP communication protocols.

Examples

collapse all

This example shows how to compile your sources and xUnit tests into a test executable and monitor the execution of the tests using the polyspace-test -monitor command.

In this example, you will use the sources and tests in polyspaceroot\polyspace\examples\doc_pstest\coverage_data_collection. Here, polyspaceroot is the Polyspace installation folder. For more information, see Installation Folder.

Before running the example, make sure to identify all files needed for compiling xUnit tests and collecting coverage data after test execution. For more information, see Set Up C/C++ Testing and Code Profiling Using Self-Managed Builds.

  1. Build your sources and xUnit tests, along with the files containing the xUnit API definitions. When building the code, define the macro PST_MONITOR_MODE using a compilation option. This macro ensures that the data from test execution is produced in a specific format.

    For instance, if you are using the GCC compiler for compilation on Windows®, on the command line, navigate to the example folder and enter the following:

    gcc src\example.c tests\test.c <PSTUNIT_SOURCE> -I <PSTUNIT_INCLUDE> -D PST_MONITOR_MODE -o testRunner
    For more information on <PSTUNIT_SOURCE> and other files available with a Polyspace Test™ installation, see Set Up C/C++ Testing and Code Profiling Using Self-Managed Builds.

  2. Monitor the execution of the test executable created in the previous step by using the polyspace-test -monitor command. For instance, if the test executable is named testRunner.exe, enter the following at the command line:

    polyspace-test -monitor -results-dir resultsFolder -- testRunner.exe
    This command generates a .pstestr file containing the test execution results in the folder resultsFolder. You can open the results in the Polyspace Platform user interface, upload the results to Polyspace Access or generate reports from the test results.

This example shows how to instrument your sources for code profiling, compile your sources and tests, and monitor the execution of the tests using the polyspace-test -monitor command.

In this example, you will use the sources and tests in polyspaceroot\polyspace\examples\doc_pstest\coverage_data_collection. Here, polyspaceroot is the Polyspace installation folder. For more information, see Installation Folder.

Before running the example, make sure to identify all files needed for compiling xUnit tests and collecting coverage data after test execution. For more information, see Set Up C/C++ Testing and Code Profiling Using Self-Managed Builds.

  1. Instrument the source files for code profiling.

    For instance, for GCC compilation on Windows, enter the following on the command line:

    polyspace-code-profiler -instrument -instrum-dir instrumResults -cov-metric-level decision -- gcc -c src/example.c

  2. Compile the tests and files containing the xUnit API definitions.

    For instance, if you are using the GCC compiler for compilation on Windows, on the command line, navigate to the example folder and enter the following:

    gcc -c tests\test.c <PSTUNIT_SOURCE> <PSPROFILE_SOURCE> -I <PSTUNIT_INCLUDE> -I <PSPROFILE_INCLUDE> -D PST_MONITOR_MODE_WITH_PROFILING
    For more information on <PSTUNIT_SOURCE> and other files available with a Polyspace Test installation, see Set Up C/C++ Testing and Code Profiling Using Self-Managed Builds.

  3. Link the binaries created from the tests and the instrumented sources in the previous steps.

    For instance, for GCC compilation on Windows, enter the following on the command line:

    gcc example.o test.o pstunit.o psprofile_internal.o <PSPROFILELIB> -o testRunner
    For more information on the profiling library <PSPROFILELIB>, see Set Up C/C++ Testing and Code Profiling Using Self-Managed Builds.

  4. Monitor the execution of the test executable created in the previous step by using the polyspace-test -monitor command. For instance, if the test executable is named testRunner.exe, enter the following at the command line:

    polyspace-test -monitor -results-dir resultsFolder -instrum-dir instrumResults -- testRunner.exe
    This command generates a .pstestr file containing the test execution results and a .psprof file containing the code profiling results. You can open the results in the Polyspace Platform user interface, upload the results to Polyspace Access, or generate reports from the results.

Input Arguments

collapse all

Path to folder where code instrumentation results are stored.

You instrument code using the command polyspace-code-profiler -instrument. When you instrument code, the instrumentation results are stored in the folder specified as the argument of the option -instrum-dir used with the polyspace-code-profiler command. For more information, see polyspace-code-profiler.

Path to folder where the test and code profiling results are stored.

Name of file for storing test results (.pstestr file) and code profiling results (.psprof file). The default name is pstest_results.pstestr.

Time allowed for completing connection to a target board. The default is 10 seconds.

Time allowed for receiving data from a target board. The default is 60 seconds.

If the test or coverage results do not appear as expected, try increasing the value of this option.

Options to explicitly describe the behavior of the test command.

OptionDescription
-working-dir <folderPath>

Current working folder for the test command being run.

Use this option if the current working folder for the test command is different from the folder where you run the polyspace-test command.

-return-code-from-app

Option to specify that polyspace-test must return:

  • The return code of the test command when the test command succeeds.

  • The value of the option -return-code-fail-value when the test command fails.

-return-code-fail-value <failValue>

Return code that polyspace-test must return to indicate failures. The default value is 253.

-compilation-working-dir <folderPath>

Path from which the compilation command was run when compiling sources and tests to create the test command (executable).

Using this option allows you to navigate from a test result in the user interface to the location of the code under test in the source code. If you do not specify this option, the command generates a valid .pstestr file that you can open in the user interface. But you cannot navigate from the test results to the source code.

-add-environment-info <filePath>

Path to JSON file specifying environment information to be associated with the result. Use this option if you want to save environment information in your result reports.

The JSON file has the following structure: 

{
    "BuildConfiguration": "<nameOfConfiguration>",
    "ConfigurationDescription": "<descriptionOfConfiguration>",
    "Toolchain": "<nameOfToolchain>",
    "Board": "<nameOfBoard>"
}
You can set these values as desired to reflect your testing and profiling configuration.

Note that if you generate a report using a Polyspace Platform project, the same values are automatically populated from your project configuration and you do not require to specify an additional file for the environment information. For more information on the values expected for the JSON keys, see Structure of HTML Reports Generated from C/C++ Test Results.

Example: -add-environment-info env_info.json

Options for serial communication with the target board. You can use these options only if you specify the option -com serial when running the polyspace-test -monitor command.

OptionDescription
-port <portName>

Port name for serial communication.

The default is COM3 on Windows and /dev/ttyS0 on Linux®.

-baud-rate <commSpeed>

Speed at which data is transferred over a serial connection, in bits per second.

The default is 115200.

-parity <evenOrOdd>

Parity used for serial communication.

The allowed values are none (default), even or odd.

Options for TCP/IP communication with the target board. You can use these options only if you specify the option -com tcpip when running the polyspace-test -monitor command.

OptionDescription
-ip-addr <hostNameOrIPAddress>

Remote host name or IP address used for TCP/IP communication.

The default is localhost.

-ip-port <portNumber>

Port number used for TCP/IP communication.

The default is 17725.

Test command to be monitored. The command can be a test executable, or a script that performs other tasks besides executing the tests, for instance, flash to a target board.

Example: testRunner.exe

Example: "C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin\STM32_Programmer_CLI.exe" --connect port=swd --erase all --download unittests.hex --go

Version History

Introduced in R2025a

See Also

Topics