polyspace.test.FunctionTestGenerationConfiguration Class

R2026b

Namespace: polyspace.test

(Python) Configure function-based automatic test generation

Since R2026b

expand all in page

Description

Use this Python® class to configure automatic test generation for a specific C/C++ function in a Polyspace® Platform project. Provide the function under test and optional preamble code, and manage input variables and ranges for test generation.

Creation

Syntax

functionConfig = polyspace.test.FunctionTestGenerationConfiguration(func)

Description

functionConfig = polyspace.test.FunctionTestGenerationConfiguration(func) creates a configuration object for function-based test generation, where func is a polyspace.project.Function object that represents the function to test. This object allows you to specify:

  • Preamble code to compile before the generated tests

  • Constraints on input arguments to the function under test

  • Sizes of pointer targets in the generated tests

example

Input Arguments

expand all

Function selected from project sources for which tests are generated, specified as a polyspace.project.Function object. The function must be supported for automatic test generation.

To obtain this object, use the following code pattern. Optionally, use the TestGenerationSupport property to check whether the function is supported for test generation:

codeInfo = polyspace.project.parseCode(proj)
func = codeInfo.getFunctionBySignature(<function_signature>)
func.TestGenerationSupport

Properties

expand all

This property is read-only.

Reference to the function under test that you provided when constructing the object, specified as a polyspace.project.FunctionReference object. This object contains the following property:

  • Name — Name of the function, specified as a string.

Collection of inputs used during test generation, specified as a polyspace.test.FunctionTestGenerationInputList object. Each individual input contained in this list is an instance of the polyspace.test.TestGenerationInput class that contains these properties:

  • Name — Name of the input, specified as a string. This property is read-only.

  • Scope — Scope of the input, specified as a string. This property is read-only.

  • Type — Type of the input, specified as a string. This property is read-only.

  • Value — Fixed value of the input in generated tests, specified as a string. By default, the input values are initialized to "".

  • Min — Minimum value of the input in generated tests, specified as a string. By default, the minimum values are initialized to "".

  • Max — Maximum value of the input in generated tests, specified as a string. By default, the maximum values are initialized to "".

Note

You can only assign strings to the Value, Max, or Min property of an input object. Therefore, put quotes around the values you assign. For example:

  • To specify the integer 42, assign the string "42" to the Value property.

  • To specify the double 3.14, assign the string "3.14" to the Value property.

  • To specify the string "My String", assign the string '"My String"' to the Value property.

When generating code for your tests, Polyspace Test™ uses the content of the string to reconstruct the constraints on the function input.

This table summarizes the various ways you can modify a function input list object functionConfig.Inputs, where functionConfig is a polyspace.test.FunctionTestGenerationConfiguration object.

ActionCommand
Add constraints

To apply constraints on the value of an input in the generated tests, set the Value, Min, and Max properties.

To access members of an aggregate such as a structure or union, use the member name as index. For instance, suppose that an input is a structure array of type Number that you defined as follows:

typedef struct Number {
    int intValue;
    double dblValue;
} Number;
To set the minimum and maximum values of the field intValue of the first array element, use this code pattern:
functionConfig.Inputs["Number"][0]["intValue"].Min= "-100"
functionConfig.Inputs["Number"][0]["intValue"].Max= "100"

Resize pointer targets

By default, pointer inputs in generated tests always point to a one element array. To resize a pointer targets before test generation so that it points to a multi-element array:

  • Use the resize method of the polyspace.test.TestGenerationInput class. For example, to resize the pointer target for the input Number so that it points to a 5 element array, run:

    functionConfig.Inputs["Number"].resize(5)

  • Use the indexing operator [] to access an element of the array beyond the array's current size. For example, the following command increases the size of the pointer target for the input Number (which was resized to 5 by the previous command) to 10:

    print(functionConfig.Inputs["Number"][9])

Add global variables

functionConfig.Inputs.create(glob) adds a global variable to the function input list, where glob is a polyspace.project.Global object.

For example, to add the global variable myGlobal to the input list, run these commands. Here codeInfo is the polyspace.project.CodeInfo object that you obtain after parsing source code that contains the global variable myGlobal.

glob = codeInfo.getGlobalByName("myGlobal")
functionConfig.Inputs.create(glob)

Delete global variable

  • Remove a global variable by name:

    functionConfig.Inputs.pop("myGlobal")

  • Remove the global variable at index 3:

    functionConfig.Inputs.pop(3)

  • Remove the last element of the list, if that element represents a global variable:

    functionConfig.Inputs.pop()
Delete all global variables

To remove all global variables from the list, use the clear method:

functionConfig.Inputs.clear()

Optional C/C++ code compiled into the generated test harness prior to executing tests, specified as a string.

For example, you can use this property to specify include statements or helper declarations:

functionConfig.Preamble = '#include "decls.h"'

Examples

collapse all

Generate tests to achieve a coverage objective while constraining the value of one function input.

Create the project, add your source files, and parse the code. Then create options and generate tests for the checkAgainstSpeedLimit function.

## Import modules
import polyspace.project
import polyspace.test
import os

## Create project
examples_path = os.path.join(polyspace.__install_path__, "polyspace", 
                            "examples", "doc_pstest", "coverage_tests")

proj = polyspace.project.Project("myProject.psprjx")

## Add source file and include path
proj.Code.Files.add(os.path.join(examples_path, "src","helpers.c"))
proj.IncludePaths.add(os.path.join(examples_path, "src"))

## Parse code - returned object contains list of functions and other source code data
codeInfo = polyspace.project.parseCode(proj)

## Get function
func = codeInfo.getFunctionBySignature("bool checkAgainstSpeedLimit(uint32_t, uint32_t)")

## Set coverage objective to DECISION for test generation
cOpts = polyspace.test.CoverageTestOptions()
cOpts.Level = polyspace.project.CoverageMetricLevel.DECISION

## Set function-specific test generation options
## Constrain the "limit" input to a constant value of 70u
cfg = polyspace.test.FunctionTestGenerationConfiguration(func)
cfg.Inputs["limit"].Value = "70u"

# Generate tests
testGenResults = polyspace.test.generateTests(proj, cfg, cOpts)

Inspect the generated tests. In each test case, the value of the input limit is set to 70u.

Specify size of pointer targets when generating tests. By default, in generated tests, pointer inputs always point to a one element array. You can resize pointer targets before test generation so that pointer inputs point to a multi-element array.

Create the project, add your source files, and parse the code. Then create options and generate tests for the addLatestReading function.

## Import modules
import polyspace.project
import polyspace.test
import os

## Create project
examples_path = os.path.join(polyspace.__install_path__, "polyspace", 
                            "examples", "doc_pstest", "coverage_tests")

proj = polyspace.project.Project("myProject.psprjx")

## Add source file and include path
proj.Code.Files.add(os.path.join(examples_path, "src","helpers.c"))
proj.IncludePaths.add(os.path.join(examples_path, "src"))

## Parse code - returned object contains list of functions and other source code data
codeInfo = polyspace.project.parseCode(proj)

## Get function
func = codeInfo.getFunctionBySignature("void addLatestReading(ecoCarState*, uint32_t)")

## Set boundary-value test generation options
## Set maximum number of tests to 50
bOpts = polyspace.test.BoundaryTestOptions()
bOpts.Mode = polyspace.test.BoundaryTestingMode.MINIMAL
bOpts.MaxNumberOfTests = 50

## Set function-specific test generation options
## Set the size of the pointer target for the "myEcoCarState" input to 2
cfg = polyspace.test.FunctionTestGenerationConfiguration(func)
cfg.Inputs["myEcoCarState"].resize(2)

# Generate tests
testGenResults = polyspace.test.generateTests(proj, cfg, bOpts)

Inspect the generated tests. In the test data associated with each test case, the pointer target has type ecoCarState[2].

Combining the previous two capabilities, you can constrain test generation for a multi-argument function where multiple arguments are required to be consistent with each other. For instance, you can generate functionally correct tests for a multi-argument function where one argument represents an array and another represents the size of the array.

For example, consider this function:

uint32_t containsNumber(uint32_t arr[], uint32_t size, uint32_t number) {
    for (uint32_t i = 0; i < size; i++) {
        if (arr[i] == number) {
            return 1;
        }
    }
    return 0;
}
When you generate tests for this function, you want the array argument arr to have a size that is consistent with the value of the size argument.

Create the project, add your source files, and parse the code. Then create options and generate tests for the containsNumber function.

## Import modules
import polyspace.project
import polyspace.test
import os

## Create project
examples_path = os.path.join(polyspace.__install_path__, "polyspace", 
                            "examples", "doc_pstest", "coverage_tests")

proj = polyspace.project.Project("myProject.psprjx")

## Add source file and include path
proj.Code.Files.add(os.path.join(examples_path, "src","helpers_with_arrays.c"))
proj.IncludePaths.add(os.path.join(examples_path, "src"))

## Parse code - returned object contains list of functions and other source code data
codeInfo = polyspace.project.parseCode(proj)

## Get function
func = codeInfo.getFunctionBySignature("uint32_t containsNumber(uint32_t*, uint32_t, uint32_t)")

## Set coverage objective to DECISION for test generation
cOpts = polyspace.test.CoverageTestOptions()
cOpts.Level = polyspace.project.CoverageMetricLevel.DECISION

## Set function-specific test generation options
## Make sure the array argument "arr" has size that is consistent with the value of the "size" argument
cfg = polyspace.test.FunctionTestGenerationConfiguration(func)
cfg.Inputs["size"].Value = "5"
cfg.Inputs["arr"].resize(5)

# Generate tests
testGenResults = polyspace.test.generateTests(proj, cfg, cOpts)

Inspect the generated tests. In the test data, the pointer targets are of type uint32_t[5], which is consistent with the value 5 of the size argument.

Version History

Introduced in R2026b

See Also

| | | |

Topics