polyspace.project.Project Class

Namespace: polyspace.project

(Python) Create and manage Polyspace Platform projects

Since R2024a

expand all in page

Description

Create or load a Polyspace® Platform project and manage the project configuration using this Python® class.

Creation

Syntax

proj = polyspace.project.Project("myProjectName")

Description

proj = polyspace.project.Project("myProjectName") loads the project from the file myProjectName.psprjx, if it already exists, or creates a new project in the current folder. You use the object proj to manage the project configuration. You do not need to specify the file extension (.psprjx) when you create or load a project file. If you create a new project, the project file myProjectName.psprjx is not saved to your file system until you explicitly run the proj.save() command.

example

Properties

expand all

Basic Information

Full path to project file (.psrpjx) including project name, specified as a string.

Example: r"C:\Polyspace_Projects\newProject.psprjx"

Name of project author, specified as a string. For more information on the corresponding configuration option, see Author.

Example: "matt"

Version identifier to indicate the current state of the project, specified as a string. This identifier appears in reports generated from test or profiling results. For more information on the corresponding configuration option, see Version.

Example: "1.0"

Example: "1.1.23 (stable)"

Date and time when project was created, specified as a datetime.datetime object. For more information on the corresponding configuration option, see Created.

Example: 2024-Jul-17 14:14:14

Date and time when the project was last saved with modifications, specified as a datetime.datetime object. For more information on the corresponding configuration option, see Last modified.

Example: 2024-Jul-17 14:14:14

Descriptive information about the project, specified as a string.

Example: "This is my test project."

Configuration

Build configurations owned by the project, returned as a polyspace.project.BuildConfigurationList object. A polyspace.project.BuildConfigurationList object is a list of polyspace.project.OwnedBuildConfiguration objects. The object properties correspond to the build-related options in Polyspace Test™. See Test Execution in Polyspace Platform User Interface.

This table summarizes the ways you can use a build configuration that is owned by a project proj.

ActionCommand
Create new owned build configurationownedBuildConfig = proj.BuildConfigurations.create("myBuildConfig")
Load existing configurationownedBuildConfig = proj.BuildConfigurations["Owned config name"]
Create owned build configuration by copying an existing build configuration

ownedBuildConfig = proj.BuildConfigurations.createFrom(existingConfig, nameOfCopy)

Here, existingConfig is one of the following:

  • An existing polyspace.project.OwnedBuildConfiguration object

  • The path to a .pscfg file containing a build configuration

Optionally, use the nameOfCopy argument to specify a name for the copied configuration.

Convert a referenced external build configuration to an owned build configuration

ownedBuildConfig = proj.BuildConfigurations.moveAsOwned(existingConfigRefObj)

Here, existingConfigRefObj is the existing polyspace.project.BuildConfigurationRef object to convert to a build configuration attached to the project proj.

Export a copy of an owned build configuration object to a .pscfg fileownedBuildConfig.export("filename.pscfg")
View available build configurations owned by the projectproj.BuildConfigurations
Modify a property of an owned build configurationownedBuildConfig.Libraries.append("gtest.lib")
Display owned build configuration

Quiet — print(ownedBuildConfig)

Verbose — print(f"{ownedBuildConfig:verbose}")

Set the active build configuration for the projectproj.ActiveBuildConfiguration = ownedBuildConfig

Since R2026a

External build configurations referenced by the project, returned as a polyspace.project.BuildConfigurationRefList object. A polyspace.project.BuildConfigurationRefList object is a list of polyspace.project.BuildConfigurationRef objects.

This table summarizes the ways you can interact with build configurations referenced by the project proj:

ActionCommand
Add a reference to an existing external build configuration

buildConfigRef = proj.BuildConfigurationRefs.add("myExternalBuildConfig") adds a reference to the external configuration file myExternalBuildConfig.pscfg.

You can provide a full or relative path to the external configuration file. Relative paths are considered relative to the location of the project.

Convert an owned build configuration to an external configuration, referenced by the project

buildConfigRef = proj.BuildConfigurationRefs.moveAsRef(ownedBuildConfig,fileName)

Here, ownedBuildConfig is an existing polyspace.project.OwnedBuildConfiguration object and fileName is the name of the new external configuration file for the project to reference.

Remove a reference to an external build configuration

proj.BuildConfigurationRefs.pop(i) removes the reference to the external build configuration at index i in the list.

Remove all references to external build configurations

proj.BuildConfigurationRefs.clear() removes all references to external build configurations.

View external build configurations referenced by the projectproj.BuildConfigurationRefs
Display name and path of external build configuration

print(buildConfigRef)

Set the active build configuration for the projectproj.ActiveBuildConfiguration = buildConfigRef

The polyspace.project.BuildConfigurationRef object has two properties:

  • Name — Name of the external build configuration

  • Path — Path to the external configuration file (.pscfg) that the project references

Use the get() method of the polyspace.project.BuildConfigurationRef object to get the polyspace.project.BuildConfiguration object it references and inspect or modify that build configuration. The properties of the polyspace.project.BuildConfiguration object correspond to the build-related options in Polyspace Test. See Test Execution in Polyspace Platform User Interface.

This table summarizes the ways you can interact with a polyspace.project.BuildConfiguration object referenced by a polyspace.project.BuildConfigurationRef object.

ActionCommand
Load existing polyspace.project.BuildConfigurationRef object and get the build configuration it references

buildConfigRef = proj.BuildConfigurationRefs["External config name"]

externalBuildConfig = buildConfigRef.get()

Modify a property of the referenced external configurationexternalBuildConfig.Libraries.append("gtest.lib")
Save the external build configuration

externalBuildConfig.save()

Save (export) a copy of the external build configuration as a .pscfg file

externalBuildConfig.saveCopy("copyOfExternalBuildConfig.pscfg")

Unload the external build configuration from memoryexternalBuildConfig.close()

Build configuration currently active in the project, specified as a polyspace.project.OwnedBuildConfiguration or polyspace.project.BuildConfigurationRef object. The options in the active configuration are used when you build the project using polyspace.test.build or build and run tests using polyspace.test.run.

Static analysis configurations owned by the project, returned as a polyspace.project.StaticAnalysisConfigurationList object. A polyspace.project.StaticAnalysisConfigurationList object is a list of polyspace.project.OwnedStaticAnalysisConfiguration objects. The object properties correspond to the options related to static analysis in Polyspace Bug Finder™ and Polyspace Code Prover™. See Polyspace Bug Finder options (Polyspace Bug Finder) and Polyspace Code Prover options (Polyspace Code Prover).

This table summarizes the ways you can use a static analysis configuration that is owned by a project proj.

ActionCommand
Create new owned static analysis configurationownedStaticConfig = proj.StaticAnalysisConfigurations.create("myStaticConfig")
Load existing configurationownedStaticConfig = proj.StaticAnalysisConfigurations["Owned config name"]
Create owned static analysis configuration by copying an existing static analysis configuration

ownedStaticConfig = proj.StaticAnalysisConfigurations.createFrom(existingConfig, nameOfCopy)

Here, existingConfig is one of the following:

  • An existing polyspace.project.OwnedStaticAnalysisConfiguration object

  • The path to a .pscfg file containing a static analysis configuration

Optionally, use the nameOfCopy argument to specify a name for the copied configuration.

Convert a referenced external static analysis configuration to an owned static analysis configuration

ownedStaticConfig = proj.StaticAnalysisConfigurations.moveAsOwned(existingConfigRefObj)

Here, existingConfigRefObj is the existing polyspace.project.StaticAnalysisConfigurationRef object to convert to a static analysis configuration attached to the project proj.

Export a copy of an owned static analysis configuration to a .pscfg fileownedStaticConfig.export("filename.pscfg")
View available static analysis configurations owned by the projectproj.StaticAnalysisConfigurations
Modify a property of an owned static analysis configurationownedStaticConfig.Multitasking.EnableMultitasking = True
Display owned static analysis configuration

Quiet — print(ownedStaticConfig)

Verbose — print(f"{ownedStaticConfig:verbose}")

Set the active static analysis configuration for the projectproj.ActiveStaticAnalysisConfiguration = ownedStaticConfig

Since R2026a

External static analysis configurations referenced by the project, returned as a polyspace.project.StaticAnalysisConfigurationRefList object. A polyspace.project.StaticAnalysisConfigurationRefList object is a list of polyspace.project.StaticAnalysisConfigurationRef objects.

This table summarizes the ways you can interact with static analysis configurations referenced by the project proj:

ActionCommand
Add a reference to an existing external static analysis configuration

staticConfigRef = proj.StaticAnalysisConfigurationRefs.add("myExternalStaticConfig") adds a reference to the external configuration file myExternalStaticConfig.pscfg.

You can provide a full or relative path to the external configuration file. Relative paths are considered relative to the location of the project.

Convert an owned static analysis configuration to an external configuration, referenced by the project

staticConfigRef = proj.StaticAnalysisConfigurationRefs.moveAsRef(ownedStaticConfig,fileName)

Here, ownedStaticConfig is an existing polyspace.project.OwnedStaticAnalysisConfiguration object and fileName is the name of the new external configuration file for the project to reference.

Remove a reference to an external static analysis configuration

proj.StaticAnalysisConfigurationRefs.pop(i) removes the reference to the external static analysis configuration at index i in the list.

Remove all references to external static analysis configurations

proj.StaticAnalysisConfigurationRefs.clear() removes all references to external static analysis configurations.

View external static analysis configurations referenced by the projectproj.StaticAnalysisConfigurationRefs
Display name and path of external static analysis configuration

print(staticConfigRef)

Set the active static analysis configuration for the projectproj.ActiveStaticAnalysisConfiguration = staticConfigRef

The polyspace.project.StaticAnalysisConfigurationRef object has two properties:

  • Name — Name of the external static analysis configuration

  • Path — Path to the external configuration file (.pscfg) that the project references

Use the get() method of the polyspace.project.StaticAnalysisConfigurationRef object to get the polyspace.project.StaticAnalysisConfiguration object it references and inspect or modify that static analysis configuration. The properties of the polyspace.project.StaticAnalysisConfiguration object correspond to the options related to static analysis in Polyspace Bug Finder and Polyspace Code Prover. See Polyspace Bug Finder options (Polyspace Bug Finder) and Polyspace Code Prover options (Polyspace Code Prover).

This table summarizes the ways you can interact with a polyspace.project.StaticAnalysisConfiguration object referenced by a polyspace.project.StaticAnalysisConfigurationRef object.

ActionCommand
Load existing polyspace.project.StaticAnalysisConfigurationRef object and get the static analysis configuration it references

staticConfigRef = proj.StaticAnalysisConfigurationRefs["External config name"]

externalStaticConfig = staticConfigRef.get()

Modify a property of the referenced external configurationexternalStaticConfig.Multitasking.EnableMultitasking = True
Save the external static analysis configuration

externalStaticConfig.save()

Save (export) a copy of the external static analysis configuration as a .pscfg file

externalStaticConfig.saveCopy("copyOfExternalStaticConfig.pscfg")

Unload the external static analysis configuration from memoryexternalStaticConfig.close()

Static analysis configuration currently active in the project, specified as a polyspace.project.OwnedStaticAnalysisConfiguration or polyspace.project.StaticAnalysisConfigurationRef object. The options in this configuration are used when you run static analysis on the project using Polyspace Bug Finder or Polyspace Code Prover.

Testing and profiling configurations owned by the project, returned as a polyspace.project.TestConfigurationList object. A polyspace.project.TestConfigurationList object is a list of polyspace.project.OwnedTestConfiguration objects. The object properties correspond to the options related to code profiling in Polyspace Test. See Code Profiling in Polyspace Platform User Interface.

This table summarizes the ways you can use a test configuration that is owned by a project proj.

ActionCommand
Create new owned test configurationownedTestConfig = proj.TestConfigurations.create("myTestConfig")
Load existing configurationownedTestConfig = proj.TestConfigurations["Owned config name"]
Create owned test configuration by copying an existing test configuration

ownedTestConfig = proj.TestConfigurations.createFrom(existingConfig)

Here, existingConfig is one of the following:

  • An existing polyspace.project.OwnedTestConfiguration object

  • The path to a .pscfg file containing a testing and profiling configuration

Convert a referenced external test configuration to an owned test configuration

ownedTestConfig = proj.TestConfigurations.moveAsOwned(existingConfigRefObj)

Here, existingConfigRefObj is the existing polyspace.project.TestConfigurationRef object to convert to a testing and profiling configuration attached to the project proj.

Export a copy of an owned test configuration to a .pscfg fileownedTestConfig.export("filename.pscfg")
View available test configurations owned by the projectproj.TestConfigurations
Modify a property of an owned test configurationownedTestConfig.CoverageOptions.Level = polyspace.project.CoverageMetricLevel.MCDC
Display owned test configuration

Quiet — print(ownedTestConfig)

Verbose — print(f"{ownedTestConfig:verbose}")

Set the active test configuration for the projectproj.ActiveTestConfiguration = ownedTestConfig

Since R2026a

External testing and profiling configurations referenced by the project, returned as a polyspace.project.TestConfigurationRefList object. A polyspace.project.TestConfigurationRefList object is a list of polyspace.project.TestConfigurationRef objects.

This table summarizes the ways you can interact with testing and profiling configurations referenced by the project proj:

ActionCommand
Add a reference to an existing external testing and profiling configuration

testConfigRef = proj.TestConfigurationRefs.add("myExternalTestConfig") adds a reference to the external configuration file myExternalTestConfig.pscfg.

You can provide a full or relative path to the external configuration file. Relative paths are considered relative to the location of the project.

Convert an owned testing and profiling configuration to an external configuration, referenced by the project

testConfigRef = proj.TestConfigurationRefs.moveAsRef(ownedTestConfig,fileName)

Here, ownedTestConfig is an existing polyspace.project.OwnedTestConfiguration object and fileName is the name of the new external configuration file for the project to reference.

Remove a reference to an external testing and profiling configuration

proj.TestConfigurationRefs.pop(i) removes the reference to the external testing and profiling configuration at index i in the list.

Remove all references to external testing and profiling configurations

proj.TestConfigurationRefs.clear() removes all references to external testing and profiling configurations.

View external testing and profiling configurations referenced by the projectproj.TestConfigurationRefs
Display name and path of external testing and profiling configuration

print(testConfigRef)

Set the active testing and profiling configuration for the projectproj.ActiveTestConfiguration = testConfigRef

The polyspace.project.TestConfigurationRef object has two properties:

  • Name — Name of the external build configuration

  • Path — Path to the external configuration file (.pscfg) that the project references

Use the get() method of the polyspace.project.TestConfigurationRef object to get the polyspace.project.TestConfiguration object it references and inspect or modify that testing and profiling configuration. The properties of the polyspace.project.TestConfiguration object correspond to the options related to code profiling in Polyspace Test. See Code Profiling in Polyspace Platform User Interface.

This table summarizes the ways you can interact with a polyspace.project.TestConfiguration object referenced by a polyspace.project.TestConfigurationRef object.

ActionCommand
Load existing polyspace.project.TestConfigurationRef object and get the testing and profiling configuration it references

testConfigRef = proj.TestConfigurationRefs["External config name"]

externalTestConfig = testConfigRef.get()

Modify a property of the referenced external configurationexternalTestConfig.CoverageOptions.Level = polyspace.project.CoverageMetricLevel.MCDC
Save the external testing and profiling configuration

externalTestConfig.save()

Save (export) a copy of the external testing and profiling configuration as a .pscfg file

externalTestConfig.saveCopy("copyOfExternalTestConfig.pscfg")

Unload the external build configuration from memoryexternalTestConfig.close()

Testing and profiling configuration currently active in the project, specified as a polyspace.project.OwnedTestConfiguration or polyspace.project.TestConfigurationRef object. The options in this configuration are used when you build the project using polyspace.test.build or build and run tests using polyspace.test.run with ProfilingSelection set to one of these:

  • polyspace.test.ProfilingSelection.COVERAGE (coverage computation)

  • polyspace.test.ProfilingSelection.EXECUTION (execution profiling)

  • polyspace.test.ProfilingSelection.STACK (stack profiling)

  • polyspace.test.ProfilingSelection.SANITIZER (code sanitizer profiling)

Source Files and Include Folders

Source files added to the project, specified as a polyspace.project.Code object. Use the following methods to manage the list:

  • To add source files, use the Files.add() method.

    sources = proj.Code
sources.Files.add("path/to/file.c")

  • To add source folders, use the Folders.add() method. Set the Recursive argument to True to add all subfolders recursively.

    sources = proj.Code
sources.Folders.add("path/to/folder",Recursive=True)

  • To remove source files, use the Files.pop() method with a string or index value. If you do not provide an argument to the Files.pop() method, the last file added to the list is removed.

    sources = proj.Code
sources.Files.pop("path/to/file.c")
sources.Files.pop(0)
    To remove all source files use the Files.clear() method.
    sources = proj.Code
sources.Files.clear()

  • To remove source folders, use the Folders.pop() method with a string or index value. If you do not provide an argument to the Folders.pop() method, the last folder added to the list is removed.

    sources = proj.Code
sources.Folders.pop("path/to/folder")
sources.Folders.pop(0)
    To remove all source folders use the Folders.clear() method.
    sources = proj.Code
sources.Folders.clear()

Include folders specified in the project specified as a list of polyspace.project.IncludeFolderSpec objects. Each object in the list has the following properties:

PropertyDescription
PathPath to include folder.
RecursiveWhether all subfolders are added recursively, specified as True or False.
FollowSymLinksWhether symbolic links must be resolved, specified as True or False.

Use the following methods to manage the list:

  • To add include folders, use the add() method. Set the Recursive argument to True to add all subfolders recursively.

    includes = proj.IncludePaths
includes.add("path/to/folder",Recursive=True)

  • To remove include folders, use the pop() method with an index value. If you do not provide an argument to the pop() method, the last include folder added to the list is removed.

    includes = proj.IncludePaths
includes.pop(0)

  • To empty the list of include folders, use the clear() method.

    includes = proj.IncludePaths
includes.clear()

List of project variables specified as a polyspace.project.VariablesMap object. Project variables are variables that can be used as shorthands in paths added to a project. For more information, see Project variables.

This table summarizes the ways you can modify the project variables.

ActionCommand
Get the value of a project variable

rootDirPath = proj.Variables["ROOTDIR"] assigns the value of a project variable ROOTDIR to the variable rootDirPath.

Set the value of an existing project variable, or add a new project variable.

proj.Variables["ROOTDIR"] = r"C:\Polyspace_Projects" sets the value of the variable ROOTDIR to a new value r"C:\Polyspace_Projects". If ROOTDIR already exists, its value is updated. Otherwise, the project variable is created.

Note that PROJECTDIR is a predefined project variable that should not be redefined.

Delete a project variable.

rootDirPath = proj.Variables.pop("ROOTDIR") removes the value of the project variable from the list of project variables in the project.

Before removing a project variable, make sure that it is not used anywhere in the paths added to the project.

Stubs and Mocks

Since R2026a

Function stubs added to the project, returned as a polyspace.project.FunctionStubList object. A polyspace.project.FunctionStubList object is a list of polyspace.project.FunctionStub objects. Use the following methods to manage the list:

  • To create a new function stub for the polyspace.project.Function object functionToStub, use the create() method.

    fcnStubs = proj.FunctionStubs
newFcnStub = fcnStubs.create(functionToStub)

  • To create a copy of an existing function stub from another project, use the createFrom() method.

    fcnStubs = proj.FunctionStubs
fcnStubCopy = fcnStubs.createFrom(existingFunctionStubObj)

  • To remove an existing function stub using its name fcnStubName or its index fcnStubIdx, use the pop() method. If you do not provide an argument to the pop() method, the last item in the list is removed.

    fcnStubs = proj.FunctionStubs
fcnStubs.pop("fcnStubName")
fcnStubs.pop(1)

  • To remove all function stubs from the project, use the clear() method.

    fcnStubs = proj.FunctionStubs
fcnStubs.clear()

To stub undefined functions using an external C/C++ source file, see polyspace.project.Stubs.

Since R2026a

Variable stubs added to the project, returned as a polyspace.project.VariableStubList object. A polyspace.project.VariableStubList object is a list of polyspace.project.VariableStub objects. Use the following methods to manage the list:

  • To create a new variable stub for the polyspace.project.Global object variableToStub, use the create() method.

    varStubs = proj.VariableStubs
newVarStub = varStubs.create(variableToStub)

  • To create a copy of an existing variable stub from another project, use the createFrom() method.

    varStubs = proj.VariableStubs
varStubCopy = varStubs.createFrom(existingVariableStubObj)

  • To remove an existing variable stub using its name varStubName or index varStubIdx, use the pop() method. If you do not provide an argument to the pop() method, the last item in the list is removed.

    varStubs = proj.VariableStubs
varStubs.pop("varStubName")
varStubs.pop(2)

  • To remove all variable stubs from the project, use the clear() method.

    varStubs = proj.VariableStubs
varStubs.clear()

To stub undefined variables using an external C/C++ source file, see polyspace.project.Stubs.

Since R2026a

External C/C++ files containing stub implementations for undefined functions and variables, specified as a polyspace.project.Stubs object. Stubbing undefined functions and variables in an external C/C++ file is an alternative to using project-specific stubs for functions (polyspace.project.FunctionStub objects) and variables (polyspace.project.VariableStub objects). Using external stub files allows you to reuse existing stubs, share stubs across similar projects and write more complex stub implementations.

Since R2026a

Mocks added to the project returned as a polyspace.project.MockList object. A polyspace.project.MockList object is a custom list of polyspace.project.Mock objects. Use the following methods to manage the list:

  • To create a new mock using a polyspace.project.Function object functionToMock, use the create() method.

    mocks = proj.Mocks
newMock = mocks.create(functionToMock)
    For more information, see polyspace.project.Mock.

  • To duplicate an existing polyspace.project.Mock object existingMock with a new name newMockName, use the createFrom() method.

    mocks = proj.Mocks
newMock = mocks.createFrom(existingMock, newMockName)
    For more information, see polyspace.project.Mock.

  • To remove a existing mock using its name mockName, use the pop() method.

    mocks = proj.Mocks
mocks.pop(mockName)

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

    mocks = proj.Mocks
mocks.clear()

Tests

Test suites that you author in the Polyspace Platform user interface or using the Polyspace Test Python API, specified as a polyspace.project.TestSuiteList object. Each individual test suite is an instance of the polyspace.project.TestSuite class. Each test suite can contain graphical test cases owned by the project or graphical test cases that are referenced by the project.

This table summarizes the ways you can modify a test suite list object proj.TestSuites, where proj is a project object.

ActionCommand
Add a new test suite

testSuite = proj.TestSuites.create("myTestSuite") adds a test suite whose Name property is set to "myTestSuite".

Add copy of an existing test suite

testSuite = proj.TestSuites.createFrom(existingTestSuite, newName)

Here, existingTestSuite is an existing polyspace.project.TestSuite object and newName is the name to associate with the copied test suite.

Delete a test suite

proj.TestSuites.pop("myTestSuite") removes the test suite with name "myTestSuite" from the list.

proj.TestSuites.pop(2) removes the test suite at index 2 in the list.

proj.TestSuites.pop() removes the last test suite from the list.

Delete all test suites

proj.TestSuites.clear() removes all test suites from the list.

A polyspace.project.TestSuite object has these properties:

  • Name — Name of the test suite, specified as a string. You specify this name when you create the test suite.

  • TestCases — Owned graphical test cases that the test suite contains, returned as a polyspace.project.TestCaseList object. Each individual test case contained in this list is an instance of the polyspace.project.OwnedTestCase class.

    This table summarizes the ways you can modify a test case list object suite.TestCases, where suite is a polyspace.project.TestSuite object.

    ActionCommand
    Add a new owned test case

    testCase = suite.TestCases.create("myTestCase") adds a graphical test case whose Name property is set to "myTestCase".

    Add copy of an existing test case to the project

    testCase = suite.TestCases.createFrom(existingTestCase, newName)

    Here, existingTestCase is the existing polyspace.project.OwnedTestCase object or the .pstestd file to copy, and newName is the name to associate with the copied test case.

    Convert referenced test case to an owned test case

    testCase = testSuite.TestCases.moveAsOwned(existingTestCaseRefObj) converts the test case referenced by existingTestCaseRefObj in testSuite to a polyspace.project.OwnedTestCase object in the same test suite.

    Delete an owned test case

    suite.TestCases.pop("myTestCase") deletes the test case named "myTestCase" from the project. Alternatively, remove a test case at index i in the list with suite.TestCases.pop(i).

    Delete all owned test cases

    suite.TestCases.clear() removes all test cases from the list.

  • TestCaseRefs — Test references that the test suite contains, returned as a polyspace.project.TestCaseRefList object. A test reference is a graphical test case that you save in a .pstestd file that is linked to the project by reference. A polyspace.project.TestCaseRefList object is a list of polyspace.project.TestCaseRef objects. (since R2026a)

    This table summarizes the ways you can modify a test case ref list object suite.TestCaseRefs, where suite is a polyspace.project.TestSuite object.

    ActionCommand
    Add a reference to a .pstestd graphical test case file

    testCaseRef = suite.TestCaseRefs.add(testCaseFile, testRefName) adds a reference to the existing .pstestd graphical test case file testCaseFile and sets the Name property to testRefName.

    Convert owned test case to a test reference

    testCaseRef = suite.TestCaseRefs.moveAsRef(existingTestCase, fileName, testCaseRefName)

    Here, existingTestCase is an existing polyspace.project.OwnedTestCase object, fileName is the name to give the .pstestd file that will be referenced by the project, and testCaseRefName is an optional argument to set the Name property of the new test case reference.

    Remove a test reference

    suite.TestCaseRefs.pop("myTestCaseRef") removes the test case reference with name "myTestCaseRef" from the project. Alternatively, remove a test case reference at index i in the list with suite.TestCaseRefs.pop(i).

    Remove all test references

    suite.TestCaseRefs.clear() removes all test references from the project.

Polyspace Test xUnit test files added to the project, specified as a polyspace.project.Tests object. Use the following methods to manage the list:

  • To add test files, use the Files.add() method.

    tests = proj.Tests
tests.Files.add("path/to/file.c")

  • To add test folders, use the Folders.add() method. Set the Recursive argument to True to add all subfolders recursively.

    tests = proj.Tests
tests.Folders.add("path/to/folder",Recursive=True)

  • To remove test files, use the Files.pop() method with a string or index value. If you do not provide an argument to the Files.pop() method, the last folder added to the list is removed.

    tests = proj.Tests
tests.Files.pop("path/to/file.c")
tests.Files.pop(0)
    To remove all test files use the Files.clear() method.
    tests = proj.Tests
tests.Files.clear()

  • To remove test folders, use the Folders.pop() method with a string or index value. If you do not provide an argument to the Folders.pop() method, the last folder added to the list is removed.

    tests = proj.Tests
tests.Folders.pop("path/to/folder")
tests.Folders.pop(0)
    To remove all test folders use the Folders.clear() method.
    tests = proj.Tests
tests.Folders.clear()

External test files added to the project, specified as a polyspace.project.ExternalTests object. Use the following methods to manage the list:

  • To add test files, use the Files.add() method.

    tests = proj.ExternalTests
tests.Files.add("path/to/file.c")

  • To add test folders, use the Folders.add() method. Set the Recursive argument to True to add all subfolders.

    tests = proj.ExternalTests
tests.Folders.add("path/to/folder",Recursive=True)

  • To remove test files, use the Files.pop() method with a string or index value. If you do not provide an argument to the Files.pop() method, the last folder added to the list is removed.

    tests = proj.ExternalTests
tests.Files.pop("path/to/file.c")
tests.Files.pop(0)
    To remove all test files use the Files.clear() method.
    tests = proj.ExternalTests
tests.Files.clear()

  • To remove test folders, use the Folders.pop() method with a string or index value. If you do not provide an argument to the Folders.pop() method, the last folder added to the list is removed.

    tests = proj.ExternalTests
tests.Folders.pop("path/to/folder")
tests.Folders.pop(0)
    To remove all test folders use the Folders.clear() method.
    tests=proj.ExternalTests
tests.Folders.clear()

Methods

expand all

Examples

collapse all

This example shows how to create or load a Polyspace Platform project and manage the project configuration.

In general, you generate and manage Polyspace Test projects and results by using classes from the polyspace.project and polyspace.test modules. Before starting, make sure you can import these modules on a Python shell or in a Python script without errors. For more information, see Set Up Python API for Polyspace.

Import the required modules:

import polyspace.project
import polyspace.test

Create new project and add source code and test files:

# Create new project
myProj = polyspace.project.Project("newProject")
# Add source and test files
myProj.Code.Files.add("file.c")
myProj.Tests.Files.add("test.c")

Save your changes to the file system.

myProj.save()

Since R2026a

When authoring a test for a C/C++ function, you can work around undefined functions and variables by replacing them with stubs. A stub for an undefined function has the same signature as the function, but a different function body, often an empty one. You can stub undefined callees in a Polyspace Platform project by writing your own external C/C++ stub files, or by creating project-specific stubs with polyspace.project.Project.FunctionStubs and polyspace.project.Project.VariableStubs. This example shows how to create default project-specific stubs for all undefined callees in a project using the Polyspace Python API.

Create the project, add your source files, and parse the code.

## Import modules
import polyspace.project
import os

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

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

## Add source files and include path
proj.Code.Files.add(os.path.join(examples_path, "algo.c"))
proj.Code.Files.add(os.path.join(examples_path, "saturate.c"))
proj.IncludePaths.add(os.path.join(examples_path))

## Parse code
codeInfo = polyspace.project.parseCode(proj)

The codeInfo object has a Functions property that contains all the functions in the source code, returned as a custom list of polyspace.project.Function objects. The codeInfo object also has a Globals property that contains all the global variables in the source code, returned as a custom list of polyspace.project.Global objects.

Use the StubbingSupport property of the polyspace.project.Function and polyspace.project.Global objects to identify which functions and variables are undefined and require stubbing. Write for-loops to identify and create default stubs for all undefined functions and variables in the project.

for f in codeInfo.Functions:
    if f.StubbingSupport:
        proj.FunctionStubs.create(f)

for v in codeInfo.Globals:
    if v.StubbingSupport:
        proj.VariableStubs.create(v)

Set the Value property of the minValue and maxValue variable stubs to -2 and 2, respectively.

minValueStub = proj.VariableStubs[0]
minValueStub.Value = "-2"

maxValueStub = proj.VariableStubs[1]
maxValueStub.Value = "2"

This example shows how to import tests that you develop in an external framework, for example GoogleTest, into a Polyspace project and then use the Python API to build and run the tests.

In general, you generate and manage Polyspace Test projects and results by using classes from the polyspace.project and polyspace.test modules. Before starting, make sure you can import these modules on a Python shell or in a Python script without errors. For more information, see Set Up Python API for Polyspace.

Import the required modules:

import polyspace.project
import polyspace.test
import os

Create a project and define some project variables to refer to the Polyspace installation folder, the folder containing example files, and the GoogleTest installation folder.

externProj = polyspace.project.Project("externalProject")
externProj.Variables["EXAMPLESFOLDER"] = os.path.join(polyspace.__install_path__, "polyspace", 
                            "examples", "doc_pstest")
externProj.Variables["GTESTINSTALLFOLDER"] = "/usr/local/googletest"

Create a build configuration project and configure the build options for your project. For an example of how to configure your project when you import tests from GoogleTest, see Run GoogleTest Tests Using Polyspace Platform Projects.


buildConf = externProj.BuildConfigurations.create("externTestConfig")
buildConf.ExtraLinkFlags = "-pthread"
buildConf.ExternalTestsBuildOptions.IncludePaths.add("$(GTESTINSTALLFOLDER)/googletest/googletest/include")
buildConf.ExternalTestsBuildOptions.LibraryPaths.append("$(GTESTINSTALLFOLDER)/googletest/build/lib")
buildConf.ExternalTestsBuildOptions.Libraries.append("libgtest.a")
buildConf.ExternalTestsBuildOptions.Libraries.append("libgtest_main.a")

Add the source and external test files to your project.

externProj.Code.Files.add("$(EXAMPLESFOLDER)/google_test/hUserCode.cpp")
externProj.ExternalTests.Files.add("$(EXAMPLESFOLDER)/google_test/hGoogleTest.cpp")

Assign the build configuration object you created to the active build configuration of the project.

externProj.ActiveBuildConfiguration = buildConf

When you run the tests using res = polyspace.test.run(externProj) and print the results, you see the following output:

{
     Suites Requested: 2
        Suites Passed: 1
        Suites Failed: 1
    Suites Incomplete: 0
      Tests Requested: 3
         Tests Passed: 2
         Tests Failed: 1
     Tests Incomplete: 0
            Profiling: --
}

Version History

Introduced in R2024a

expand all

See Also

| | | | | | | | | | | | | | | |

Topics