matlab.unittest.plugins.CodeCoveragePlugin.forNamespace

R2026b

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

Create plugin that collects code coverage information for namespaces

Renamed from matlab.unittest.plugins.CodeCoveragePlugin.forPackage in R2024a

expand all in page

Syntax

plugin = matlab.unittest.plugins.CodeCoveragePlugin.forNamespace(namespace)
plugin = matlab.unittest.plugins.CodeCoveragePlugin.forNamespace(namespace,Name=Value)

Description

plugin = matlab.unittest.plugins.CodeCoveragePlugin.forNamespace(namespace) creates a plugin that collects code coverage information for source code in the specified namespace and generates an HTML code coverage report from the information. You can specify one or more namespaces when calling the method.

plugin = matlab.unittest.plugins.CodeCoveragePlugin.forNamespace(namespace,Name=Value) specifies options using one or more name-value arguments. For example, plugin = matlab.unittest.plugins.CodeCoveragePlugin.forNamespace("myNamespace",IncludingInnerNamespaces=true) creates a plugin that generates an HTML code coverage report for source code in the specified namespace and any of its inner namespaces.

example

Input Arguments

expand all

Name of the namespace containing source code, specified as a string array, character vector, or cell array of character vectors.

Example: "myNamespace"

Example: ["namespaceA" "namespaceB.innerNamespace"]

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: plugin = matlab.unittest.plugins.CodeCoveragePlugin.forNamespace("myNamespace",IncludingInnerNamespaces=true)

Option to include source code in the inner namespaces of namespace, specified as a numeric or logical 0 (false) or 1 (true). By default, the plugin reports only on the source code in namespace and ignores source code defined in its inner namespaces.

Format for accessing the code coverage information, specified as a row vector of matlab.unittest.plugins.codecoverage.CoverageFormat objects. If you specify multiple CoverageFormat objects, the plugin provides access to the information in each corresponding coverage format.

The plugin supports these CoverageFormat subclasses:

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

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:

  • "statement" — Statement and function coverage

  • "decision" (requires MATLAB Test) — Decision coverage

  • "condition" (requires MATLAB Test) — Condition coverage

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

  • "type-size" (requires MATLAB Test) — Data type and size coverage

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 Code Coverage for MATLAB Source Code (MATLAB Test).

By default, if you have a MATLAB Test license, the plugin collects information about line and decision (branch) coverage with the Cobertura XML format, and all structural coverage with other formats. Otherwise, the plugin collects information about line coverage with the Cobertura XML format, and statement and function coverage with other formats.

Example: Metrics="mcdc" (all structural coverage)

Example: Metrics=["statement" "type-size"] (statement, function, and data type and size coverage)

Example: Metrics=["mcdc" "type-size"] (all structural coverage and data type and size coverage)

Since R2024b

Location of the coverage filters to apply, specified as a string array, character vector, or cell array of character vectors. If you have a MATLAB Test license, you can use this argument to specify an XML file that includes the coverage filters previously created for the source code under test. The value can be a path relative to the current folder or an absolute path.

For example, suppose that you previously justified the missing coverage for your source code and saved the justifications to a file named myFilters.xml in your current folder. Using the justifications in myFilters.xml, run your tests and produce an interactive HTML code coverage report that filters the blocks of code that are missed by the tests.

import matlab.unittest.plugins.CodeCoveragePlugin
import matlab.unittest.plugins.codecoverage.CoverageReport

runner = testrunner("textoutput");
format = CoverageReport("report");
plugin = CodeCoveragePlugin.forNamespace("myNamespace", ...
    Producing=format,Filter="myFilters.xml");
runner.addPlugin(plugin)

suite = testsuite("MyTestClass");
results = runner.run(suite);

Note

If you are using a MATLAB project to organize your work, then you do not need to specify the Filter argument. The testing framework automatically applies the coverage filters stored in the project.

Example: Filter="myFilters.xml"

Example: Filter="C:\work\myFilters.xml"

Attributes

statictrue

To learn about attributes of methods, see Method Attributes.

Examples

expand all

Open Script

Run a suite of tests and generate a code coverage report for source code in a namespace.

In a namespace named sourceNamespace 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 a namespace named testsNamespace 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 = sourceNamespace.quadraticSolver(1,-3,2);
            expSolution = [2 1];
            testCase.verifyEqual(actSolution,expSolution)
        end
        function imaginarySolution(testCase)
            actSolution = sourceNamespace.quadraticSolver(1,2,10);
            expSolution = [-1+3i -1-3i];
            testCase.verifyEqual(actSolution,expSolution)
        end
        function nonnumericInput(testCase)
            testCase.verifyError(@()sourceNamespace.quadraticSolver(1,"-3",2), ...
                "quadraticSolver:InputMustBeNumeric")
        end
    end
end

Create a test suite from testsNamespace.

suite = testsuite("testsNamespace");

Create a test runner and customize it using a plugin that generates an HTML code coverage report for the code in sourceNamespace. 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");
reportFormat = CoverageReport("coverageReport");
p = CodeCoveragePlugin.forNamespace("sourceNamespace", ...
    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 testsNamespace.SolverTest
...
Done testsNamespace.SolverTest
__________

MATLAB code coverage report has been saved to:
 C:\work\ExampleManager\user.26b_021326\matlab-ex97061601\coverageReport\index.html

Open the main file of the report.

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

Tips

  • To measure the code coverage for source code in a namespace, the parent folder of the namespace must be on the MATLAB path during the test run.

Version History

Introduced in R2014b

expand all

See Also

Functions

Classes

Topics