polyspace.project.ScriptedTestStep Class

R2026b

Namespace: polyspace.project

(Python) Create and manage scripted test steps

Since R2025a

Description

This Python^® class contains information about a scripted test step that you author using the Polyspace^® Test™ Python API. This class includes:

• The body of the step that contains the code this step executes

• Inputs supplied to the step body

• Step observables

• Assessments against which the success of the test is evaluated

Note

You can only assign strings to the Value property of an input, assessment, or observable. Therefore, put quotes around the values you want to 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.

• To specify the address of a variable var, assign the string "&var" to the Value property.

When generating code for your tests, Polyspace Test uses the content of the string to reconstruct the value of the input, assessment, or observable.

Creation

Syntax

scriptedStep = testCase.TestSteps.createScripted(stepName)

scriptedStep = testCase.TestSteps.createFrom(existingScriptedStep, stepName)

Description

scriptedStep = testCase.TestSteps.createScripted(stepName) creates a scripted test step with name stepName in a polyspace.project.TestCase or polyspace.project.OwnedTestCase object testCase.

scriptedStep = testCase.TestSteps.createFrom(existingScriptedStep, stepName) creates a scripted test step with name newName by copying an existing scripted test step existingScriptedStep.

Input Arguments

existingScriptedStep — Existing scripted test step

polyspace.project.ScriptedTestStep object

Existing scripted test step to copy, specified as a polyspace.project.ScriptedTestStep object. The existing step can be from any test case.

stepName — Name of test step

string

Name of test step specified as a string. This name is assigned to the Name property of the newly created step.

Properties

Name — Name of scripted step

str value

Name of the test step, specified as a string. You specify this name when you create the scripted test step using either the createScripted or createFrom method.

Description — Description of the test step

str

Description associated with the test step, specified as a string.

Enabled — Whether step is enabled

True (default) | False

Whether this step is executed or not when you run your project, specified as either True or False. The default value is True.

Inputs — List of step inputs

polyspace.project.StepInputList value

List of inputs associated with the test step, specified as a polyspace.project.StepInputList object. Each individual input contained in this list is a polyspace.project.StepInput object that contains these properties:

• Name — Name of the input variable in your source code, specified as a string. This property is read-only.

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

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

• Value — Value of the input for this test step, specified as a string, polyspace.project.TestData object, or polyspace.project.TestParameter object. By default, the input values are initialized to "0".

This table summarizes the various ways you can access or modify a test inputs list object scriptedStep.Inputs, where scriptedStep is a polyspace.project.ScriptedTestStep object.

Action	Command
Access individual inputs	Index using numeric location. For example, scriptedStep.Inputs[2]. Index using the name of the input variable <varName>. For example, scriptedStep.Inputs["<varName>"].
Assign value to an input	Assign a string, polyspace.project.TestData object, or polyspace.project.TestParameter object to the Value property. For example, scriptedStep.Inputs[0].Value = "23" scriptedStep.Inputs[1].Value = testData scriptedStep.Inputs[2].Value = testParam
Add new input for a primitive type	Suppose that codeInfo is the polyspace.project.CodeInfo object that you obtain after parsing your source code. Also assume that your step body contains a variable myInput of int type that you want to specify as an input. Run this command: dataType = codeInfo.getType("int") scriptedStep.Inputs.create("myInput",dataType)
Delete an input	Remove an input by name: scriptedStep.Inputs.pop("myInput") Remove the input at index 0: scriptedStep.Inputs.pop(0) Remove the last input in the list: scriptedStep.Inputs.pop()
Delete all inputs	scriptedStep.Inputs.clear()

Body — Step body

str value

The code that the scripted test step executes, specified as a string. The following code snippet is an example of a step body specification.

# Step body that invokes saturate_and_cache multiple times.
scriptedStep.Body = r"""
out1 = saturate_and_cache(in);
out2 = saturate_and_cache(in+3);
out3 = saturate_and_cache(in+5);
"""

Observables — List of step observables

polyspace.project.StepObservableList value

List of observables associated with the test step, specified as a polyspace.project.StepObservableList object. Each individual observable contained in this list is a polyspace.project.StepObservable object that contains these properties:

• Name — Name of the observable variable in the step body, specified as a string. This property is read-only.

• Type — Data type of the observable variable, specified as a string. This property is read-only.

This table summarizes the various ways you can access or modify an observable list object scriptedStep.Observables, where scriptedStep is a polyspace.project.ScriptedTestStep object.

Action	Command
Access individual observables	Index using numeric location. For example, scriptedStep.Observables[2]. Index using the name of the observable variable <varName>. For example, scriptedStep.Observables["<varName>"].
Add new observable for a primitive type	Suppose that codeInfo is the polyspace.project.CodeInfo object that you obtain after parsing your source code. Also assume that your step body contains a variable myObservable of int type that you want to specify as an observable. Run this command: dataType = codeInfo.getType("int") scriptedStep.Observables.create("myObservable",dataType) When you create a new observable, an assessment is automatically created for that observable. For example, to assign a value to the assessment that is automatically created for myObservable, run a command like this: scriptedStep.Assessments["myObservable"].Value = "2"
Delete an observable	Delete an observable by name: scriptedStep.Observables.pop("myObservable") Delete the observable at index 0: scriptedStep.Observables.pop(0) Delete the last observable in the list: scriptedStep.Observables.pop()
Delete all observables	scriptedStep.Observables.clear()

Assessments — List of step assessments

polyspace.project.StepAssessmentList value

List of assessments associated with the test step, specified as a polyspace.project.StepAssessmentList object. Each individual assessment contained in this list is a polyspace.project.StepAssessment object that has these properties:

• Comparator — Comparator for the assessment, specified as a polyspace.project.AssessmentComparator enum class object. The enum values are EQUAL, GREATER, GREATER_EQUAL, LESS, LESS_EQUAL, NONE, and NOT_EQUAL.

• Enabled — Option to use this assessment to determine if the test passes, specified as True or False.

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

• Scope — Scope of the assessment variable such as "local" or "fcn_call", specified as a string. This property is read-only.

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

• Type — Data type of the assessment variable, or "call count" for function call count assessments, specified as a string. This property is read-only.

• Value — Value of the assessment, specified as a string or a polyspace.project.TestData object. By default, the assessment values are initialized to "0", or "0u" for function call count assessments.

This table summarizes the various ways you can access or modify a step assessment list object scriptedStep.Assessments, where scriptedStep is a polyspace.project.ScriptedTestStep object.

Action	Command
Access individual assessments	Index using numeric location. For example, scriptedStep.Assessments[2]. Index using the name of the assessment variable <varName>. For example, scriptedStep.Assessments["<varName>"]. Index using the name of an observable you add to a scripted step. For example, scriptedStep.Assessments["myObservable"].
Assign value to an assessment	Assign a string or a polyspace.project.TestData object to the Value property: scriptedStep.Assessments[0].Value = "23" scriptedStep.Inputs[1].Value = testData
Add new assessment	Create an assessment from an input: scriptedStep.Assessments.create(scriptedStep.Inputs[0]) Create an assessment from an observable: scriptedStep.Assessments.create(scriptedStep.Observables[0])
Add new function call count assessment	Create a function call count assessment and verify that a function is called at least once: functionGetMinValue = codeInfo.getFunctionBySignature("int getMinValue(void)") scriptedStep.Assessments.create(functionGetMinValue) Modify the assessment so that it verifies that the function is called exactly once by updating the Comparator and Value properties: scriptedStep.Assessments["getMinValue()"].Comparator = "EQUAL" scriptedStep.Assessments["getMinValue()"].Value = "1u" To add a function call count assessment for a function, the function must be supported for mocking. For more information see Limitations in polyspace.project.Mock.
Delete assessment	Remove an assessment by name: scriptedStep.Assessments.pop("myAssessment") Remove the assessment at index 0: scriptedStep.Assessments.pop(0) Remove the last assessment in the list: scriptedStep.Assessments.pop()
Delete all assessments	Use the clear method to delete all assessments: scriptedStep.Assessments.clear()

CallSequenceAssessment — Function call sequence assessment

polyspace.project.CallSequenceAssessment object

Since R2026b

Function call sequence assessment for the test step, specified as a polyspace.project.CallSequenceAssessment object. Use this property to verify that specific functions are called in a defined order during test execution. Optionally, enable input parameter assessments for each function call to verify that the functions in the call sequence were called with the expected input or range of input values.

For more information, see polyspace.project.CallSequenceAssessment.

ActiveMocks — Function overrides or mocks applied to step

polyspace.project.ActiveMockSet object

Mocks applied to the step specified as a polyspace.project.ActiveMockSet object. Use the following methods to populate the set:

• To apply a mock described by a polyspace.project.Mock object mock, use the add() method:

  scriptedStep.ActiveMocks.add(mock)

  For more information, see polyspace.project.Mock.

• To remove a polyspace.project.Mock object mock from the step, use the remove() method:

  scriptedStep.ActiveMocks.remove(mock)

• To remove all mocks, use the clear() method:

  scriptedStep.ActiveMocks.clear()

Examples

Create Graphical Test Case with Scripted Step

This example shows how to add a scripted test step in a graphical test case.

Before starting, make sure you can import the polyspace.project and polyspace.test modules on a Python shell or in a Python script without errors. For more information, see Set Up Python API for Polyspace. The source file used in this python API example is available with a Polyspace installation.

Create a project, add source files, and include the source folder which contains the header file. Create a test case with preamble to include the header file containing the class definition. Then, create a scripted step and enter the step body that invokes the constructor and member functions.

# Import the required modules.
import polyspace.project, polyspace.test
import os

# Create the project, add the source files and add the source folder as an include path.
proj = polyspace.project.Project("newProject")
example_path = os.path.join(polyspace.__install_path__, "polyspace",
                            "examples", "doc_pstest", "scripted_tests")
proj.Code.Files.add(os.path.join(example_path, "src", "Position.cpp"))
proj.IncludePaths.add(os.path.join(example_path, "src"))

# Set the configuration language to C++ and parse source code.
proj.ActiveBuildConfiguration.Language = "cpp"
codeInfo = polyspace.project.parseCode(proj)

# Create a test suite and add a test case to the suite.
mySuite = proj.TestSuites.create("positionTestSuite")
myTestCase = mySuite.TestCases.create("positionScriptedTest")

# Set the test preamble to include the header with the class definition.
myTestCase.Preamble = '#include "Position.hpp"'

# Create a scripted step and set the step body of the scripted step to invoke the constructor and member functions.
scriptedStep = myTestCase.TestSteps.createScripted("testPositionConstructor")
scriptedStep.Body = """
Position currentPosition(xPos, yPos);
xMeasured = currentPosition.getX();
yMeasured = currentPosition.getY();
"""

# Get the int type from parsed code.
intType = codeInfo.getType("int")

# Add inputs for the constructor arguments.
scriptedStep.Inputs.create("xPos", intType)
scriptedStep.Inputs.create("yPos", intType)
scriptedStep.Inputs["xPos"].Value = "1"
scriptedStep.Inputs["yPos"].Value = "2"

# Add observables for the values returned by getX() and getY().
scriptedStep.Observables.create("xMeasured", intType)
scriptedStep.Observables.create("yMeasured", intType)

# Set assessments for the observables.
scriptedStep.Assessments["xMeasured"].Value = "1"
scriptedStep.Assessments["yMeasured"].Value = "2"

# Run the test.
res = polyspace.test.run(proj)

For more information on authoring tests using python API, see Author Graphical Tests Using Python API for Polyspace.

For more information on how to write scripted tests using the Polyspace Platform user interface, see Test C/C++ Functions by Using Scripts in Graphical Tests.

Mock Callees in a Scripted Step

This example shows how to create a mock for a callee function and apply the mock to a scripted test step. This example extends the previous example by mocking Position::keepValueWithinRange(int), which is called from the constructor Position::Position(int, int).

Before starting, make sure you can import the polyspace.project and polyspace.test modules on a Python shell or in a Python script without errors. For more information, see Set Up Python API for Polyspace. The source file used in this python API example is available with a Polyspace installation.

Create the project, parse code, and set up the scripted test as in the previous example. Then, create a mock for keepValueWithinRange and apply it to the scripted step.

# Import the required modules.
import polyspace.project, polyspace.test
import os

# Create the project, add the source files and Add the source folder as an include path.
proj = polyspace.project.Project("newProject")
example_path = os.path.join(polyspace.__install_path__, "polyspace",
                            "examples", "doc_pstest", "scripted_tests")
proj.Code.Files.add(os.path.join(example_path, "src", "Position.cpp"))
proj.IncludePaths.add(os.path.join(example_path, "src"))

# Set the configuration language to C++ and parse source code.
proj.ActiveBuildConfiguration.Language = "cpp"
codeInfo = polyspace.project.parseCode(proj)

# Create a test suite and add a test case to the suite.
mySuite = proj.TestSuites.create("positionTestSuite")
myTestCase = mySuite.TestCases.create("positionScriptedTest")

# Set the test preamble to include the header with the class definition.
myTestCase.Preamble = '#include "Position.hpp"'

# Create a scripted step and set the step body of the scripted step to invoke the constructor and member functions.
scriptedStep = myTestCase.TestSteps.createScripted("testPositionConstructor")
scriptedStep.Body = """
Position currentPosition(xPos, yPos);
xMeasured = currentPosition.getX();
yMeasured = currentPosition.getY();
"""

# Get the int type from parsed code.
intType = codeInfo.getType("int")

# Add inputs for the constructor arguments.
scriptedStep.Inputs.create("xPos", intType)
scriptedStep.Inputs.create("yPos", intType)
scriptedStep.Inputs["xPos"].Value = "1"
scriptedStep.Inputs["yPos"].Value = "2"

# Add observables and assessments.
scriptedStep.Observables.create("xMeasured", intType)
scriptedStep.Observables.create("yMeasured", intType)
scriptedStep.Assessments["xMeasured"].Value = "1"
scriptedStep.Assessments["yMeasured"].Value = "2"

# Create a mock for keepValueWithinRange.
funcToMock = codeInfo.getFunctionBySignature("int Position::keepValueWithinRange(int)")
mockKeepValue = proj.Mocks.create(funcToMock)

# Apply the mock to the scripted step.
scriptedStep.ActiveMocks.add(mockKeepValue)

# Run the test.
res = polyspace.test.run(proj)

For more information on authoring tests using python API, see Author Graphical Tests Using Python API for Polyspace.

For more information on how to write scripted tests using the Polyspace Platform user interface, see Test C/C++ Functions by Using Scripts in Graphical Tests.

Version History

Introduced in R2025a

R2026b: New CallSequenceAssessment Property

Use the CallSequenceAssessment property to create function call sequence assessments in a scripted test step. For more information, see polyspace.project.CallSequenceAssessment.