matlab.unittest.plugins.CodeCoveragePlugin.forFile
Class: matlab.unittest.plugins.CodeCoveragePlugin
Namespace: matlab.unittest.plugins
Create plugin that collects code coverage information for files
Syntax
Description
plugin = matlab.unittest.plugins.CodeCoveragePlugin.forFile(
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.file
)
plugin = matlab.unittest.plugins.CodeCoveragePlugin.forFile(
specifies options using one or more name-value arguments. For example,
file
,Name,Value
)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
matlab.unittest.plugins.codecoverage.CoverageReport
object (default) | row vector of matlab.unittest.plugins.codecoverage.CoverageFormat
objects
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")
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 |
| Statement, function, and decision coverage |
| Statement, function, decision, and condition coverage |
| 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).
Filter
— Location of coverage filters to apply
string array | character vector | cell array of character vectors
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 a MAT file that contains 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.mat
in your current folder. Using the
existing matlabtest.coverage.Justification
objects in
myFilters.mat
, 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.forFile("myFile.m", ... Producing=format,MetricLevel="mcdc",Filter="myFilters.mat"); 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.mat"
Example: Filter="C:\work\myFilters.mat"
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 R2017bR2024b: Reuse existing coverage filters
If you have a MATLAB
Test license, you can specify the Filter
name-value argument
to apply the coverage filters previously created for the source code under test.
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.
See Also
Functions
matlab.unittest.plugins.CodeCoveragePlugin.forFolder
|matlab.unittest.plugins.CodeCoveragePlugin.forNamespace
Classes
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)