matlab.unittest.plugins.CodeCoveragePlugin.forFile

Class: matlab.unittest.plugins.CodeCoveragePlugin
Namespace: matlab.unittest.plugins

Create plugin that collects code coverage information for files

Syntax

plugin = matlab.unittest.plugins.CodeCoveragePlugin.forFile(file)

plugin = matlab.unittest.plugins.CodeCoveragePlugin.forFile(file,Name,Value)

Description

plugin = matlab.unittest.plugins.CodeCoveragePlugin.forFile(file) creates a plugin that collects code coverage information for source code in the specified file and generates an HTML code coverage report from the information.

plugin = matlab.unittest.plugins.CodeCoveragePlugin.forFile(file,Name,Value) specifies options using one or more name-value arguments. For example, plugin = matlab.unittest.plugins.CodeCoveragePlugin.forFile("myFile.m","Producing",matlab.unittest.plugins.codecoverage.CoberturaFormat("report.xml")) creates a plugin that generates a Cobertura XML code coverage report for source code in the specified file.

Input Arguments

file — Name of file containing source code

string array | character vector | cell array of character vectors

Name of the file containing source code, specified as a string array, character vector, or cell array of character vectors ending in .m, .mlx, or .mlapp. The value can be a relative path, but the relative path must be in the current folder. Otherwise, the value must be a full path. You can specify multiple files using file.

Example: "myFile.m"

Example: "C:\work\myFile.m"

Example: ["fileA.m" "fileB.mlx" "C:\work\fileC.mlapp"]

Name-Value Arguments

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: plugin = matlab.unittest.plugins.CodeCoveragePlugin.forFile("myFile.m",Producing=matlab.unittest.plugins.codecoverage.CoberturaFormat("report.xml"))

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: plugin = matlab.unittest.plugins.CodeCoveragePlugin.forFile("myFile.m","Producing",matlab.unittest.plugins.codecoverage.CoberturaFormat("report.xml"))

Producing — Format for accessing code coverage information

CoverageReport object (default) | CoberturaFormat object | CoverageResult object | row vector of format objects

Format for accessing the code coverage information, specified as a CoverageReport object, CoberturaFormat object, CoverageResult object, or row vector of these format objects. If you specify multiple format objects, the plugin provides access to the information in each format.

Example: Producing=matlab.unittest.plugins.codecoverage.CoberturaFormat("report.xml")

MetricLevel — Level of coverage metrics to collect

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

Level of coverage metrics to collect, specified as one of the values in this table. By default, the plugin collects statement and function coverage metrics.

Value of MetricLevel	Types of Coverage Included
"statement"	Statement and function coverage
"decision" (requires MATLAB® Test™)	Statement, function, and decision coverage
"condition" (requires MATLAB Test)	Statement, function, decision, and condition coverage
"mcdc" (requires MATLAB Test)	Statement, function, decision, condition, and modified condition/decision coverage (MC/DC)

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

Attributes

static

true

To learn about attributes of methods, see Method Attributes.

Examples

Generate Code Coverage Report in Cobertura XML Format

Run a suite of tests and generate a code coverage report in Cobertura XML format for your source code.

In a file in your current folder, create the quadraticSolver function. The function takes as inputs the coefficients of a quadratic polynomial and returns the roots of that polynomial. If the coefficients are specified as nonnumeric values, the function throws an error.

function r = quadraticSolver(a,b,c)
% quadraticSolver returns solutions to the
% quadratic equation a*x^2 + b*x + c = 0.

if ~isa(a,"numeric") || ~isa(b,"numeric") || ~isa(c,"numeric")
    error("quadraticSolver:InputMustBeNumeric", ...
        "Coefficients must be numeric.")
end

r(1) = (-b + sqrt(b^2 - 4*a*c)) / (2*a);
r(2) = (-b - sqrt(b^2 - 4*a*c)) / (2*a);

end

To test the quadraticSolver function, create the SolverTest class in your current folder. Define three Test methods that test the function against real solutions, imaginary solutions, and nonnumeric inputs.

classdef SolverTest < matlab.unittest.TestCase
    methods(Test)
        function realSolution(testCase)
            actSolution = quadraticSolver(1,-3,2);
            expSolution = [2 1];
            testCase.verifyEqual(actSolution,expSolution)
        end
        function imaginarySolution(testCase)
            actSolution = quadraticSolver(1,2,10);
            expSolution = [-1+3i -1-3i];
            testCase.verifyEqual(actSolution,expSolution)
        end
        function nonnumericInput(testCase)
            testCase.verifyError(@()quadraticSolver(1,"-3",2), ...
                "quadraticSolver:InputMustBeNumeric")
        end
    end
end

Create a test suite from the SolverTest class.

suite = testsuite("SolverTest");

Create a test runner and customize it using a plugin that generates a Cobertura XML code coverage report for the source code in the file quadraticSolver.m. Specify that the plugin writes its output to a file named coverageReport.xml in your current folder.

import matlab.unittest.plugins.CodeCoveragePlugin
import matlab.unittest.plugins.codecoverage.CoberturaFormat
runner = testrunner("textoutput");
sourceCodeFile = "quadraticSolver.m";
reportFile = "coverageReport.xml";
reportFormat = CoberturaFormat(reportFile);
p = CodeCoveragePlugin.forFile(sourceCodeFile,"Producing",reportFormat);
runner.addPlugin(p)

Run the tests. In this example, all the tests pass and the source code receives full coverage. The plugin generates a Cobertura XML code coverage report in your current folder.

results = runner.run(suite);

Running SolverTest
...
Done SolverTest
__________

You can process the generated code coverage report on continuous integration (CI) platforms. You also can view its contents with commands such as open(reportFile) or disp(fileread(reportFile)).

Version History

Introduced in R2017b

R2023a: Programmatically access code coverage results

To programmatically access the results of code coverage analysis for your source code, create a CodeCoveragePlugin instance using a CoverageResult object.

R2023a: Specify the coverage metrics to collect

To specify the coverage metrics to collect, use the MetricLevel name-value argument.