addCodeCoverage

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

Enable code coverage collection for TestTask instance

Since R2024a

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.

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

Input Arguments

task — Task

matlab.buildtool.tasks.TestTask object

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

results — Code coverage results to produce

string vector | character vector | cell vector of character vectors | matlab.buildtool.io.File vector

Code coverage results to produce, specified as a string vector, character vector, cell vector of character vectors, or matlab.buildtool.io.File vector. The task can produce code coverage results in various formats. Specify formats by using file extensions:

• .html — Produce an HTML code coverage report.

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

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

Example: "code-coverage/report.html"

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

level — Level of coverage metrics

"statement" (default) | "decision" | "condition" | "mcdc"

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 statement and function coverage with the HTML or MAT-file format, and line coverage with the Cobertura XML format.

Value of level	Types of Coverage Included
	HTML or MAT-File Format	Cobertura XML Format
"statement"	Statement and function coverage	Line coverage
"decision" (requires MATLAB Test™)	Statement, function, and decision coverage	Line and decision coverage
"condition" (requires MATLAB Test)	Statement, function, decision, and condition coverage	Line and decision coverage
"mcdc" (requires MATLAB Test)	Statement, function, decision, condition, and modified condition/decision coverage (MC/DC)	Line and decision coverage

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 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

Produce Code Coverage Results in Cobertura XML Format

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