polyspace.test.StatementCoverageInfo Class

Namespace: polyspace.test

(Python) Review statement coverage results

Since R2024b

expand all in page

Description

This Python® class contains statement coverage results obtained from executing C/C++ tests. Depending on how you create an object of this class, the results can show the statement coverage for an entire project, a single file, or a single function.

Creation

Syntax

statementCoverageInfo = coverageResults.getCoverageInfo("statement")
statementCoverageInfo = coverageResults.getCoverageInfo("statement", fileName)
statementCoverageInfo = coverageResults.getCoverageInfo("statement", fileName, functionName)

Description

statementCoverageInfo = coverageResults.getCoverageInfo("statement") loads statement coverage results for the entire project:

statementCoverageInfo = coverageResults.getCoverageInfo("statement", fileName) loads statement coverage results for the file fileName (specified by full path or path relative to the current working folder):

statementCoverageInfo = coverageResults.getCoverageInfo("statement", fileName, functionName) loads statement coverage results for the file fileName and function functionName:

Properties

expand all

Total number of statements to be covered, specified as an integer.

For more information on statement coverage, see Statement Coverage.

Number of statements actually covered during test execution, specified as an integer.

For more information on statement coverage, see Statement Coverage.

Number of uncovered statements that you justified during review, specified as an integer.

For more information:

Details of condition coverage, specified as a list of polyspace.test.StatementCoverageDetail objects with the following properties:

PropertyDescription
FileFile containing statement.
FunctionFunction containing statement.
IsCoveredWhether the statement is executed at least once.
IsJustifiedWhether you justified the statement coverage (provided the statement was not covered during test execution).
RationaleRationale for justification, if you justified the statement coverage.
SourceLocation

Location of the statement, specified as a polyspace.test.SourceLocation object with the following properties:

  • StartLine – Line number where statement begins.

  • StartColumn – Column number where statement begins.

  • EndLine – Line number where statement ends.

  • EndColumn – Column number where statement ends.

ExecutionCount

Number of times the statement is exercised during test execution.

Kind and Text

Kind of statement and text of the statement, for instance:

Kind: "stmt"Text: statement upto semicolon
Kind: "for"Text: for loop body
Kind: "fcn/enter"Text: function body including braces
Kind: "decl"Text: declaration upto semicolon

Examples

collapse all

This example shows how to get an overview of statement coverage after executing your C/C++ tests.

In general, you generate and manage Polyspace® Test™ 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.

  1. Import the required modules:

    import polyspace.project, polyspace.test
import os

  2. Add source files and xUnit test files to a project. This example uses some example source and test files available with a Polyspace Test installation. Instead, you can use your own sources and tests.

    examples_path = os.path.join(polyspace.__install_path__, "polyspace", 
                            "examples", "pstest", "Getting_Started_Example")
polyspaceProject = polyspace.project.Project("newProject")
polyspaceProject.Code.Files.add(os.path.join(examples_path, "sources", "utils.c"))
polyspaceProject.IncludePaths.add(os.path.join(examples_path, "includes"))
polyspaceProject.Tests.Files.add(os.path.join(examples_path, "tests", "test.c"))

  3. Set the coverage metric level to STATEMENT in the active test configuration of the project:

    coverageMetricLevel = polyspace.project.CoverageMetricLevel.DECISION
polyspaceProject.ActiveTestConfiguration.CoverageOptions.Level = coverageMetricLevel
    For more information on coverage metric levels, see Coverage metrics (-cov-metric-level).

  4. Run the tests added to the project with code coverage computation enabled.

    res = polyspace.test.run(
      polyspaceProject,
      ProfilingSelection=polyspace.test.ProfilingSelection.COVERAGE
)

  5. Print an overview of statement coverage.

    # Read code coverage results
profilingResults = res.Profiling
coverageResults = profilingResults.Coverage

# Read statement coverage results
statementCoverageResults = coverageResults.getCoverageInfo("statement")

# Print condition coverage overview
statementCoveragePercent = ((statementCoverageResults.CoveredCount 
                           + statementCoverageResults.JustifiedCount) 
                           / statementCoverageResults.TotalCount) * 100
print(f"{statementCoveragePercent} %")

This example shows how to find the line numbers of statements that were not covered during test execution.

In general, you generate and manage Polyspace Test 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.

  1. Import the required modules:

    import polyspace.project
import polyspace.test
import os

  2. Add source files and xUnit test files to a project. This example uses some example source and test files available with a Polyspace Test installation. Instead, you can use your own sources and tests.

    examples_path = os.path.join(polyspace.__install_path__, "polyspace", 
                            "examples", "pstest", "Getting_Started_Example")
polyspaceProject = polyspace.project.Project("newProject")
polyspaceProject.Code.Files.add(os.path.join(examples_path, "sources", "utils.c"))
polyspaceProject.IncludePaths.add(os.path.join(examples_path, "includes"))
polyspaceProject.Tests.Files.add(os.path.join(examples_path, "tests", "test.c"))

  3. Set the coverage metric level to STATEMENT in the active test configuration of the project:

    coverageMetricLevel = polyspace.project.CoverageMetricLevel.DECISION
polyspaceProject.ActiveTestConfiguration.CoverageOptions.Level = coverageMetricLevel
    For more information on coverage metric levels, see Coverage metrics (-cov-metric-level).

  4. Run the tests added to the project with code coverage computation enabled.

    res = polyspace.test.run(
      polyspaceProject,
      ProfilingSelection=polyspace.test.ProfilingSelection.COVERAGE
)

  5. Print the line numbers of statements that were not covered during test execution.

    # Read code coverage results
profilingResults = res.Profiling
coverageResults = profilingResults.Coverage

# Read statement coverage results
statementCoverageResults = coverageResults.getCoverageInfo("statement")

# Loop through statement coverage details.
# Print line numbers of statements that were not covered.
for details in statementCoverageResults.Details:
    if not details.IsCovered:
        print(f"Line number {details.SourceLocation.StartLine} in {details.File}")

    If you use the example source and test files, you see an output in the format:

    lineNumber in fileName
    For instance:
    Line 108 in path\to\utils.c

Version History

Introduced in R2024b

See Also

Topics