matlabtest.coder.plugins.GeneratedCodeCoveragePlugin Class

R2026b

Namespace: matlabtest.coder.plugins
Superclasses: matlab.unittest.plugins.TestRunnerPlugin, matlab.unittest.plugins.Parallelizable

Plugin for code coverage information for generated C/C++ code equivalence tests

Since R2023a

expand all in page

Description

Add an instance of the matlabtest.coder.plugins.GeneratedCodeCoveragePlugin class to the test runner to collect and access code coverage information for generated C/C++ code in an equivalence test. When the test suite runs, the plugin collects information about the parts of the generated C/C++ code that executed. You can access this information programmatically or in the code coverage report.

The matlabtest.coder.plugins.GeneratedCodeCoveragePlugin class is a handle class.

Creation

Description

p = matlabtest.coder.plugins.GeneratedCodeCoveragePlugin creates a plugin that provides access to code coverage information when you run a generated C/C++ code equivalence test.

example

p = matlabtest.coder.plugins.GeneratedCodeCoveragePlugin(Name=Value) specifies options using one or more name-value arguments. For example, p = matlabtest.coder.plugins.GeneratedCodeCoveragePlugin(Metrics="decision") creates a plugin that collects statement, function, and decision coverage metrics.

example

Name-Value Arguments

expand all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: p = matlabtest.coder.plugins.GeneratedCodeCoveragePlugin(Metrics="decision")

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. By default, the plugin collects information about line and decision (branch) coverage with the Cobertura XML format, and all structural coverage with other formats.

  • "statement" — Statement and function coverage

  • "decision" — Decision coverage

  • "condition" — Condition coverage

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

Structural coverage metrics ("statement", "decision", "condition", and "mcdc") are hierarchical, meaning each metric level includes all lower levels. For more information about coverage types, see Types of Coverage for Generated C/C++ Code in Equivalence Tests.

This argument sets the Metrics property.

Example: Metrics="decision"

Coverage filters to apply, specified as a string array, character vector, or cell array of character vectors.

For example, suppose that you previously justified missing coverage in your generated C/C++ equivalence tests and saved the justifications to a file named myGeneratedCodeFilter.xml in your current folder. You can use myGeneratedCodeFilter.xml to filter code coverage outcomes in your tests by using the Filter name-value argument.

import matlab.unittest.plugins.codecoverage.CoverageResult
import matlabtest.coder.plugins.GeneratedCodeCoveragePlugin

format = CoverageResult;
plugin = GeneratedCodeCoveragePlugin( ...
    Producing=format,Filter="myGeneratedCodeFilter.xml");
runner = testrunner("textoutput");
addPlugin(runner,plugin);

suite = testsuite;
results = run(runner,suite);

Example: Filter="myGeneratedCodeFilter.xml"

Data Types: char | string | cell

Properties

expand all

Since R2026b

Coverage metrics to collect, specified as a string vector, character vector, or cell vector of character vectors, and stored as a string vector. To set this property, specify the Metrics name-value argument when you create the plugin. For more information about coverage types, see Types of Coverage for Generated C/C++ Code in Equivalence Tests.

Attributes:

GetAccess
public
SetAccess
immutable

Examples

collapse all

This example shows how to collect coverage and generate a report for a generated C/C++ code equivalence test.

The function myMath takes two numeric inputs and an operation string to indicate if the inputs are added or subtracted.

function y = myMath(a,b,operation) %#codegen
if operation == "add"
    y = a+b;
elseif operation == "subtract"
    y = b-a;
else
    y = [];
end
end

The equivalence test tMyMathSIL uses class properties and class-level setup to generate a static library and specifies that the operation argument can be a variable-size string. The test uses parameterization to execute and verify the generated C code twice, with different inputs each time.

classdef tMyMathSIL < matlabtest.coder.TestCase
    properties
        buildResults;
    end

    methods (TestClassSetup)        
        function generateCode(testCase)           
            operationSize = coder.typeof("add");
            operationSize.StringLength = inf;
            buildInputs = {1,2,operationSize};
            testCase.buildResults = build(testCase,"myMath", ...
                Inputs=buildInputs,Configuration="lib");
        end        
    end

    properties (TestParameter)
        runInputs = {{1,2,"add"},{1,2,"subtract"}};
    end
    
    methods(Test)
        function testSILVsMATLAB(testCase,runInputs)
                executionResults = execute(testCase, ...
                testCase.buildResults,Inputs=runInputs);
            verifyExecutionMatchesMATLAB(testCase,executionResults);
        end        
    end
end

Create a test runner with text output.

runner = matlab.unittest.TestRunner.withTextOutput;

Create an instance of the generated code coverage plugin.

plugin = matlabtest.coder.plugins.GeneratedCodeCoveragePlugin;

Add the plugin to the test runner.

addPlugin(runner,plugin)

Create a test suite from tMyMathSIL.m.

suite = testsuite("tMyMathSIL.m");

Run the test suite with the test runner, which generates the coverage report.

results = run(runner,suite);
Running tMyMathSIL
..
Done tMyMathSIL
__________

C/C++ code coverage report has been saved to:
 C:\Users\jdoe\AppData\Local\Temp\tpc5f66fd8_ae86_433c_8749_20e2b5ecd810\index.html
results = 
  1×2 TestResult array with properties:

    Name
    Passed
    Failed
    Incomplete
    Duration
    Details

Totals:
   2 Passed, 0 Failed, 0 Incomplete.
   23.7352 seconds testing time.

This example shows how to collect MC/DC coverage and generate a report with a specified name and file path for a generated C/C++ code equivalence test.

The function myMath takes two numeric inputs and an operation string to indicate if the inputs are added or subtracted.

function y = myMath(a,b,operation) %#codegen
if operation == "add"
    y = a+b;
elseif operation == "subtract"
    y = b-a;
else
    y = [];
end
end

The equivalence test tMyMathSIL uses class properties and class-level setup to generate a static library and specifies that the operation argument can be a variable-size string. The test uses parameterization to execute and verify the generated C code twice, with different inputs each time.

classdef tMyMathSIL < matlabtest.coder.TestCase
    properties
        buildResults;
    end

    methods (TestClassSetup)        
        function generateCode(testCase)           
            operationSize = coder.typeof("add");
            operationSize.StringLength = inf;
            buildInputs = {1,2,operationSize};
            testCase.buildResults = build(testCase,"myMath", ...
                Inputs=buildInputs,Configuration="lib");
        end        
    end

    properties (TestParameter)
        runInputs = {{1,2,"add"},{1,2,"subtract"}};
    end
    
    methods(Test)
        function testSILVsMATLAB(testCase,runInputs)
            executionResults = execute(testCase, ...
                testCase.buildResults,Inputs=runInputs);
            verifyExecutionMatchesMATLAB(testCase,executionResults);
        end        
    end
end

Create a test runner with text output.

runner = matlab.unittest.TestRunner.withTextOutput;

Create an instance of the coverage report plugin and specify the name and output path for the report.

outputPath = "myArtifacts";
reportName = "myCoverageReport.html";
reportFormat = matlab.unittest.plugins.codecoverage.CoverageReport( ...
    outputPath,MainFile=reportName);

Create an instance of the generated code coverage plugin.

plugin = matlabtest.coder.plugins.GeneratedCodeCoveragePlugin( ...
    Producing=reportFormat);

Add the plugin to the test runner.

addPlugin(runner,plugin)

Create a test suite from tMyMathSIL.m.

suite = testsuite("tMyMathSIL.m");

Run the test suite with the test runner, which generates the coverage report.

results = run(runner,suite);
Running tMyMathSIL
..
Done tMyMathSIL
__________

C/C++ code coverage report has been saved to:
 C:\Users\jdoe\MATLAB\myArtifacts\myCoverageReport.html
results = 
  1×2 TestResult array with properties:

    Name
    Passed
    Failed
    Incomplete
    Duration
    Details

Totals:
   2 Passed, 0 Failed, 0 Incomplete.
   18.9304 seconds testing time.

Limitations

  • You can only collect coverage for C/C++ equivalence tests on Windows® and Linux® platforms.

  • You can only collect coverage for equivalence tests that generate C/C++ code for a LIB target.

Version History

Introduced in R2023a

expand all

See Also

Classes

Functions

Topics