Get Started with Python API for Polyspace

You can manage Polyspace® Test™ workflows entirely at the command line by using the Python® API for Polyspace. This example demonstrates the workflow for using the API to:

  • Create a project.

  • Add source files and xUnit test files to the project.

  • Build and run tests in the project.

Prerequisites

Make sure you are using a supported Python version and you are able to import the polyspace.project and polyspace.test Python modules without errors. For more information, see Set Up Python API for Polyspace.

Import Modules

Import the modules polyspace.project and polyspace.test:

import polyspace.project
import polyspace.test
import os
For more information, see Set Up Python API for Polyspace.

Create Project and Add Files

To create a project, use the polyspace.project module.

examples_path = os.path.join(polyspace.__install_path__, "polyspace", 
                            "examples", "pstest", "Getting_Started_Example")
polyspaceProject = polyspace.project.Project("getStarted")
The command creates a polyspace.project.Project object polyspaceProject and a project file getStarted.psprjx in the current folder.

Use the properties of polyspaceProject to add source and xUnit test files to the project.

# Add source code files
polyspaceProject.Code.Files.add(os.path.join(examples_path, "sources", "utils.c"))
polyspaceProject.IncludePaths.add(os.path.join(examples_path, "includes"))

# Add test file
polyspaceProject.Tests.Files.add(os.path.join(examples_path, "tests", "test.c"))

To view additional properties and methods that are available with objects from the polyspace.project and polyspace.test modules, press Tab as you type a command.

Build and Run Tests

To build and run the tests in the project, use the polyspace.test.run() method.

res = polyspace.test.run(polyspaceProject)
Polyspace Test builds a test executable and runs the tests. If the test executable already exists and you have not made any changes to your code, the polyspace.test.run() method runs the executable without rebuilding first.

Read Test Results

The polyspace.test.run() method returns a polyspace.test.TestResults object that you can use to read test results. For instance, you can do the following:

  • Check overall status of test execution:

    if not res.Status.Failed and not res.Status.Incomplete: 
    print("All tests have passed.")
elif res.Status.Failed:
    print("At least one test failed.")
else:
    print("At least one test did not run to completion.")

  • Print names of suites with failing tests:

    for resTestSuite in res.TestSuiteResults:
    if resTestSuite.Status.Failed:
        print(resTestSuite.Name)

  • Print names of failing test cases:

    for resTestSuite in res.TestSuiteResults:
    if resTestSuite.Status.Failed:
        for resTestCase in resTestSuite.TestCaseResults:
            if resTestCase.Status.Failed:
                print(f"{resTestSuite.Name}/{resTestCase.Name}")

  • Print file names and line numbers of failing assessments:

    for resTestSuite in res.TestSuiteResults:
    if resTestSuite.Status.Failed:
        for resTestCase in resTestSuite.TestCaseResults:
            if resTestCase.Status.Failed:
                print(f"{resTestSuite.Name}/{resTestCase.Name}\n")
                for resAssessment in resTestCase.FailedAssessmentResults:
                    print(f"{resAssessment.File}: Line {resAssessment.Line}")

See Also

| | | | | |

Topics