polyspace-test -generate-tests

R2026b

(System Command) Generate C/C++ unit tests automatically in a Polyspace Platform project

Since R2026b

Syntax

polyspace-test -generate-tests -project <projectFile> -boundary -config-file <configFile> [options]

polyspace-test -generate-tests -project <projectFile> -coverage -config-file <configFile> [options]

polyspace-test -generate-tests -project <projectFile> -boundary -function <function> [options]

polyspace-test -generate-tests -project <projectFile> -coverage -function <function> [options]

Description

The system command polyspace-test -generate-tests generates C/C++ unit tests automatically for boundary values or coverage objectives in a Polyspace^® Platform project.

Generate Tests Using a Configuration File

polyspace-test -generate-tests -project <projectFile> -boundary -config-file <configFile> [options] generates boundary-value tests using the test generation configuration file <configFile>. The configuration file describes the code under test and constraints on the inputs. Depending on the contents of <configFile>, the test generator produces either function-based (tabular) or scripted tests.

Use the polyspace-test -create-testgen-config command to create a default configuration file and then modify it to according to your testing requirements.

polyspace-test -generate-tests -project <projectFile> -coverage -config-file <configFile> [options] generates tests to achieve coverage objectives using the test generation configuration file <configFile>. Depending on the contents of <configFile>, the test generator produces either function-based (tabular) or scripted tests.

Use the polyspace-test -create-testgen-config command to create a default configuration file and then modify it to according to your testing requirements.

Generate Tests for a Specific Function

polyspace-test -generate-tests -project <projectFile> -boundary -function <function> [options] generates boundary-value tests for the function function within the project projectFile. The generated tests exercise boundary values (such as minimum, maximum, and zero) for each input of the specified function.

By default, the generated tests are contained within the default test suite of the project. If the project does not contain a default test suite and at least one test is generated, the test generator creates a default test suite. To specify a nondefault destination suite, use the -destination-suite <suiteName> option (see the description of the options argument below).

polyspace-test -generate-tests -project <projectFile> -coverage -function <function> [options] generates tests to achieve coverage objectives for the function function within the project projectFile. The generated tests target structural coverage metrics such as decision, condition/decision, or MC/DC coverage for the specified function.

Examples

Generate Boundary Value Tests for a Function

Generate a small suite that exercises boundary values with minimal combinations. Include both zero parameter values and off-by-one values in the generated tests.

Generate boundary-value tests for the saturate_value function in the project myProject.psprjx. Use the minimal boundary testing mode and include off-by-one values and zero parameter values.

polyspace-test -generate-tests -project myProject.psprjx -boundary -function "int saturate_value(int)" -boundary-mode minimal -boundary-include-off-by-one -boundary-include-zero-parameters

The command generates boundary-value tests in the default test suite of the project. The generated tests exercise minimum, maximum, zero, and off-by-one values for the input of saturate_value.

Build and run the generated tests.

polyspace-test -build -project myProject.psprjx
polyspace-test -run -project myProject.psprjx -results-dir resultsFolder

Generate Tests to Achieve Full Decision Coverage

Generate tests that target full decision coverage for a function, then run the tests and verify that they have achieved full decision coverage.

Generate tests for the saturate_value function in the project myProject.psprjx, targeting decision coverage.

polyspace-test -generate-tests -project myProject.psprjx -coverage -function "int saturate_value(int)" -cov-metric-level decision

The command generates tests in the default test suite that target full decision coverage for the saturate_value function.

Build and run the generated tests with code coverage profiling enabled, then generate a report to verify coverage results.

polyspace-test -run -project myProject.psprjx -profiling-mode coverage -cov-metric-level decision -results-dir resultsFolder
polyspace-test -report -report-dir reportFolder -xml resultsFolder

Generate Function-Based (Tabular) Tests Using a Configuration File

Create a default configuration file, customize it with input constraints, and then use it to generate tests.

Create a default configuration file for the checkAgainstSpeedLimit function.

polyspace-test -create-testgen-config -config-file myConfig.toml -project myProject.psprjx -function "bool checkAgainstSpeedLimit(uint32_t, uint32_t)"

Edit the generated configuration file myConfig.toml to add constraints on the inputs. For example, fix one input to a constant value:

Tabular = true
CodeUnderTest = "bool checkAgainstSpeedLimit(uint32_t, uint32_t)"

[[Inputs]]
Var = 0
MinValue = "20"
MaxValue = "250"

[[Inputs]]
Var = 1
Value = "70"

Generate coverage tests using the customized configuration file.

polyspace-test -generate-tests -project myProject.psprjx -coverage -config-file myConfig.toml -cov-metric-level decision

Create Scripted Tests Using a Configuration File

Create a configuration file to describe a scripted test. Specify a script body, input variables, and constraints.

This example creates a scripted test for a function with this signature:

bool checkAgainstSpeedLimit(uint32_t speedReading, uint32_t limit)

Create a configuration file speedcheck_config.toml. Specify a test script body that exercises the checkAgainstSpeedLimit function and add input variables with constraints.

Tabular = false

Preamble = """
#include "decls.h"
"""
Body = """
bool res = checkAgainstSpeedLimit(speed, limit);
"""

[[Inputs]]
Var = "speed"
Type = "unsigned int"
MinValue = "20"
MaxValue = "250"

[[Inputs]]
Var = "limit"
Type = "unsigned int"
Value = "70"

Generate coverage tests using the scripted configuration file.

polyspace-test -generate-tests -project myProject.psprjx -coverage -config-file speedcheck_config.toml -cov-metric-level decision

Generate Tests into a Named Test Suite and Replace Existing Tests

Generate boundary-value tests into a specific test suite and replace any previously generated tests for the same function and objective type (boundary or coverage).

Generate boundary-value tests for the addLatestReading function into a test suite named boundary_tests. Limit the maximum number of generated tests to 50 and replace any previously generated tests.

polyspace-test -generate-tests -project myProject.psprjx -boundary -function "void addLatestReading(ecoCarState*, uint32_t)" -destination-suite boundary_tests -replace-tests -boundary-mode minimal -boundary-max-generated-tests 50

Input Arguments

-project <projectFile> — Path to project file

string

Absolute or relative path to the Polyspace Platform project file (.psprjx file) that contains the source files for which you want to generate tests.

Example: -project "myProject.psprjx"

Example: -project "C:\Users\jsmith\project\myTestProject.psprjx"

-config-file <configFile> — Path to test generation configuration file

string

Path to a configuration file that describes the code under test and constraints on the inputs. The configuration file uses a TOML-like format to describe both tabular (function-based) and scripted test generation settings, including preamble, setup, teardown, code under test, and input constraints such as fixed values, minimum/maximum bounds, and pointer target sizes.

Use -config-file as an alternative to -function when you need fine-grained control over test generation inputs. To create a default configuration file for a function, use the polyspace-test -create-testgen-config command. See Configuration File Format.

-function <function> — Name of function to generate tests for

string

Name of the C/C++ function to generate tests for. If only one function with the specified name exists in the project sources, specifying just the function name is sufficient. Otherwise, specify the full function signature.

Example: -function "int saturate_value(int)"

Example: -function "saturate_value"

options — Options to customize test generation

strings

General Options

Option	Description
-output-project <outputProjectFile>	Specify an output project file. When you use this option, the generated tests are saved in the specified output project instead of the input project.
-test-config <configName>	Override the project test configuration by specifying the name of a test configuration variant.
-destination-suite <suiteName>	Name of the test suite in which to generate the tests. If the project does not contain a test suite with this name and the test generator creates at least one test, the test generator also creates a test suite with the specified name.
-replace-tests	Replace existing tests in the destination suite. When generating tabular tests, this option replaces all tests in the destination suite that were previously generated for the same function and objective (-coverage or -boundary). When generating tests with scripted steps, this option replaces all previously generated tests that have the same body.
-verbose	Enable verbose output to help with debugging.
-help, -h	Show help message.

Coverage Options

Option	Description
-cov-metric-level <level>	Select a coverage level for test generation. Specify <level> as one of these values: decision — The generated tests achieve full decision coverage. condition/decision — The generated tests achieve full condition coverage, in addition to full decision coverage. mcdc — The generated tests achieve full MC/DC coverage, in addition to full condition and decision coverage.
-cov-relbound	Generate tests that cover relational boundaries. When you use this option, for each relational operator in the tested function (such as == or <), the generated tests must test the operator with equal operand values and values that differ by a tolerance.
-cov-relbound-abs-tol <value>	Absolute tolerance for floating-point relational boundaries. Operands differ by at most this value.
-cov-relbound-rel-tol <value>	Relative tolerance for floating-point relational boundaries. Operands differ by at most this value times the largest operand magnitude (relTol * max(|lhs|,|rhs|)).
-cov-restrict-to-function	Limit test generation to satisfy coverage objectives only within the function under test instead of traversing into other reachable code. Use this option to keep test scope focused.
-cov-existing-coverage-file <coverageFile>	Specify a .psprof coverage file to generate tests only for missing coverage. By default, the test generation process does not consider existing tests. Use this option to generate additional tests after taking into account current test results.
-cov-timeout <seconds>	Test generation timeout in seconds. If the time limit is exceeded, the test generator stops and returns any tests created up to that point. Default value is 300.

Boundary Options

Option	Description
-boundary-mode <mode>	Boundary test generation mode. Specify <mode> as one of these values: minimal — Generate the fewest tests that still exercise boundary values (such as minimum, maximum, or zero) for each parameter. exhaustive — Generate combinations that exercise all boundary values across multiple inputs to expose boundary interactions.
-boundary-max-generated-tests <number>	Maximum number of tests to generate. Use this option to avoid combinatorial growth, especially with the exhaustive mode. Default value is 10.
-boundary-include-zero-parameters	Generate tests with parameters set to 0. If you use this option, for a signed input, tests are generated for values in {min, 0, max}.
-boundary-include-smallest-float	For floating-point parameters, generate tests with the smallest representable value and its negative. If you use this option, tests are generated for values in {min, -eps, eps, max}, where eps is the smallest representable value.
-boundary-include-off-by-one	For integer parameters, generate tests with values that are one off from boundary values. If you use this option, tests are generated for values in {min, min + 1, max - 1, max}.

Version History

Introduced in R2026b