Configuration Macros in Polyspace Test API for C/C++ Code

The Polyspace^® Test™ xUnit API enables you to author C/C++ tests that can run on your host platform or an embedded target. When working with embedded targets, it may be necessary to adapt your test executable to align with the specific features of the target. For example, if a standard header such as stdio.h is not available on your target, you have to use a custom function to display test results. When creating the test executable for such targets, you have to specify the absence of the standard header and the custom display function.

The Polyspace Test xUnit API provides several macros that allow you to configure the test executable for your target.

Prerequisites

This topic describes test authoring using the Polyspace Test xUnit API. To compile these tests, you are required to know some file paths in advance. For your convenience, you can define environment variables to stand for the file paths, or otherwise include the file paths in your build. For more information, see Set Up C/C++ Testing and Code Profiling Using Self-Managed Builds.

Use of Configuration Macros

To configure the test executable for your target:

1. Define all required configuration macros in a header file pstunit_config.h.

2. When building your tests, define the macro PST_USER_CONFIG_FILE using a compilation option so that this header gets included in your build. For example, if you are using the GCC compiler, you can add this command-line option when compiling your tests:

   -D PST_USER_CONFIG_FILE

Instead of pstunit_config.h, you can use a header with a different name. In this case, when building your tests, set the macro PST_USER_CONFIG_HEADER_FILE to your header name so that this header is included in your build. For example, if you are using the GCC compiler, add this command-line option when compiling your tests:

-D PST_USER_CONFIG_HEADER_FILE=<my_config_header.h>

where my_config_header.h is the name of your header file.

Usage Example

By default, tests written using the Polyspace Test xUnit API generate an output in tabular format that is human-readable on a console. However, when executing tests on a target, it is more useful to generate test results in a machine-readable format, transfer the output to your host platform, and then convert the output to a format that can be opened in the Polyspace Platform user interface.

To generate machine-readable results:

1. Set the configuration macro PST_OUTPUT to the value PST_OUTPUT_MRF in a header file pstunit_config.h:

   #define PST_OUTPUT PST_OUTPUT_MRF

2. Enable support for configuration macros when building your tests.

   For example, if you use the GCC compiler for building tests, add this command-line option when compiling your tests:

   -D PST_USER_CONFIG_FILE

For information on the machine-readable format for test results, see Machine-Readable Results for Tests Written Using Polyspace Test API. To convert machine-readable results to a format that you can use in the Polyspace Platform user interface, see Define Test Results Format.

List of Configuration Macros

This table provides a list of configuration macros that you can use to adapt test executables for specific targets.

Macro	Description	Example
PST_GET_CURRENT_TIME	Specify a custom time-measurement function.	Polyspace Test uses a default time-measurement function. If you want to define a time-measurement function custom_time, specify the function by using this macro: #define PST_GET_CURRENT_TIME custom_time For user-defined time-measurement functions, Polyspace Test expects this signature: void custom_time(time_t *s, unsigned int* ms)
PST_ENABLE_EXECUTION_TIME	Specify whether to calculate the time required to run xUnit tests.	To enable calculating the time required to run your xUnit tests, define this macro as follows: #define PST_ENABLE_EXECUTION_TIME 1 To disable calculating the time required to run your xUnit tests, define this macro as follows: #define PST_ENABLE_EXECUTION_TIME 0 Some embedded targets do not support time measurement. When compiling test executables for such targets, set PST_ENABLE_EXECUTION_TIME to 0. Otherwise, the compilation can fail.
PST_EMBEDDED_MODE	Adapt test executable for launching on embedded devices.	To support launching of test executables on embedded targets, define this macro as follows: #define PST_EMBEDDED_MODE 1 This macro: Sets the macro PST_OUTPUT to PST_OUTPUT_MRF so that results are generated in a machine-readable format. For more information on this format, see Machine-Readable Results for Tests Written Using Polyspace Test API. Disables support for direct command-line launch of test executables, thereby reducing the executable size. For usage examples, see Optimize xUnit Test Executables for Embedded Targets.
PST_COMPACT_EMBEDDED_MODE	Build a compact test executable for embedded devices.	This macro adapts the test executable for launching on embedded targets by setting PST_EMBEDDED_MODE to 1. In addition, the macro results in a test executable that is as small as possible. This test executable runs the tests and reports their pass or fail status, but lacks several features. For example, this executable lacks support for library functions defined in the header stdio.h. For usage examples, see Optimize xUnit Test Executables for Embedded Targets.
PST_MONITOR_MODE	Support monitoring of test execution on embedded devices.	This macro adapts the test executable for launching on embedded targets by setting PST_EMBEDDED_MODE to 1. In addition, the macro results in a test executable which supports the following: Monitoring of test execution from host. Retrieval of test results from target to host. Conversion of test results to a format that can be viewed in the Polyspace Platform user interface. For usage examples, see Run C/C++ Tests on Target Using Existing Toolchain Setup.
PST_HAS_STDIO	Specify whether you want standard input/output support for the test executable.	By default, this macro is set to 1 and the test executable outputs formatted tests. When this macro is set to 0, the test executable no longer has stdio support. If you set PST_COMPACT_EMBEDDED_MODE to 1, this macro is set to 0. When this macro is set to 0, you must set the macro PST_WRITE.
PST_WRITE	Supply a custom implementation of a function that can write characters to the console.	This macro defines the function used to write the output of the test executable. By default, this macro points to the printf() function defined in the header stdio.h. When you set PST_COMPACT_EMBEDDED_MODE to 1 or PST_HAS_STDIO to 0, you must define PST_WRITE. Polyspace expects a function with this signature: pst_write(const char* string, int length); The first argument is a C-string and the second argument is the length of the string. You must implement this function so that it can write a C-string to the output of your target.
PST_OUTPUT	Specify the format in which test results are generated.	Set this macro to one of these values: PST_OUTPUT_TABLE – Tabular format PST_OUTPUT_BRIEF – Brief format PST_OUTPUT_TAP – Test Anything Protocol (TAP) format PST_OUTPUT_MRF – Machine-readable format For more information on the results formats, see Results Format of Tests Written Using Polyspace Test API.
PST_RETURN_ON_ABORT	Specify the behavior of test execution if an assertion or assumption failure occurs.	If an assertion or assumption failure occurs in a function called from a test, by default, the execution returns to the caller. If you want an assertion or assumption failure to exit the test entirely, define this macro as follows: #define PST_RETURN_ON_ABORT 0 By default, the test exit behavior is implemented using the setjmp/longjmp mechanism in C and exceptions in C++. If you set PST_RETURN_ON_ABORT to 0 and both mechanisms are not available, there is an error during test execution.
PST_HAS_EXCEPTION	Allow or forbid the use of C++ exceptions to exit tests. This option is relevant only if you set PST_RETURN_ON_ABORT to 0.	This macro is set to 1 by default. To specify that C++ exceptions are not available and cannot be used to exit tests, define this macro as follows: #define PST_HAS_EXCEPTION 0 This ensures that the xUnit API implementation does not use exceptions and uses alternatives such as the setjmp/longjmp mechanism to exit tests. If you use compiler flags such as the GCC or Clang flag -fno-exceptions during compilation, the macro PST_HAS_EXCEPTION is automatically set to 0 to disable the use of exceptions.
PST_HAS_SETLONGJMP	Allow or forbid the use of setjmp/longjmp mechanism to exit tests. This option is relevant only if you set PST_RETURN_ON_ABORT to 0.	This macro is set to 1 by default. To specify that the setjmp/longjmp mechanisms are not available and cannot be used to exit tests, define this macro as follows: #define PST_HAS_SETLONGJMP 0