addCodeCoverage

Class: matlab.buildtool.tasks.TestTask
Namespace: matlab.buildtool.tasks

Enable code coverage collection for TestTask instance

Since R2024a

expand all in page

Syntax

task = addCodeCoverage(task,results)
task = addCodeCoverage(task,results,MetricLevel=level)

Description

task = addCodeCoverage(task,results) enables task to produce the specified code coverage results for the MATLAB® source code defined in its SourceFiles property. The method returns the specified task with an updated CodeCoverageResults property.

Note

To use the addCodeCoverage method, you must first specify your source code by setting the SourceFiles property of the task.

example

task = addCodeCoverage(task,results,MetricLevel=level) also specifies the code coverage metrics to include in results.

Input Arguments

expand all

Task, specified as a matlab.buildtool.tasks.TestTask object with its SourceFiles property specifying the source code.

Code coverage results to produce, specified as one of these values:

The task can produce code coverage results in various formats. If you specify results as a value of type matlab.buildtool.io.File or convertible to matlab.buildtool.io.File, then specify formats by using file extensions:

  • .html — Produce an interactive HTML code coverage report.

  • .xml — Produce code coverage results in Cobertura XML format.

  • .mat — Save the matlab.coverage.Result array to a MAT file.

Specify results as a CoverageFormat vector for maximum flexibility in producing code coverage results. For example, this build file contains one task that:

  • Runs the tests in the current folder and its subfolders and fails the build if any of the tests fail

  • Produces a standalone HTML code coverage report (requires MATLAB Test™) for the source code in the mySource subfolder of the current folder

function plan = buildfile
import matlab.buildtool.tasks.TestTask
import matlabtest.plugins.codecoverage.StandaloneReport

% Create a plan with no tasks
plan = buildplan;

% Add a task to run tests and produce coverage results
plan("test") = TestTask(SourceFiles="mySource").addCodeCoverage( ...
    StandaloneReport("report.html"));
end

Example: "code-coverage/report.html"

Example: ["code-coverage/results.xml" "code-coverage/results.mat"]

Example: matlab.unittest.plugins.codecoverage.CoverageReport(MainFile="report.html",DocumentTitle="My Report")

Level of coverage metrics to include in the code coverage results, specified as one of the values in this table. By default, the task collects information about line coverage with the Cobertura XML format, and statement and function coverage with other formats.

Value of levelTypes of Coverage Included
Cobertura XML FormatOther Formats
"statement"Line coverageStatement and function coverage

"decision" (requires MATLAB Test)

Line and decision coverageStatement, function, and decision coverage

"condition" (requires MATLAB Test)

Line and decision coverageStatement, function, decision, and condition coverage

"mcdc" (requires MATLAB Test)

Line and decision coverageStatement, function, decision, condition, and modified condition/decision coverage (MC/DC)

For example, this build file contains one task that:

  • Runs the tests in the current folder and its subfolders and fails the build if any of the tests fail

  • Produces an interactive HTML code coverage report, including all the supported coverage metrics, for the source code in the mySource subfolder of the current folder

function plan = buildfile
import matlab.buildtool.tasks.TestTask

% Create a plan with no tasks
plan = buildplan;

% Add a task to run tests and produce coverage results
plan("test") = TestTask(SourceFiles="mySource").addCodeCoverage( ...
    "code-coverage/report.html",MetricLevel="mcdc");
end

For more information about coverage types, see Types of Code Coverage for MATLAB Source Code (MATLAB Test).

Data Types: char | string

Examples

expand all

Open Live Script

Produce code coverage results in Cobertura XML format by using the addCodeCoverage method.

Open the example and then navigate to the code_coverage_example folder, which contains a build file, a source file named quadraticSolver.m, and a test file named SolverTest.m. For more information about the source and test files used in this example, see Write Simple Test Case Using Classes.

cd code_coverage_example

This code shows the contents of the build file. The build file contains one task that:

  • Runs the tests in the current folder and its subfolders and fails the build if any of the tests fail

  • Produces code coverage results in Cobertura XML format for the source code in quadraticSolver.m

function plan = buildfile
import matlab.buildtool.tasks.TestTask

% Create a plan with no tasks
plan = buildplan;

% Add a task to run tests and produce coverage results
plan("test") = TestTask(SourceFiles="quadraticSolver.m").addCodeCoverage( ...
    "code-coverage/results.xml");
end

Run the "test" task. The task runs the tests and saves the coverage results to the specified location in your current folder. In this example, all the tests pass, and the task runs successfully.

buildtool test
** Starting test
...

Test Summary:
    Total Tests: 3
         Passed: 3
         Failed: 0
     Incomplete: 0
       Duration: 0.025416 seconds testing time.
                 

Code Coverage:
    Cobertura: code-coverage\results.xml
** Finished test

Version History

Introduced in R2024a

expand all

See Also

Functions

Classes

Topics