polyspace.test.ConditionCoverageInfo Class

Namespace: polyspace.test

(Python) Review condition coverage results

Since R2024b

expand all in page

Description

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

Creation

Syntax

conditionCoverageInfo = coverageResults.getCoverageInfo("condition")
conditionCoverageInfo = coverageResults.getCoverageInfo("condition", fileName)
conditionCoverageInfo = coverageResults.getCoverageInfo("condition", fileName, functionName)

Description

conditionCoverageInfo = coverageResults.getCoverageInfo("condition") loads condition coverage results for the entire project:

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

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

Properties

expand all

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

For more information on condition outcomes, see Condition Coverage.

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

For more information on condition outcomes, see Condition Coverage.

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

For more information:

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

PropertyDescription
FileFile containing condition that requires coverage.
FunctionFunction containing condition that requires coverage.
IsCoveredWhether both the true and false outcomes of the condition are covered.
IsJustifiedWhether you justified the uncovered condition outcomes.
RationaleRationale for justification, if you justified the uncovered condition outcomes.
TotalCountTotal number of condition outcomes. This number is always 2.
CoveredCountNumber of condition outcomes covered.
JustifiedCountNumber of condition outcomes justified.
Outcomes

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

  • IsCovered – Whether the condition outcome is covered.

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

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

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

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

Text

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

if (idx > 0 && idx < MAXSIZE)
The two polyspace.test.ConditionCoverageDetail objects corresponding to the two conditions have the Text properties set to "idx > 0" and "idx < MAXSIZE" respectively.

Examples

collapse all

This example shows how to get an overview of condition 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
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 CONDITION_DECISION in the active test configuration of the project:

    coverageMetricLevel = polyspace.project.CoverageMetricLevel.CONDITION_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 condition coverage.

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

# Read condition coverage results
conditionCoverageResults = coverageResults.getCoverageInfo("condition")

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

This example shows how to find the conditions 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, 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 CONDITION_DECISION in the active test configuration of the project:

    coverageMetricLevel = polyspace.project.CoverageMetricLevel.CONDITION_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 conditions that were not covered during test execution.

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

# Read condition coverage results
conditionCoverageResults = coverageResults.getCoverageInfo("condition")

# Loop through condition coverage details.
# Print names of functions with partial coverage.
for details in conditionCoverageResults.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:

    conditionText in functionName (fileName)
    For instance:
    'speedReading > SPEED_LIMIT_TOLERANCE' in checkAgainstSpeedLimit (path\to\utils.c)

Version History

Introduced in R2024b

See Also

Topics