polyspace.test.CoverageFilters Class

Namespace: polyspace.test

(Python) Create filters for code coverage results

Since R2025a

Description

Create or load filters for code coverage results. You can use these filters to justify missing coverage results.

Creation

Syntax

coverageFilters = polyspace.test.CoverageFilters()

coverageFilters = polyspace.test.CoverageFilters("filtersFile")

Description

coverageFilters = polyspace.test.CoverageFilters() creates a coverage filters object coverageFilters with an empty Rules property.

coverageFilters = polyspace.test.CoverageFilters("filtersFile") loads a coverage filters object from the file "filtersFile.psprof.filter". You do not need to include the extension (.psprof.filter) in the name of the file you supply to the constructor.

Properties

Rules — List of coverage filter rules

polyspace.test.CoverageFilterRuleList object

List of coverage filter rules, specified as a polyspace.test.CoverageFilterRuleList object. To add a new rule to the list, use one of these polyspace.test.CoverageFilterRuleList methods:

• rules.create(filterableObject, Rationale = "My Rationale", Status = "justified"|"unreviewed")

• rules.createForFile(fileName, Rationale = "My Rationale", Status = "justified"|"unreviewed")

• rules.createForFunction(functionName, fileName, Rationale="My Rationale", Status = "justified"|"unreviewed")

Notes about the creation method syntaxes:

• The filterableObject input of the create method can be one of these objects: polyspace.test.FunctionCoverageDetail, polyspace.test.DecisionCoverageDetail, polyspace.test.ConditionCoverageDetail, polyspace.test.CoverageOutcome, polyspace.test.MCDCCoverageOutcome.

• If you do not explicitly specify the Status input, it is set to "unreviewed".

• The Rationale input is optional if Status is set to "justified".

• Alternatively, you can set Status to one of these polyspace.test.CoverageFilterRuleStatus enum class objects:

  • polyspace.test.CoverageFilterRuleStatus.JUSTIFIED

  • polyspace.test.CoverageFilterRuleStatus.UNREVIEWED

To inspect the individual rules, index into the polyspace.test.CoverageFilterRuleList object. For example:

filters = polyspace.test.CoverageFilters()
rules = filters.Rules
rules.createForFunction("isGreaterThanSpeedLimit", "utils.c", Rationale="Unreachable code", Status="justified")
print(rules[0])

{
    File: 'D:\Getting_Started_Example\sources\utils.c'
    Function: 'checkAgainstSpeedLimit'
    Status: JUSTIFIED
    Kind: FUNCTION
    Rationale: 'Unreachable code'
}

Each rule is an instance of the polyspace.test.CoverageFilterRule class which has these properties:

File	Name of the file to which this rule applies, specified as a string.
Function	Name of the function to which this rule applies, specified as a string.
Status	Status associated with this rule, specified as an enum class object. The values are: CoverageFilterRuleStatus.UNREVIEWED CoverageFilterRuleStatus.JUSTIFIED
Kind	Whether this rule is associated with a file, a function, or a certain kind of detail or outcome object, specified as an enum class object. The values are: CoverageFilterRuleKind.FILE CoverageFilterRuleKind.FUNCTION CoverageFilterRuleKind.CONDITION CoverageFilterRuleKind.DECISION CoverageFilterRuleKind.CONDITION_OUTCOME CoverageFilterRuleKind.DECISION_OUTCOME CoverageFilterRuleKind.MCDC_OUTCOME CoverageFilterRuleKind.RELBOUND_OUTCOME
Rationale	Rationale for the rule, specified as a string.

To remove one or more rules from the list, use these polyspace.test.CoverageFilterRuleList methods:

• rules.pop(myRuleIdx) removes the rule object with index myRuleIdx from the rule list object rules.

• rules.clear() removes all rules included in the rule list object rules.

Methods

Public Methods

save

Save the coverage filters object to a new or existing .psprof.filter file. For example, to save the object coverageFilters to the file filter_rules.psprof.filter, run this command: coverageFilters.save("filter_rules") You do not need to include the file extension .psprof.filter in the input argument that you supply to the save method.

Examples

Add Justification for Unreachable Branch in Code Coverage Results

This example shows how apply a filter to your code coverage results to justify missing code coverage for an unreachable branch in a function.

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

   The other possible values instead of MCDC are STATEMENT, DECISION, CONDITION_DECISION, or NONE. For an explanation of the 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. Extract the code coverage results object coverageResults from the res object.

   profilingResults = res.Profiling
   coverageResults = profilingResults.Coverage

6. In the source file utils.c, the function isGreaterThanSpeedLimit contains an unreachable branch because the if condition in this function is always true. Inspect the decision coverage results for this function.

   result_isGreaterThanSpeedLimit = coverageResults.getCoverageInfo("decision", "utils.c","isGreaterThanSpeedLimit")
   print(result_isGreaterThanSpeedLimit)

   Only one of the two decision outcomes of the if statement is covered by the tests.

   {
       TotalCount: 2
       CoveredCount: 1
       JustifiedCount: 0
       Details: [<DecisionCoverageDetail>]
   }

7. Define a filter to justify all missing code coverage results in the isGreaterThanSpeedLimit function. Apply this filter to the coverageResults object to obtain a filtered object filteredCoverageResults.

   filters = polyspace.test.CoverageFilters()
   filters.Rules.createForFunction("isGreaterThanSpeedLimit", "utils.c", Rationale="Unreachable code", Status="justified")
   filteredCoverageResults = coverageResults.applyFilters(filters)

   Instead of using the createForFunction method, you can also use:

   • The createForFile method to create a rule that applies to an entire file

   • The create method to create a rule that filters a specific decision or a specific decision outcome

   For more information on these methods, see the description of the Rules property of the polyspace.test.CoverageFilters class.

8. Inspect the filtered decision coverage results for the isGreaterThanSpeedLimit function.

   filteredResult_isGreaterThanSpeedLimit = filteredCoverageResults.getCoverageInfo("decision", "utils.c","isGreaterThanSpeedLimit")
   print(filteredResult_isGreaterThanSpeedLimit)

   The previously uncovered decision outcome has now been marked as justified.

   {
       TotalCount: 2
       CoveredCount: 1
       JustifiedCount: 1
       Details: [<DecisionCoverageDetail>]
   }

Version History

Introduced in R2025a