Types of Code Coverage for MATLAB Source Code
When you run tests, you can collect and access code coverage
information for your MATLAB® source code by adding an instance of the CodeCoveragePlugin
class to the test runner. As the tests run, the plugin
collects information that shows the parts of the source code that were executed by the
tests. You can access this information either programmatically or as a code coverage
report.
If you create a CodeCoveragePlugin
instance using a
CoverageResult
or CoverageReport
format object, the plugin supports the following coverage
types, which let you perform a detailed analysis of the source code covered by your
tests.
Statement Coverage
Statement coverage identifies the source code statements that execute when the tests run. Use this type of coverage to determine whether every statement in your source code is executed at least once.
To report statement coverage, MATLAB divides the source code into statements that are separated by a comma, semicolon, or newline character. For example, this code has three statements.
b = 1, a = 2 * (b + 10); x = (b ~= 0) && (a/b > 18.5)
MATLAB divides control flow statements into smaller units for code coverage
reporting. For example, in the following control flow statement code, MATLAB reports coverage for these five units: if x > 0
,
elseif x < 0
, and three calls to the disp
function. To achieve 100% statement coverage, you need tests that execute each of these
units.
if x > 0 disp("x is positive.") elseif x < 0 disp("x is negative.") else disp("x is either zero or NaN.") end
A keyword followed by an expression forms a unit for which MATLAB reports statement coverage. Among keywords that do not require an
expression, MATLAB reports coverage for break
,
catch
, continue
,
return
, and try
. It
ignores keywords such as else
,
end
, and
otherwise
.
In general, MATLAB reports coverage for statements that perform some action on program data
or affect the flow of the program. It ignores code that defines functions, classes, or
class members, such as function [y1,...,yN] = myfun(x1,...,xM)
or
classdef MyClass
.
Function Coverage
Function coverage identifies the functions defined in the source code that execute when the tests run. Use this type of coverage to determine whether every function in your source code was called at least once.
For example, this code contains three defined functions: f
,
root
, and square
. To achieve 100% function
coverage, you need tests that result in each of these functions being called.
function f(x) if x >= 0 root else square end disp(x) function root x = sqrt(x); end function square x = x.^2; end end
Decision Coverage
Decision coverage identifies the decision outcomes achieved by the tests. Use this type of coverage to determine whether every decision in your source code, including every branching statement, has been tested.
Typically, a decision is an expression that affects the flow of the program by
following the MATLAB keywords if
,
elseif
, switch
,
for
, or while
.
Additionally, any assignment statement that contains the short-circuiting logical
operators &&
or ||
is considered a
decision.
For example, this code has three decisions. To achieve 100% decision coverage, you
need tests that evaluate each decision to both true
and
false
.
function y = f(x) z = (x > -3) || (x == -5); % Decision #1 if x > 0 % Decision #2 y = 1; elseif (x < 0) && z % Decision #3 y = -1; else y = 0; end
Condition Coverage
Condition coverage identifies the condition outcomes achieved by the tests. Use this
type of coverage to determine whether every condition in your source code has been
evaluated to both true
and false
.
Conditions are logical expressions that do not contain short-circuiting operators, but
that are part of a decision formed by such operators. For example, this code has two
conditions. To achieve 100% condition coverage, you need tests that evaluate each
condition to both true
and false
.
y = (x > -3) || (x == -5); % A decision with two conditions z = x ~= 0; % Neither a decision nor a condition if x == 0 % A decision but not a condition disp("x is zero.") else disp("x is nonzero.") end
Modified Condition/Decision Coverage (MC/DC)
Modified condition/decision coverage (MC/DC) identifies how tests independently exercise conditions within decisions. To achieve 100% MC/DC, you need tests that satisfy both of these statements:
All conditions within decisions are evaluated to both
true
andfalse
.Every condition within a decision independently affects the outcome of the decision.
Instead of testing for all possible combinations of condition outcomes, satisfying
these statements calls for fewer tests. For example, consider the decision
result = x || (y && z)
, which contains three conditions
x
, y
, and z
. This table
shows how different condition outcomes affect the decision outcome.
Combination | x | y | z | result |
---|---|---|---|---|
1 | false | false | false | false |
2 | false | false | true | false |
3 | false | true | false | false |
4 | false | true | true | true |
5 | true | false | false | true |
6 | true | false | true | true |
7 | true | true | false | true |
8 | true | true | true | true |
To achieve 100% MC/DC for result = x || (y && z)
, testing
for combinations 2, 3, 4, and 6 is sufficient because:
Combinations 2 and 6 show that
x
can take both possible values and also affect the decision outcome independently.Combinations 2 and 4 show that
y
can take both possible values and also affect the decision outcome independently.Combinations 3 and 4 show that
z
can take both possible values and also affect the decision outcome independently.
How to Use Coverage Types
To perform a code coverage analysis using the supported coverage types, specify the
MetricLevel
name-value argument when you create a plugin using
one of the static methods of the CodeCoveragePlugin
class. For example, run
your tests and generate an HTML code coverage report that includes all supported metrics
for the source code in a folder.
import matlab.unittest.plugins.CodeCoveragePlugin import matlab.unittest.plugins.codecoverage.CoverageReport suite = testsuite("MyTestClass"); runner = testrunner("textoutput"); format = CoverageReport; plugin = CodeCoveragePlugin.forFolder("myFolder", ... Producing=format,MetricLevel="mcdc"); runner.addPlugin(plugin) results = runner.run(suite);
The MetricLevel
argument specifies which coverage types to
include in the analysis. This table shows the possible values of
MetricLevel
and the corresponding coverage types.
Value of MetricLevel | Types of Coverage Included |
---|---|
"statement" (default) | Statement and function coverage |
"decision" | Statement, function, and decision coverage |
"condition" | Statement, function, decision, and condition coverage |
"mcdc" | Statement, function, decision, condition, and modified condition/decision coverage |
See Also
Classes
matlab.unittest.plugins.CodeCoveragePlugin
|matlab.coverage.Result
|matlab.unittest.plugins.codecoverage.CoverageResult
|matlab.unittest.plugins.codecoverage.CoverageReport
|matlab.unittest.plugins.codecoverage.CoberturaFormat