polyspace.test.DecisionCoverageInfo Class

Namespace: polyspace.test

(Python) Review decision coverage results

Since R2024b

expand all in page

Description

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

Creation

Syntax

decisionCoverageInfo = coverageResults.getCoverageInfo("decision")
decisionCoverageInfo = coverageResults.getCoverageInfo("decision", fileName)
decisionCoverageInfo = coverageResults.getCoverageInfo("decision", fileName, functionName)

Description

decisionCoverageInfo = coverageResults.getCoverageInfo("decision") loads decision coverage results for the entire project:

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

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

Properties

expand all

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

For more information on decision outcomes, see Decision Coverage.

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

For more information on decision outcomes, see Decision Coverage.

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

For more information:

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

PropertyDescription
FileFile containing decision that requires coverage.
FunctionFunction containing decision that requires coverage.
IsCoveredWhether both the true and false outcomes of the decision are covered.
IsJustifiedWhether you justified the uncovered decision outcomes.
RationaleRationale for justification, if you justified the uncovered decision outcomes.
TotalCountTotal number of decision outcomes. This number is 2 for if statements and equal to number of case clauses plus one for switch statements.
CoveredCountNumber of decision outcomes covered.
JustifiedCountNumber of decision outcomes justified.
Outcomes

Details of decision outcomes specified as a list of polyspace.test.CoverageOutcome objects, with each object in the list representing a decision outcome. The object has the following properties:

  • IsCovered – Whether the decision outcome is covered.

  • IsJustified – Whether the decision outcome is uncovered but justified.

  • ExecutionCount – Number of times the decision outcome occurs during test execution.

  • Rationale – Rationale for justification, if the decision outcome is justified.

  • Text – Outcome of the decision to be covered. This property has the value "true" or "false".

Text

Text of the code that involves a decision outcome. For instance, if the decision outcome occurs through an if statement:

if (idx < MAXSIZE)
The Kind property contains the string "if" and the Text property contains the string "idx < MAXSIZE".

Examples

collapse all

This example shows how to see an overview of decision 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 DECISION 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 decision coverage.

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

# Read decision coverage results
decisionCoverageResults = coverageResults.getCoverageInfo("decision")

# Print decision coverage overview
decisionCoveragePercent = ((decisionCoverageResults.CoveredCount 
                           + decisionCoverageResults.JustifiedCount) 
                           / decisionCoverageResults.TotalCount) * 100
print(f"{decisionCoveragePercent} %")

This example shows how to find the decisions in the source code that were not covered or partially 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 DECISION 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 details of decisions that were not covered during test execution.

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

# Read decision coverage results
decisionCoverageResults = coverageResults.getCoverageInfo("decision")

# Loop through decision coverage details.
# Print names of functions with partial coverage.
for details in decisionCoverageResults.Details:
    percentCoverage = ((details.CoveredCount + details.JustifiedCount) / details.TotalCount) * 100
    if percentCoverage < 100:
        print(f"'{details.Text}' in {details.Function} ({details.File})")

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

    decisionText in functionName (fileName)
    For instance:
    'speedReading > limit + SPEED_LIMIT_TOLERANCE' in isGreaterThanSpeedLimit (path\to\utils.c)

Version History

Introduced in R2024b

See Also

Topics