matlab.unittest.plugins.CodeCoveragePlugin class

Package: matlab.unittest.plugins

Plugin that generates a code coverage report

Description

To generate a code coverage report for MATLAB^® source code, add an instance of the matlab.unittest.plugins.CodeCoveragePlugin class to the test runner. As the test suite runs, the plugin generates a report that shows the parts of the source code that were executed by the tests.

The matlab.unittest.plugins.CodeCoveragePlugin class is a handle class.

Creation

Create a CodeCoveragePlugin instance using one of its static methods:

• To create a plugin that generates a code coverage report for source code in files, use the forFile static method.

• To create a plugin that generates a code coverage report for source code in folders, use the forFolder static method.

• To create a plugin that generates a code coverage report for source code in packages, use the forPackage static method.

Methods

Public Methods

matlab.unittest.plugins.CodeCoveragePlugin.forFile	Create plugin that generates code coverage report for files
matlab.unittest.plugins.CodeCoveragePlugin.forFolder	Create plugin that generates code coverage report for folders
matlab.unittest.plugins.CodeCoveragePlugin.forPackage	Create plugin that generates code coverage report for packages

Examples

Generate Code Coverage Report in HTML Format

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

In a folder named sourceFolder 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 roots = 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

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

end

To test the quadraticSolver function, create the SolverTest class in a folder named testsFolder 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

To run the tests and generate a code coverage report, first add sourceFolder to the path.

addpath("sourceFolder")

Create a test suite from testsFolder.

suite = testsuite("testsFolder");

Create a test runner and customize it using a plugin that generates an HTML code coverage report for the code in sourceFolder. Instruct the plugin to write its output to a folder named coverageReport in your current folder.

import matlab.unittest.plugins.CodeCoveragePlugin
import matlab.unittest.plugins.codecoverage.CoverageReport
runner = testrunner("textoutput");
sourceCodeFolder = "sourceFolder";
reportFolder = "coverageReport";
reportFormat = CoverageReport(reportFolder);
p = CodeCoveragePlugin.forFolder(sourceCodeFolder,"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 an HTML code coverage report in the specified folder coverageReport, created in your current folder. By default, the main file of the report is index.html.

results = runner.run(suite);

Running SolverTest
...
Done SolverTest
__________

Code coverage report has been saved to:
 C:\work\coverageReport\index.html

Open the main file of the report.

open(fullfile("coverageReport","index.html"))

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

roots(1) = (-b + sqrt(b^2 - 4*a*c)) / (2*a);
roots(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. Instruct the plugin to write 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)).

More About

MATLAB Source Code

When you create a plugin using one of the static methods of the CodeCoveragePlugin class, the plugin generates a code coverage report for source code in files with a .m, .mlx, or .mlapp extension.

Version History

Introduced in R2014b

R2022a: Add multiple CodeCoveragePlugin instances to the test runner

You can add multiple CodeCoveragePlugin instances to the test runner. If you customize the test runner this way, each plugin must report on a different set of files. For example, run your tests and simultaneously generate HTML code coverage reports for source code in two folders in your current folder.

suite = testsuite(pwd);
runner = testrunner("textoutput");
import matlab.unittest.plugins.CodeCoveragePlugin
p1 = CodeCoveragePlugin.forFolder(folderA);
runner.addPlugin(p1)
p2 = CodeCoveragePlugin.forFolder(folderB);
runner.addPlugin(p2)
results = runner.run(suite);