polyspace.project.TabularTestStep Class

R2026b

Namespace: polyspace.project

(Python) Create and manage tabular test steps

Since R2025a

expand all in page

Description

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

  • Reference to the function that the step exercises

  • Inputs supplied to this function

  • Assessments against which the success of the test is evaluated

Note

You can only assign strings to the Value property of an input or assessment. 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 or assessment.

Creation

Syntax

tabularStep = testCase.TestSteps.createTabular(stepName, functionToTest)
tabularStep = testCase.TestSteps.createFrom(existingTabularStep, stepName)

Description

tabularStep = testCase.TestSteps.createTabular(stepName, functionToTest) creates a tabular test step with name stepName in a polyspace.project.TestCase or polyspace.project.OwnedTestCase object testCase. The step invokes functionToTest as the code under test and is added as the last step in the test.

example

tabularStep = testCase.TestSteps.createFrom(existingTabularStep, stepName) creates a tabular test step with name stepName by copying an existing tabular test step existingTabularStep.

Input Arguments

expand all

Function to test, specified as a polyspace.project.Function object.

You can get the polyspace.project.Function object for a function using the function signature by reading the parsed source code added to a project. In other words, you can parse the code associated with a polyspace.project.Project object proj and look up the function signature in the resulting polyspace.project.CodeInfo object.

For instance, suppose that the signature of a function added to a project proj is void init(int). You can obtain the associated polyspace.project.Function as follows:

codeInfo = polyspace.project.parseCode(proj)
functionToTest = codeInfo.getFunctionBySignature("void init(int)")

For more information, see polyspace.project.CodeInfo.

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

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

Properties

expand all

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

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

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

Reference to the function in your source code that the test step exercises, specified as a polyspace.project.FunctionReference object. This object contains the following property:

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

When you create a polyspace.project.TabularTestStep object, the CodeUnderTest property references the function you provided to the createTabular method. However, after you create the test step object, you can modify the code under test by assigning a different polyspace.project.Function object to the CodeUnderTest property. For example, if codeInfo is the polyspace.project.CodeInfo object that you obtain after parsing your source code, you can execute a command like this:

tabularStep.CodeUnderTest = codeInfo.getFunctionBySignature("void foo(int*, unsigned)")

Modifying the CodeUnderTest property resets all other properties of the polyspace.project.TabularTestStep object to their default values.

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 "parameter" or "global", 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 tabularStep.Inputs, where tabularStep is a polyspace.project.TabularTestStep object.

ActionCommand
Access individual inputs

  • Index using numeric location. For example, tabularStep.Inputs[2].

  • Index using the name of the input variable <varName>. For example, tabularStep.Inputs["<varName>"].

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

    typedef struct Number {
    int intValue;
    double dblValue;
} Number;
    You can access the member intValue of an input of this type as follows:
    tabularStep.Inputs[0]["intValue"]

Assign value to an input

Assign a string, polyspace.project.TestData object, or polyspace.project.TestParameter object to the Value property. For example,

tabularStep.Inputs[0].Value = "23"
tabularStep.Inputs[1].Value = testData
tabularStep.Inputs[2].Value = testParam
Add new input for a global

Suppose that codeInfo is the polyspace.project.CodeInfo object that you obtain after parsing your source code that contains a global variable myGlobal.

myGlob = codeInfo.getGlobalByName("myGlobal")
tabularStep.Inputs.create(myGlobal)

Delete input for a global

  • Remove an input by name:

    tabularStep.Inputs.pop("myGlobal")

  • Remove an input by index:

    tabularStep.Inputs.pop(0)

  • Remove the last input in the list:

    tabularStep.Inputs.pop()
Delete all global inputs 
tabularStep.Inputs.clear()

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. The default value is True.

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

  • Scope — Scope of the assessment variable such as "return" 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 ways you can access or modify a test assessment list object tabularStep.Assessments, where tabularStep is a polyspace.project.TabularTestStep object.

ActionCommand
Access individual assessments

  • Index using numeric location. For example, tabularStep.Assessments[2].

  • Index using the name of the assessment variable <varName>. For example, tabularStep.Assessments["<varName>"].

  • If the function under test has a return value, a default assessment with name pst_call_out is automatically created. To access this assessment, use tabularStep.Assessments["pst_call_out"].

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

    typedef struct Number {
    int intValue;
    double dblValue;
} Number;
    You can access the member intValue of an assessment of this type as follows:
    tabularStep.Assessments[0]["intValue"]

Assign value to an assessment

Assign a string or a polyspace.project.TestData object to the Value property:

tabularStep.Assessments[0].Value = "23"
tabularStep.Inputs[1].Value = testData
Add new assessment

Create an assessment from an input:

tabularStep.Assessments.create(tabularStep.Inputs[0])

Create an assessment from the return value stored in the ReturnValue property of the tabular step:

tabularStep.Assessments.create(tabularStep.ReturnValue)

Obtain a polyspace.project.CodeInfo object codeInfo by parsing your source code that contains a global variable myGlobal. Create an assessment for this global variable:

myGlobal = codeInfo.getGlobalByName("myGlobal")
tabularStep.Assessments.create(myGlobal)

Add new function call count assessment

Obtain a polyspace.project.CodeInfo object codeInfo by parsing your source code. Create a function call count assessment and verify that a function is called at least once:

functionGetMinValue = codeInfo.getFunctionBySignature("int getMinValue(void)")
tabularStep.Assessments.create(functionGetMinValue)
Modify the assessment so that it verifies that the function is called exactly once by updating the Comparator and Value properties:
tabularStep.Assessments["getMinValue()"].Comparator = "EQUAL"
tabularStep.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:

    tabularStep.Assessments.pop("myAssessment")

  • Remove an assessment by index:

    tabularStep.Assessments.pop(0)

  • Remove the last assessment in the list:

    tabularStep.Assessments.pop()
Delete all assessments

Use the clear method to delete all assessments:

tabularStep.Assessments.clear()

Since R2026b

Function call sequence assessment for the test step, specified as a polyspace.project.CallSequenceAssessment object. Use this property to verify that your code under test calls specific functions 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.

Reference to the value the function under test returns, specified as a polyspace.project.StepReturnValue object. This object contains the following properties:

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

  • Type — Data type of the value the function returns, specified as a string.

You can use the ReturnValue property to create assessments. For more information, see the description of the Assessments property.

The test data object that stores the return value of the function under test. To store the return value, create a polyspace.project.TestData object with the data type of the return value and assign this object to the StoreReturnValue property.

For example, if the function under test returns an int value, run these commands. Here, codeInfo is the polyspace.project.CodeInfo object that you obtain after parsing your source code.

dataType = codeInfo.getType("int")
returnValue = testCase.TestData.create("myReturnValue", dataType)
tabularStep.StoreReturnValue = returnValue

For more information about the polyspace.project.TestData class, see the description of the TestData property of the polyspace.project.TestCase and polyspace.project.OwnedTestCase classes.

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:

    tabularStep.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:

    tabularStep.ActiveMocks.remove(mock)

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

    tabularStep.ActiveMocks.clear()

Examples

collapse all

This example shows how to add a simple test step in a graphical test. To write graphical tests using the Polyspace python API, you must

  • Create a test suite.

  • Add one or more test cases to your suite.

  • Add one or more test steps to your 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 test suite and test case. Add a step to your test case.

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

# Create the project and add a source file. 
proj = polyspace.project.Project("newProject")
example_path = os.path.join(polyspace.__install_path__, "polyspace",
                            "examples", "doc_pstest", "multi_step_tests")
proj.Code.Files.add(os.path.join(example_path, "src", "multistep_test_with_test_data.c"))

# Parse source code.
codeInfo = polyspace.project.parseCode(proj)
functionCleanUpData = codeInfo.getFunctionBySignature("int32_t cleanUpData(int32_t arg)")

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

# Create test step for your test case.
simpleStep = myTestCase.TestSteps.createTabular("singleSimpleStep", functionCleanUpData)

# Update inputs and assessments. 
simpleStep.Inputs["arg"].Value = "6"
simpleStep.Assessments["pst_call_out"].Value = "5" 

# 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 test steps using the Polyspace Platform user interface, see Write Multistep Tests in Polyspace Platform User Interface.

This example shows you how to create a multistep test where the output to the first step becomes the input to the second step.

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.

Write a multistep test that invokes the two functions in the file multistep_test_with_test_data.c in sequence to confirm that the functions work as intended.

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

# Create the project and add a source file. 
proj = polyspace.project.Project("newProject")
example_path = os.path.join(polyspace.__install_path__, "polyspace",
                            "examples", "doc_pstest", "multi_step_tests")
proj.Code.Files.add(os.path.join(example_path, "src", "multistep_test_with_test_data.c"))

# Parse source code.
codeInfo = polyspace.project.parseCode(proj)
functionIsDataClean = codeInfo.getFunctionBySignature("int32_t isDataClean(int32_t arg)")
functionCleanUpData = codeInfo.getFunctionBySignature("int32_t cleanUpData(int32_t arg)")

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

# Create the first step for the function cleanUpData, set the input value to 6, and remove the default assessment. 
stepCleanUpData = myTestCase.TestSteps.createTabular("Step_ID1_cleanUpData",functionCleanUpData)
stepCleanUpData.Inputs["arg"].Value = "6"
stepCleanUpData.Assessments.clear()

# Store the output value from step 1. 
step1Out = myTestCase.TestData.create("Step_ID1_out",codeInfo.getType("int32_t"))
stepCleanUpData.StoreReturnValue = step1Out

# Create the second step for the function isDataClean. Use the output value produced by Step 1 as the input to Step 2
stepIsDataClean = myTestCase.TestSteps.createTabular("Step_ID2_isDataClean", functionIsDataClean)
stepIsDataClean.Inputs["arg"].Value = step1Out

# Check that isDataClean returns 1.
stepIsDataClean.Assessments["pst_call_out"].Value = "1"

# 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 multistep tests using the Polyspace Platform user interface, see Write Multistep Tests in Polyspace Platform User Interface.

Version History

Introduced in R2025a

expand all

See Also

| | | | |

Topics