polyspace.project.TestCase Class

R2026b

Namespace: polyspace.project

(Python) Edit referenced test cases saved in .pstestd file

Since R2025a

expand all in page

Description

This Python® class contains information about a graphical test case that is saved separately from a Polyspace® Platform project in a .pstestd file. When you add a reference to this .pstestd file from a project, it is called a test reference. Saving your graphical test cases in .pstestd files and referencing those files from one or more projects enables you to create a modular project structure that improves sharing and version control workflows. For more information about project structure, see Modularize Project by Using External Configurations, Test References, and External Stub Files.

To work with test references in the Polyspace Python API, use this class, which contains the test case definition, together with the polyspace.project.TestCaseRef class, which contains the name of the graphical test case and the path to the .pstestd file where it is saved. You can also work with test references in the Polyspace Platform user interface.

To create and manage test cases that are owned by the project, use the polyspace.project.OwnedTestCase class.

Creation

Syntax

referencedTestCase = myTestCaseRefObj.get()

Description

referencedTestCase = myTestCaseRefObj.get() returns the polyspace.project.TestCase object referenced by the polyspace.project.TestCaseRef object myTestCaseRefObj. For more information on managing referenced test cases from a test suite, see polyspace.project.TestCaseRef.

Properties

expand all

Absolute or relative path to the .pstestd file where the referenced test case is saved, returned as a string. Relative paths are considered relative to the project location. This property is read-only. To manage the name and path of a referenced test case, use the polyspace.project.TestCaseRef class.

Description of the test case, specified as a string.

Code to run as the preamble for the test case, specified as a string. This code runs before the actual setup phase.

Code to run during the setup phase of the test case, specified as a string. This code sets up the test environment.

Code to run during the teardown phase of the test case, specified as a string. This code performs cleanup actions such as deallocating resources after the test has been executed.

List of test data associated with the test case, specified as a polyspace.project.TestDataList object. Each individual test data contained in this list is an instance of the polyspace.project.TestData class that contains these properties:

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

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

  • Value — Value of the test data, specified as a string. By default, the test data values are initialized to "0".

    Note

    You can only assign strings to the Value property of a test data 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.

    • 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 test data or parameter.

This table summarizes the various ways you can modify a test data list object testCase.TestData, where testCase is a polyspace.project.OwnedTestCase object or a polyspace.project.TestCase object.

ActionCommand
Add new test data

testData = testCase.TestData.create("myTestData",<dataType>) adds a test data object whose Name property is set to "myTestData". Here, <dataType> is a polyspace.project.Type object.

The testData object contains values of type <dataType> that are initialized to "0". To update these values, set the Value property of testData.

For example, to create a test data array of dimension 4 that contains the integers -1, 1, 3, and 5, run these commands. Here codeInfo is the polyspace.project.CodeInfo object that you obtain after parsing source code that contains the int data type.

at = codeInfo.getType("int[4]")
myData = testCase.TestData.create("myTestData",at)
for k, v in enumerate([-1, 1, 3, 5]):
    myData[k].Value = str(v)

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 a test data of this type as follows:
type = codeInfo.getType("Number")
data = testCase.TestData.create("my_data", type)
data["intValue"].Value = "1"

Delete test data

  • proj.TestData.pop("myTestData") removes the test data object with name "myTestData" from the list.

  • proj.TestData.pop(0) removes the test data object at index 0 from the list.

  • proj.TestData.pop() removes the last test data object in the list.

Delete all test data

proj.TestData.clear() removes all test data from the list.

List of test parameters, iteration strategy, and whether to load parameters at run time, specified as a polyspace.project.TestParameters object. This object has these properties:

  • Parameters — List of test parameters, specified as a polyspace.project.TestParameterList object. Each individual test parameter contained in this list is an instance of the polyspace.project.TestParameter class that has these properties:

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

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

    • Value — Values of the test parameter elements, specified as strings. By default, the test parameter element values are initialized to "0".

      Note

      You can only assign strings to the Value property of a test parameters 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.

      • 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 test data or parameter.

    This table summarizes the various ways you can modify a test parameter list object params.Parameters, where params is a polyspace.project.TestParameters object.

    ActionCommand
    Add new test parameter

    testParam = params.Parameters.create("myTestParam",<dataType>) adds a test parameter object whose Name property is set to "myTestParam". Here, <dataType> is a polyspace.project.Type object.

    The testParam object contains values of type dataType that are initialized to "0". To update these values, set the Value property of the elements of testParam.

    For example, to create a test data array of dimension 4 that contains all integers from -50 through 50, run these commands. Here codeInfo is the polyspace.project.CodeInfo object that you obtain after parsing source code that contains the int data type.

    testParam = params.Parameters.create("myParam", codeInfo.getType("int[101]"))
for k in range(101):
 testParam[k].Value = str(k-50)

    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 a two-value test parameter of this type as follows:
    type = codeInfo.getType("Number[2]")
testParam = params.Parameter.create("my_param", type)
testParam[0]["intValue"].Value = "1"
testParam[1]["intValue"].Value = "2"

    Delete a test parameter

    • params.Parameters.pop("myTestParam") removes the test parameter with name "myTestParam" from the list.

    • params.Parameters.pop(0) removes the test parameter at index 0 from the list.

    • params.Parameters.pop() removes the last test parameter in the list.

    Delete all test parameters

    params.Parameters.clear() removes all test parameters from the list.

  • Iteration — Parameter iteration strategy, specified as a polyspace.project.ParameterIterationMode enum class object. The enum values are EXHAUSTIVE and SEQUENTIAL.

  • LoadAtRunTime — Whether to load the parameter values at run time instead of embedding them in the generate code, specified as a boolean.

For more information on the Iteration and LoadAtRunTime properties, see Decide Parameterization Strategy.

List of tabular and scripted test steps associated with the test case, specified as a polyspace.project.TestStepList object. Each individual test step contained in this list is an instance of either the polyspace.project.TabularTestStep class or the polyspace.project.ScriptedTestStep class.

This table summarizes the various ways you can modify a test steps list object testCase.TestSteps, where testCase is a polyspace.project.OwnedTestCase or polyspace.project.TestCase object.

ActionCommand
Add a new tabular test step

tabularStep = testCase.TestSteps.createTabular("myTabularStep",<functionToTest>) adds a tabular test step whose Name property is set to "myTabularStep". This step exercises the function referenced by the polyspace.project.Function object <functionToTest>.

For example, to add a tabular test step for a function with signature int saturate_value(int) in your source code, run the following commands. Here codeInfo is the polyspace.project.CodeInfo object that you obtain after parsing your source code.

func = codeInfo.getFunctionBySignature("int saturate_value(int)")
step = testCase.TestSteps.createTabular("myStep", func)
Add a new scripted test step

scriptedStep = testCase.TestSteps.createScripted("myScriptedStep") adds a scripted test step whose Name property is set to "myScriptedStep".

Add copy of an existing test step

testStep = testCase.TestSteps.createFrom(<existingTestStep>,<newName>)

Here <existingTestStep> is an existing polyspace.project.TabularTestStep or polyspace.project.ScriptedTestStep object and <newName> is the name you associate with the copied test step.

Delete a test step

  • testCase.TestSteps.pop("myTestStep") removes the test step with name "myTestStep" from the list.

  • testCase.TestSteps.pop(idx) removes the test step at index idx from the list.

  • testCase.TestSteps.pop() removes the last test step in the list.

Delete all test steps

testCase.TestSteps.clear() removes all test steps from the list.

Methods

expand all

Examples

collapse all

This example shows you how to modularize your code by:

  • Creating a test case reference object in one script

  • Accessing and modifying this test reference in a second script

Normally these two actions would be performed by two different people to share .pstestd files.

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.

  1. Create a simple test for the getDifferenceOfValues function that supplies input values 2 and 2 to the function and checks the output against the assessment value 0. Convert your test case to a test reference to be used in other scripts. 

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

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

# Parse source code.
codeInfo = polyspace.project.parseCode(proj)
functionDiff = codeInfo.getFunctionBySignature("int32_t getDifferenceOfValues(int32_t arg1, int32_t arg2)")

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

# Create a test step for your test case.
simpleStep = myTestCase.TestSteps.createTabular("diffSimpleStep", functionDiff)

# Update inputs and assessments. 
simpleStep.Inputs["arg1"].Value = "2"
simpleStep.Inputs["arg2"].Value = "2"
simpleStep.Assessments["pst_call_out"].Value = "0" 

# Convert the myTestCase to a test case reference.
mySuite.TestCaseRefs.moveAsRef(myTestCase, "testRefFile.pstestd", "simpleTestRef")

  2. In a separate script, access your test reference from the .pstestd file and create a test case object. Modify your test case object by adding a new step and saving the test case. Notice the test reference contains the step with inputs and assessments created in part 1. 

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

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

# Parse source code.
codeInfo = polyspace.project.parseCode(proj)
functionDiff = codeInfo.getFunctionBySignature("int32_t getDifferenceOfValues(int32_t arg1, int32_t arg2)")

# Create a test suite
mySuite = proj.TestSuites.create("diffTestSuite")

# Add the .pstestd as a test reference, which already has a test step with inputs and assessments. 
testCaseRefObject = mySuite.TestCaseRefs.add(r"path\to\testRefFile.pstestd","simpleTestRef")
testCaseObject = testCaseRefObject.get()

# Add second test to your test case object
newStep = testCaseObject.TestSteps.createTabular("newStep", functionDiff)
newStep.Inputs["arg1"].Value = "3"
newStep.Inputs["arg2"].Value = "3"
newStep.Assessments["pst_call_out"].Value = "0" 

# Save your test case object to add it to the project.
testCaseObject.save()

# Run the project.
res = polyspace.test.run(proj)
    For more information on authoring tests using Python API, see Author Graphical Tests Using Python API for Polyspace.

This example shows you how to modularize your code by:

  • Creating a parameterized test case reference object in one script

  • Accessing and modifying this test reference in a second script

Normally these two actions would be performed by two different people to share .pstestd files.

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.

  1. Create a parameterized test for the getDifferenceOfValues function with input values for arg1 ranging from -10 to 10. Convert your test case to a test reference to be used in other scripts. 

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

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

# Parse source code.
codeInfo = polyspace.project.parseCode(proj)
functionDiff = codeInfo.getFunctionBySignature("int32_t getDifferenceOfValues(int32_t arg1, int32_t arg2)")

# Create a test suite and add a test case to the suite "diffTests"
suiteDiff = proj.TestSuites.create("diffTests")
parameterizedCase = suiteDiff.TestCases.create("diffParameterizedTest")
parameterizedStep = parameterizedCase.TestSteps.createTabular("multiplyParameterizedStep",functionDiff)

# Create integer test parameters that range from -10 to 10.
params = parameterizedCase.TestParameters
inputArg1Param = params.Parameters.create("myParam", codeInfo.getType("int[21]"))
outputParam = params.Parameters.create("outputParam", codeInfo.getType("int[21]"))

for k in range(21):
 inputArg1Param[k].Value = str(k)
 outputParam[k].Value = str(abs(k))

# Update the automatically created input and assessment. Add parameterized assessments.
parameterizedStep.Inputs["arg1"].Value = inputArg1Param
parameterizedStep.Inputs["arg2"].Value = "0"

parameterizedStep.Assessments["pst_call_out"].Value = outputParam

# Set the iteration strategy to sequential.
parameterizedCase.TestParameters.Iteration = (polyspace.project.ParameterIterationMode.SEQUENTIAL)

# Convert parameterizedCase to a test case reference
suiteDiff.TestCaseRefs.moveAsRef(parameterizedCase, "testRefFile.pstestd", "parameterizedTestRef")

  2. In a separate script, access your parameterized test reference from the .pstestd file and run the project. Modify your test case object by adding a new step and saving the test case. Notice the test reference contains the parameterized test with inputs and assessments created in part 1. 

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

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

# Parse source code.
codeInfo = polyspace.project.parseCode(proj)
functionDiff = codeInfo.getFunctionBySignature("int32_t getDifferenceOfValues(int32_t arg1, int32_t arg2)")

# Create a test suite.
mySuite = proj.TestSuites.create("diffTestSuite")

# Add the .pstestd as a test reference, which already has the parameterized test case with inputs and assessments.
testCaseRefObject = mySuite.TestCaseRefs.add(r"path\to\testRefFile.pstestd","parameterizedTestRef")
testCaseObject = testCaseRefObject.get()

# Add another test to your test case object
newStep = testCaseObject.TestSteps.createTabular("newStep", functionDiff)
newStep.Inputs["arg1"].Value = "3"
newStep.Inputs["arg2"].Value = "3"
newStep.Assessments["pst_call_out"].Value = "0" 

# Save your test case object to add it to the project.
testCaseObject.save()

# Run the project.
res = polyspace.test.run(proj)
    For more information on authoring tests using Python API, see Author Graphical Tests Using Python API for Polyspace.

Version History

Introduced in R2025a

expand all

See Also

| | | | |

Topics