Run C/C++ Tests on Target Using Self-Managed Builds

R2026b

In the context of test execution in Polyspace® Test™, the word target refers to embedded systems with specific processor architecture, cross-compilation tools, and channels for communication with a host computer.

The steps below show how to leverage existing toolchain setup for on-target execution to run tests authored using the Polyspace Test C/C++ xUnit API.

Prerequisites

This topic assumes that:

Overview

You can retrieve test results from the target using one of two modes:

 Monitor ModeManual Conversion Mode
Result conversionAutomatic — polyspace-test -monitor retrieves and converts results during execution.Manual — You retrieve the .mrf output from the target and convert it on the host using polyspace-test -convert.
Configuration macroPST_MONITOR_MODE 1PST_EMBEDDED_MODE 1
Communication requirementRequires a live communication channel (serial port, TCP) between host and target during execution.No live connection required — collect output after execution completes.
Code profilingAlso produces code profiling results (.psprof) if you enable profiling in the same configuration. See Collect Test and Code Profiling Results from Target Using Self-Managed Builds.Captures test results only. To also collect code profiling data, perform a separate execution with a profiling-specific configuration. See Collect Test and Code Profiling Results from Target Using Self-Managed Builds.

If you can stream data from your target through a serial or TCP/IP port, you can use either mode. The monitor mode is recommended as it automates the retrieval and conversion of test results. If your port is not supported for the monitor mode, use the manual conversion mode. For more information on the ports supported by monitor mode, see polyspace-test -monitor.

Alternatively, you can add C/C++ xUnit tests to a Polyspace Platform project and execute the tests using this project. In this workflow, once you register your target, the test execution on target and retrieval of test results are managed entirely by the test execution framework in Polyspace Test. You do not have to manually perform the test build, communication with target, retrieval of test results, or any of the subsequent conversions. For more information on the completely managed workflow, see Run C/C++ Tests on Target in Polyspace Platform User Interface.

Monitor Mode

In monitor mode, polyspace-test -monitor launches the test executable on the target, streams the test output through a communication channel (serial or TCP), and automatically converts the results into a .pstestr file.

Configure Test Execution

Define a configuration header file to enable monitor mode:

  1. In a header file pstest_config.h, set these configuration macros:

    /* Enable monitor mode for test execution */
#define PST_MONITOR_MODE 1
/* Disable execution time calculation, otherwise requires timer function definition */
#define PST_ENABLE_EXECUTION_TIME   0

extern void uart_write(const char * str, unsigned long len);

/* Transfer string of specific length */
#define PST_WRITE(str, len) uart_write(str, len)

    The macro PST_MONITOR_MODE configures the test executable to produce output in a machine-readable format with newline delimiters, suitable for streaming through a communication channel. The macro PST_WRITE maps to a function that sends data through the communication channel. For more information on the configuration macros, see Configuration Macros in Polyspace Test API for C/C++ Code.

  2. Define the implementation of the function mapped to the macro PST_WRITE in a source file.

    For example, this source file defines the function uart_write() to send a string of characters through the UART interface using the function HAL_UART_Transmit() from the STM32 HAL library:

    #include "stm32746g_discovery.h"
extern UART_HandleTypeDef huart1;

void uart_write(const char * str, unsigned long len) {
      HAL_UART_Transmit(&huart1, (const uint8_t*)str, len, HAL_MAX_DELAY);
}

Build Tests on Host Using Cross-Compiler

Build your tests and create a test executable by using your cross-compiler. Define the macro PST_USER_CONFIG during build so that the macros in the configuration file pstest_config.h get used during build. For more information on the macro PST_USER_CONFIG, see Configuration Macros in Polyspace Test API for C/C++ Code.

For example, to cross-compile using the GNU® toolchain for an Arm target, use this command at the command line:

arm-none-eabi-gcc  src/example.c tests/mytest.c <PSTEST_SRC> -D PST_USER_CONFIG -I <PSTEST_INC>
In this command:

  • <PSTEST_SRC> is the path to the file <polyspaceroot>\polyspace\pstest\pstunit\src\pstest.c containing definitions of xUnit API macros.

  • <PSTEST_INC> is the path to the folder <polyspaceroot>\polyspace\pstest\pstunit\include containing the xUnit API headers.

Here, <polyspaceroot> is the Polyspace installation folder, for instance, C:\Program Files\Polyspace\R2026b.

Run Tests on Target

After creating the test executable on the host, use polyspace-test -monitor to run the executable on the target, stream the results, and convert them automatically.

For instance, suppose that you are running tests in Windows® on an STM32 board using the STM32_Programmer_CLI.exe command:

"C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin\STM32_Programmer_CLI.exe" --connect port=swd --erase all --download unittests.hex --go
You can monitor the execution of this command as follows:
polyspace-test -monitor -com serial -read-timeout 15 -com-timeout 30 -port COM6 -baud-rate 115200 -parity none -results-dir resultsFolder -- "C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin\STM32_Programmer_CLI.exe" --connect port=swd --erase all --download unittests.hex --go
After retrieving the test results, the polyspace-test -monitor command converts the results into a .pstestr file and stores it in the folder specified for the option -results-dir.

For more information, see polyspace-test -monitor.

Review Results

Open the .pstestr file from the results folder and review the results using one of these methods:

Manual Conversion Mode

In manual conversion mode, you run the test executable on the target, collect the machine-readable output (.mrf file), and convert it to a .pstestr file on the host using polyspace-test -convert. This mode does not require a live communication channel during execution.

Configure Test Execution

Define a configuration header file to enable embedded mode:

  1. In a header file pstest_config.h, set these configuration macros:

    /* Enable embedded mode for compact machine-readable output */
#define PST_EMBEDDED_MODE 1
/* Disable execution time calculation, otherwise requires timer function definition */
#define PST_ENABLE_EXECUTION_TIME   0

extern void pst_write(const char * str, unsigned long len);

/* Transfer string of specific length */
#define PST_WRITE(str, len) pst_write(str, len)

    The macro PST_EMBEDDED_MODE configures the test executable to produce compact machine-readable output. The macro PST_WRITE maps to a function that stores or sends the output data. For more information on the configuration macros, see Configuration Macros in Polyspace Test API for C/C++ Code.

  2. Define the implementation of the function mapped to the macro PST_WRITE in a source file.

    For example, this source file defines the function pst_write() to store test output in a buffer that is written to a file after execution completes:

    #include <stdio.h>
#include <string.h>

static unsigned char outBuffer[16384];
static unsigned int outIndex = 0;

void pst_write(const char * str, unsigned long len) {
    if ((outIndex + len) <= sizeof(outBuffer)) {
        memcpy(&outBuffer[outIndex], str, len);
        outIndex += len;
    }
}

void save_results(const char * filename) {
    FILE *f = fopen(filename, "wb");
    if (f) {
        fwrite(outBuffer, 1, outIndex, f);
        fclose(f);
    }
}

    The exact implementation depends on your target. On targets with file system access, you can write directly to a file. On targets without file system access, you can store the output in a buffer and retrieve it through a debug probe or other mechanism after execution completes.

Build Tests on Host Using Cross-Compiler

Build your tests and create a test executable by using your cross-compiler. Define the macro PST_USER_CONFIG during build so that the macros in the configuration file pstest_config.h get used during build. For more information on the macro PST_USER_CONFIG, see Configuration Macros in Polyspace Test API for C/C++ Code.

For example, to cross-compile using the GNU toolchain for an Arm target, use this command at the command line:

arm-none-eabi-gcc  src/example.c tests/mytest.c <PSTEST_SRC> -D PST_USER_CONFIG -I <PSTEST_INC>
In this command:

  • <PSTEST_SRC> is the path to the file <polyspaceroot>\polyspace\pstest\pstunit\src\pstest.c containing definitions of xUnit API macros.

  • <PSTEST_INC> is the path to the folder <polyspaceroot>\polyspace\pstest\pstunit\include containing the xUnit API headers.

Here, <polyspaceroot> is the Polyspace installation folder, for instance, C:\Program Files\Polyspace\R2026b.

Run Tests and Retrieve Results

After creating the test executable on the host, run it on the target using your regular methods of code execution. For instance, if you use options in an IDE to transfer your compiled code to the target board, you can continue to use the same method to transfer the test executable.

Collect the test output from the target and save it as an .mrf file. The method for collecting the output depends on your target:

  • If you use a terminal emulator program such as Tera Term or PuTTY, specify in the program settings that command execution output must be stored in a file with the .mrf extension.

  • If your target does not support running commands at a command-line interface, collect the binary output of the test executable through a debug probe or other mechanism and save it as an .mrf file on the host computer.

Convert and Review Results

Convert the .mrf file into a .pstestr file by entering this command at the command line:

polyspace-test -convert -results-dir resultsFolder results.mrf
In this command:

  • resultsFolder is the folder where Polyspace stores the output .pstestr file.

  • results.mrf is the .mrf file collected from the target.

Review the results using one of these methods:

See Also

Topics

External Websites