Run C/C++ Tests on Target Using Existing Toolchain Setup

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.

Overview

If you already have an existing toolchain setup to run C/C++ code on a target, you can adapt your setup to execute tests authored using the Polyspace Test xUnit API. The workflow that you follow is dependent on the target, but there are certain key steps that are common to all workflows. This topic outlines the key steps of the workflow for running tests on target using an existing toolchain setup.

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.

Author Tests

Author tests for your source by using the xUnit API:

Write tests that invoke functions in your source code and assess return values and global variables following the function invocations. See Write C/C++ Unit Tests Using Polyspace Test xUnit API and Run Tests at Command Line.
Register the tests.
For examples, register a test myTest in a suite myTestSuite using the following syntax:
```
PST_REGFCN(myRegFcn) {
   PST_ADD_TEST(myTestSuite, myTest);
}
```
In C++, you do not need to explicitly register the tests. For more information, see Write Test Fixtures Using Polyspace Test C++ API.
In your main() function, invoke previously registered tests by using the PST_REGFCN_CALL macro.
For example, invoke the test registration function myRegFcn from the previous step in your main() function using the following syntax:
```
int main(void) {
   PST_REGFCN_CALL(myRegFcn);
   PST_MAIN(0, NULL);
}
```

Configure Test Execution

Define a configuration file to configure certain aspects of test execution:

In a header file pstunit_config.h, set appropriate configuration macros to modify the default test execution. In particular, you must set these macros:

/* Enable monitoring of 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)

For more information on the configuration macros, see Configuration Macros in Polyspace Test API for C/C++ Code.

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_FILE during build so that the macros in the configuration file pstunit_config.h get used during build. For more information on the macro PST_USER_CONFIG_FILE, 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_FILE -I <PSTEST_INC>

In this command:

<PSTEST_SRC> is the path to the file <polyspaceroot>\polyspace\pstest\pstunit\src\pstunit.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\R2026a.

To avoid typing the paths each time you run the tests, you can create a makefile. For example, this makefile uses a MinGW cross-compiler to create an Windows^® test executable on a Linux^® host.

Makefile

Run Tests on Target

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.

Monitor Test Execution

Use the command polyspace-test -monitor to monitor the execution of tests, retrieve the results, and convert them to a format appropriate for review.

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 attempts to convert the results into a .pstestr format and stores the results in the folder specified for the option -results-dir.

For more information, see polyspace-test -monitor.

Manually Retrieve and Convert Test Results

Instead of monitoring the test execution and producing results in a viewable format using polyspace-test -monitor, you can explicitly retrieve the test results using other methods that you might already be using for communicating with the target. You then convert the results to a format that is suitable for viewing in the Polyspace Platform user interface (.pstestr format).

For instance, if you use a terminal emulator program such as Tera Term or PuTTY to communicate with your target:

Specify in the terminal emulator program settings that any command execution output must be stored in a specific file. Make sure that the extension of your output file is .mrf.
Launch your tests on the embedded target using methods you already use.
The test execution results are stored in the .mrf file you specified in the previous step. The content of the file follows the specifications of the Polyspace Test machine-readable format (this format was ensured by earlier setting the macro PST_MONITOR_MODE to 1 in the test configuration header file pstunit_config.h). For more information on this format, see Machine-Readable Results for Tests Written Using Polyspace Test API.
Convert the test results in 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 Results in Polyspace Platform User Interface

You can open the test results file (.pstestr file) and review the results using one of these methods:

Open the .pstestr file in the Polyspace Platform user interface. For more information, see Review C/C++ Test Execution Results.
Upload the .pstestr file to the Polyspace Access™ web interface. For more information, see Upload Results to Polyspace Access.

You can also generate an HTML report from the test results. To generate an HTML report, use this command at the command line:

polyspace-test -report -html -report-dir reportFolder resultsFolder