matlab.unittest.plugins.CodeCoveragePlugin class

Package: matlab.unittest.plugins

Plugin that produces a code coverage report

Description

To produce a line coverage report for MATLAB^® source code, add the CodeCoveragePlugin to the TestRunner. The testing framework runs the tests, and the resulting coverage report indicates the executed lines of code. The coverage report is based on source code located in one or more folders or packages. The source code must be on the MATLAB path and remain on the path during the test run.

The CodeCoveragePlugin uses the MATLAB profiler to determine which lines of code the tests execute. The tests and source code should not interact with the profiler. Before running a suite of tests, the plugin clears any data collected by the profiler.

Construction

Instantiate a CodeCoveragePlugin using one of its static methods.

To report on source code within one or more files, use the forFile static method. To report on source code within one or more folders, use the forFolder static method. To report on source code within one or more packages, use the forPackage static method.

Methods

forFile	Construct `CodeCoveragePlugin` for files
forFolder	Construct `CodeCoveragePlugin` for folders
forPackage	Construct `CodeCoveragePlugin` for packages

Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects.

Examples

collapse all

Generate Code Coverage Report

In a new file, quadraticSolver.m, in your working folder, create the following function.

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

checkInputs

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

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

Create a test for the quadratic solver. In a tests package (a +tests subfolder), create SolverTest.m containing the following test class.

classdef SolverTest < matlab.unittest.TestCase
    % SolverTest tests solutions to the quadratic equation
    % a*x^2 + b*x + c = 0
    
    methods (Test)
        function testRealSolution(testCase)
            actSolution = quadraticSolver(1,-3,2);
            expSolution = [2,1];
            testCase.verifyEqual(actSolution,expSolution)
        end
        function testImaginarySolution(testCase)
            actSolution = quadraticSolver(1,2,10);
            expSolution = [-1+3i, -1-3i];
            testCase.verifyEqual(actSolution,expSolution)
        end
    end
    
end

At the command prompt from within your original working folder, create a test suite from the tests package.

import matlab.unittest.TestSuite
import matlab.unittest.TestRunner
import matlab.unittest.plugins.CodeCoveragePlugin

suite = TestSuite.fromPackage('tests');

Create a test runner.

runner = TestRunner.withTextOutput;

Add CodeCoveragePlugin to the runner and run the tests. Specify that the source code folder is your current working folder. If you have other source code files in your current working folder, they show up in the coverage report. The folder that contains the source code (quadraticSolver.m) must be on the MATLAB search path.

runner.addPlugin(CodeCoveragePlugin.forFolder(pwd))
result = runner.run(suite);

Running tests.SolverTest
..
Done tests.SolverTest
__________

MATLAB creates a code coverage report for the quadratic solver function in a temporary folder.

Code coverage report for quadraticSolver

The checkinputs nested function does not have complete code coverage. Since the tests in SolverTest.m do not pass nonnumeric input to quadraticSolver, MATLAB does not exercise the code that throws an error if the inputs are not numeric. To address the missing coverage, add a test method to test the error condition.

Generate Report in Cobertura Format

In your working folder, create a file quadraticSolver.m with the following function.

function roots = quadraticSolver(a,b,c)
    % quadraticSolver returns solutions to the
    % quadratic equation a*x^2 + b*x + c = 0.
    checkInputs
    roots(1) = (-b + sqrt(b^2 - 4*a*c)) / (2*a);
    roots(2) = (-b - sqrt(b^2 - 4*a*c)) / (2*a);
    
    function checkInputs
        if ~isa(a,'numeric') || ~isa(b,'numeric') || ~isa(c,'numeric')
            error('quadraticSolver:InputMustBeNumeric', ...
                'Coefficients must be numeric.')
        end
    end
end

Create a test class for the quadratic solver in ForFileSolverTest.m.

classdef ForFileSolverTest < matlab.unittest.TestCase
    % SolverTest tests solutions to the quadratic equation
    % a*x^2 + b*x + c = 0
    
    methods (Test)
        function testRealSolution(testCase)
            actSolution = quadraticSolver(1,-3,2);
            expSolution = [2,1];
            testCase.verifyEqual(actSolution,expSolution)
        end
        function testImaginarySolution(testCase)
            actSolution = quadraticSolver(1,2,10);
            expSolution = [-1+3i, -1-3i];
            testCase.verifyEqual(actSolution,expSolution)
        end
    end
end

At the command prompt, create a test suite for ForFileSolverTest.m, and create a test runner.

import matlab.unittest.TestRunner

testFile = 'ForFileSolverTest.m';
suite = testsuite(testFile);
runner = TestRunner.withTextOutput;

Create a plugin that outputs a code coverage report for the source code in Cobertura format.

import matlab.unittest.plugins.CodeCoveragePlugin
import matlab.unittest.plugins.codecoverage.CoberturaFormat

sourceCodeFile = 'quadraticSolver.m';
reportFile = 'CoverageResults.xml';
reportFormat = CoberturaFormat(reportFile);
plugin = CodeCoveragePlugin.forFile(sourceCodeFile,'Producing',reportFormat);

Add the plugin to the test runner and run the tests.

runner.addPlugin(plugin);
result = runner.run(suite);

Running ForFileSolverTest
..
Done ForFileSolverTest
__________

Display the contents of the file with the code coverage results.

disp(fileread(reportFile))

<?xml version="1.0" encoding="utf-8"?>
<coverage branch-rate="NaN" branches-covered="NaN" branches-valid="NaN" complexity="NaN" line-rate="0.8" lines-covered="4" lines-valid="5" timestamp="737000.4343" version="NaN">
   <sources>
      <source>C:\work\</source>
   </sources>
   <packages>
      <package branch-rate="NaN" complexity="NaN" line-rate="0.8" name="">
         <classes>
            <class branch-rate="NaN" complexity="NaN" filename="quadraticSolver.m" line-rate="0.8" name="quadraticSolver">
               <methods/>
               <lines>
                  <line branch="NaN" condition-coverage="NaN" hits="2" number="4"/>
                  <line branch="NaN" condition-coverage="NaN" hits="2" number="5"/>
                  <line branch="NaN" condition-coverage="NaN" hits="2" number="6"/>
                  <line branch="NaN" condition-coverage="NaN" hits="2" number="9"/>
                  <line branch="NaN" condition-coverage="NaN" hits="0" number="10"/>
               </lines>
            </class>
         </classes>
      </package>
   </packages>
</coverage>

Documentation