addGeneratedCodeCoverage

Enable generated code coverage collection for TestTask instance

Since R2026a

expand all in page

Syntax

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

Description

task = addGeneratedCodeCoverage(task,results) enables task to produce the specified code coverage results for the generated C/C++ code in equivalence tests that the task runs. The method returns the specified task with an updated GeneratedCodeCoverageResults property.

Note

Code coverage results for generated C/C++ code are supported only for equivalence tests that build static libraries and execute using software-in-the-loop (SIL) or processor-in-the-loop (PIL) verification. For more information, see Collect Coverage for Generated C/C++ Code in Equivalence Tests.

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

example

Input Arguments

expand all

Task, specified as a matlab.buildtool.tasks.TestTask object.

Generated C/C++ code coverage results to produce, specified as one of these values:

The task can produce generated 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 one of the tests fail

  • Produces a standalone HTML code coverage report for the generated C/C++ code in equivalence tests run by the task

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().addGeneratedCodeCoverage( ...
    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 for generated C/C++ code, 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"

Line and decision coverageStatement, function, and decision coverage

"condition"

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

"mcdc"

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 one of the tests fail

  • Produces an interactive HTML code coverage report, including the supported coverage metrics, for the generated C/C++ code in equivalence tests run by the task

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().addGeneratedCodeCoverage( ...
    "code-coverage/report.html",MetricLevel="mcdc");
end

For more information about coverage types, see Types of Coverage for Generated C/C++ Code in Equivalence Tests.

Data Types: string | char

Output Arguments

expand all

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

Examples

expand all

This example uses:

Open Live Script

Produce a standalone code coverage report for the generated C/C++ code in equivalence tests by using the addGeneratedCodeCoverage method.

Open the example and then navigate to the generated_code_coverage_example folder, which contains a build file named buildfile.m, a function file named myMath.m, and an equivalence test file named tMyMathSIL.m. For more information about the equivalence testing scenario in this example, see Collect Coverage and Generate Report for Equivalence Tests.

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

  • Supports incremental builds because its SourceFiles property specifies the MATLAB source file

  • Produces a standalone HTML code coverage report, including the statement, function, and decision coverage metrics, for the generated C code in equivalence tests

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="myMath.m").addGeneratedCodeCoverage( ...
    StandaloneReport("report.html"), ...
    MetricLevel="decision");
end

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

buildtool test
** Starting test
..
Generating standalone report. Please wait.
    Preparing content for the standalone report.
    Adding content to the standalone report.
    Writing standalone report to file.
Standalone code coverage report has been saved to:
 C:\work\ExampleManager\user.examples\matlabtest-ex61207510\generated_code_coverage_example\report.html

Test Summary:
    Total Tests: 2
         Passed: 2
         Failed: 0
     Incomplete: 0
       Duration: 145.828 seconds testing time.
                 
Generated Code Coverage:
    Standalone Report: C:\work\ExampleManager\user.examples\matlabtest-ex61207510\generated_code_coverage_example\report.html
** Finished test

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

Run the "test" task again. The build tool skips the task because it is up to date. Only TestTask instances with a nonempty SourceFiles property support incremental builds. If the SourceFiles property of the "test" task were not set in this example, the build tool would rerun the task.

buildtool test
** Skipped test (up-to-date)

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

Version History

Introduced in R2026a

See Also

Functions

Classes

Topics