addCodeCoverage

R2026b

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,Metrics=metrics)

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,Metrics=metrics) 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")

Since R2026b

Coverage metrics to collect, specified as a string vector, character vector, or cell vector of character vectors. You can specify one or more values from this list:

  • "statement" — Statement and function coverage

  • "decision" (requires MATLAB Test) — Decision coverage

  • "condition" (requires MATLAB Test) — Condition coverage

  • "mcdc" (requires MATLAB Test) — Modified condition/decision coverage (MC/DC)

  • "type-size" (requires MATLAB Test) — Data type and size coverage

Structural coverage metrics ("statement", "decision", "condition", and "mcdc") are hierarchical, meaning each metric level includes all lower levels. 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 structural 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",Metrics="mcdc");
end

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

By default, if you have a MATLAB Test license, the task collects information about line and decision (branch) coverage with the Cobertura XML format, and all structural coverage with other formats. Otherwise, the task collects information about line coverage with the Cobertura XML format, and statement and function coverage with other formats.

Example: Metrics="decision"

Example: Metrics=["condition" "type-size"]

Output Arguments

expand all

Updated task, returned as a matlab.buildtool.tasks.TestTask object.

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
...
Cobertura XML code coverage report has been saved to:
 C:\work\ExampleManager\user.examples\matlab-ex23465918\code_coverage_example\code-coverage\results.xml

Test Summary:
    Total Tests: 3
         Passed: 3
         Failed: 0
     Incomplete: 0
       Duration: 0.035096 seconds testing time.
                 
Code Coverage:
    Cobertura: C:\work\ExampleManager\user.examples\matlab-ex23465918\code_coverage_example\code-coverage\results.xml
** Finished test

Build Successful:
    1 Task: 0 Failed, 0 Skipped
    2.4726 sec total build time

Version History

Introduced in R2024a

expand all

See Also

Functions

Classes

Topics