applyFilter

Apply filters to coverage results

Since R2024b

Syntax

newr = applyFilter(r,f)

Description

newr = applyFilter(r,f) applies the coverage filters f to the code coverage results r. The method returns the new coverage results as a matlab.coverage.Result vector.

Input Arguments

r — Code coverage results

matlab.coverage.Result vector

Code coverage results, specified as a matlab.coverage.Result vector.

f — Coverage filters to apply

string array | character vector | cell array of character vectors | matlabtest.coverage.Justification array

Coverage filters to apply to the code coverage results, specified as a string array, character vector, or cell array of character vectors containing file paths, or a matlabtest.coverage.Justification array. To apply coverage filters from XML files, specify the paths of the XML files. If you specify a file path, the value can be a path relative to the current folder or an absolute path.

Example: "myFilters.xml"

Example: "C:\work\myFilters.xml"

Example: myCoverageResults.Filter

Examples

Update Coverage Results Using Justifications

Create a justification to filter a block of code that must be covered by a method other than automated testing, for instance, by interactive testing. Then, use the justification to create new coverage results.

First, open this example to access the required files.

openExample("matlabtest/UpdateCoverageResultsUsingJustificationsExample")

When you open the example, these files appear in your current folder:

• logToFile function — This function appends a string to a file. The function throws a system-dependent error if it cannot open the file.

• LoggingTest test class — This test class contains a test to verify that the logToFile function adds the expected string to a specified file. However, the test class does not test the logToFile function in the case of system-dependent errors because there is a plan to test the errors interactively.

• collectCoverage script — This script provides programmatic access to the statement, function, and decision coverage information for the source code in the file logToFile.m and generates an interactive HTML code coverage report from the produced coverage result.

Run the collectCoverage script to collect code coverage information and produce an interactive code coverage report. Because the test does not achieve a decision outcome in the source code, the code coverage report includes a missed statement and a missed decision outcome.

collectCoverage

Running LoggingTest
.
Done LoggingTest
__________

result = 
  Result with properties:

        Filename: "C:\work\logToFile.m"
    CreationDate: 25-Nov-2024 15:37:23
          Filter: [0×0 matlabtest.coverage.Justification]

Coverage summary (HTML report):
   Function: 1/1 (100%)
   Statement: 5/6 (83.33%)
   Decision: 1/2 (50%)

Use coverageSummary to retrieve information from the coverage results.

  Show all accessible properties of Result

Justify the missing code coverage by following these steps:

1. With Decision selected from the Currently viewing list on the code coverage report, click the if fileID < 0 branching statement in the Source Details section.

2. In the dialog box that appears, enter a reason for the justification and then click OK.

3. Using your system file browser, save the justification to an XML file named myFilter.xml in your current folder.

After saving the justification, you can use the applyFilter and resetFilter methods to create new coverage results. For example, this code creates a coverage result that incorporates the justified outcomes and then generates an interactive code coverage report from the new result.

result1 = result.applyFilter("myFilter.xml")
generateHTMLReport(result1)

This code creates another coverage result by removing the justification applied to result1.

result2 = result1.resetFilter

Version History

Introduced in R2024b

R2025a: Apply coverage filters from files

To apply the coverage filters from an XML file, specify the path of that file as an input to the applyFilter method.