polyspace.test.MCDCCoverageInfo Class

Namespace: polyspace.test

(Python) Review MCDC coverage results

Since R2024b

Description

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

Creation

Syntax

MCDCCoverageInfo = coverageResults.getCoverageInfo("mcdc")

MCDCCoverageInfo = coverageResults.getCoverageInfo("mcdc", fileName)

MCDCCoverageInfo = coverageResults.getCoverageInfo("mcdc", fileName, functionName)

Description

MCDCCoverageInfo = coverageResults.getCoverageInfo("mcdc") loads MCDC coverage results for the entire project:

• From a polyspace.test.CoverageResults object coverageResults.

• To a polyspace.test.MCDCCoverageInfo object MCDCCoverageInfo.

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

• From a polyspace.test.CoverageResults object coverageResults.

• To a polyspace.test.MCDCCoverageInfo object MCDCCoverageInfo.

MCDCCoverageInfo = coverageResults.getCoverageInfo("mcdc", fileName, functionName) loads MCDC coverage results for the file fileName and function functionName:

• From a polyspace.test.CoverageResults object coverageResults.

• To a polyspace.test.MCDCCoverageInfo object MCDCCoverageInfo.

Properties

TotalCount — Total number of MCDC outcomes to be covered

integer

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

For more information on MCDC outcomes, see MC/DC Coverage.

CoveredCount — Number of MCDC outcomes covered during test execution

integer

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

For more information on MCDC outcomes, see MC/DC Coverage.

JustifiedCount — Number of uncovered MCDC outcomes justified during review

integer

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

For more information:

• On MCDC outcomes, see MC/DC Coverage.

• On justifying coverage outcomes, see Improve or Justify Missing Code Coverage Results.

Details — Details of MCDC coverage

list of polyspace.test.MCDCCoverageDetail objects

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

Property	Description
File	File containing decision that requires MCDC coverage.
Function	Function containing decision that requires MCDC coverage.
IsCovered	Whether both the true and false MCDC outcomes are covered.
IsJustified	Whether you justified the uncovered MCDC outcomes.
Rationale	Rationale for justification, if you justified the uncovered MCDC outcomes.
TotalCount	Total number of MCDC outcomes. This number is always 2.
CoveredCount	Number of MCDC outcomes covered.
JustifiedCount	Number of MCDC outcomes justified.
Outcomes	Details of MCDC outcomes specified as a list of polyspace.test.CoverageOutcome objects, with each object in the list representing a MCDC outcome. The object has the following properties: IsCovered – Whether the MCDC outcome is covered. IsJustified – Whether the MCDC outcome is uncovered but justified. TrueResult – The combination of condition coverage outcomes required for the MCDC outcome to be true. For instance, TF indicates that the first condition must have a true outcome and the second a false outcome for the MCDC outcome to be true. If the combination did not occur during the tests, it is shown in parenthesis. FalseResult – The combination of condition coverage outcomes required for the MCDC outcome to be false. If the combination did not occur during the tests, it is shown in parenthesis. ExecutionCount – Number of times the MCDC outcome occurs during test execution. Rationale – Rationale for justification, if the MCDC outcome is justified. Text – Outcome of the MCDC to be covered. This property has the value "true" or "false".
Text	Text of the code that involves a MCDC outcome. For instance, if the MCDC outcome occurs through an if statement: if (idx > 0 && idx < MAXSIZE) The Text property has the value "if (idx > 0 && idx < MAXSIZE)".

Examples

Print Overview of MCDC Coverage

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

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

   # Read code coverage results
   profilingResults = res.Profiling
   coverageResults = profilingResults.Coverage
   
   # Read MCDC coverage results
   mcdcCoverageResults = coverageResults.getCoverageInfo("mcdc")
   
   
   # Print condition coverage overview
   mcdcCoveragePercent = ((mcdcCoverageResults.CoveredCount 
                              + mcdcCoverageResults.JustifiedCount) 
                              / mcdcCoverageResults.TotalCount) * 100
   print(f"{mcdcCoveragePercent} %")

Print Details of Decisions with Partial MCDC Coverage

This example shows how to find the decisions in the source code that have partial or no MCDC coverage 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 MCDC in the active test configuration of the project:

   coverageMetricLevel = polyspace.project.CoverageMetricLevel.MCDC
   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 have partial or no MCDC coverage during test execution.

   # Read code coverage results
   profilingResults = res.Profiling
   coverageResults = profilingResults.Coverage
   
   # Read MCDC coverage results
   mcdcCoverageResults = coverageResults.getCoverageInfo("mcdc")
   
   # Loop through MCDC coverage details.
   # Print names of functions with partial coverage.
   for details in mcdcCoverageResults.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