polyspace.test.CoverageFilters Class

Namespace: polyspace.test

(Python) Create filters for code coverage results

Since R2025a

expand all in page

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

expand all

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

expand all

Examples

collapse all

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

See Also