Use Parameters in Class-Based Tests
Often, you need to run a series of tests that are different only in terms of test data. For example, you might want to test that a function produces the expected outputs for different inputs. In this case, the test logic is the same and the only difference between tests is the actual and expected values for each function call. With parameterized testing, you can implement code to iteratively run tests using different data values. When a method is parameterized, the testing framework automatically invokes the method for each parameter value. Therefore, you are not required to implement a separate method for each value.
The testing framework enables you to parameterize your test class at different levels. Additionally, when you call a test class method with multiple parameters, you can specify how the method should be invoked for different combinations of the parameters.
How to Write Parameterized Tests
Classes that derive from the matlab.unittest.TestCase
class can
implement test parameterization using framework-specific property and method
attributes. To provide data as parameters in your class-based test, specify the data
using a properties
block with an appropriate parameterization
attribute. Then, pass the parameterization property as an input argument to one or
more methods.
For example, consider the SampleTest
class. The class defines a
parameterized test, because it specifies a property within a
properties
block with the TestParameter
attribute. The property is passed to the Test
method and is used
to perform qualification.
classdef SampleTest < matlab.unittest.TestCase properties (TestParameter) Number = {1,2,'3',4,5}; end methods(Test) function testDouble(testCase,Number) testCase.verifyClass(Number,'double') end end end
Because Number
is a cell array with five elements, the test
class results in a parameterized test suite with five
elements.
suite = testsuite('SampleTest');
{suite.Name}'
ans = 5×1 cell array {'SampleTest/testDouble(Number=value1)'} {'SampleTest/testDouble(Number=value2)'} {'SampleTest/testDouble(Number=value3)'} {'SampleTest/testDouble(Number=value4)'} {'SampleTest/testDouble(Number=value5)'}
The value assigned to a parameterization property must be either a nonempty cell array or a scalar structure with at least one field. MATLAB® uses the property value to specify parameter names and values in the test suite:
If the property value is a cell array of character vectors, MATLAB generates parameter names from the values in the cell array. Otherwise, MATLAB specifies parameter names as
value1
,value2
, …,valueN
.If the property value is a structure, structure fields represent the parameter names and structure values represent the parameter values. To include descriptive parameter names in the suite, define the parameters using a structure instead of a cell array.
How to Initialize Parameterization Properties
When you define a parameterization property, you must initialize the property so that MATLAB can generate parameter names and values. You can initialize the property at either test class load time or test suite creation time:
Class load time: If the property value can be determined at the time MATLAB loads the test class definition, initialize the property using a default value. You can specify the default value in the
properties
block or using a local function in theclassdef
file. For more information about assigning values in a class definition, see Evaluation of Expressions in Class Definitions.When you initialize a parameterization property at class load time, the parameters associated with the property remain fixed for different test runs. Each time you create a suite from the parameterized test class, the framework uses the same parameter names and values to run the tests. See Create Basic Parameterized Test for an example using parameterization properties with default values.
Suite creation time: If you cannot or do not want to determine the parameters at class load time, initialize the property at suite creation time using a static method with the
TestParameterDefinition
attribute. When you initialize a parameterization property with aTestParameterDefinition
method, the parameters associated with the property can vary for different test runs. Each time you create a suite from the parameterized test class, the framework generates fresh parameter names and values to run the tests. For more information, see Define Parameters at Suite Creation Time.
Once you assign a value to a parameterization property, do not modify it. For
example, when you initialize a parameterization property using a default value, you
cannot use a TestParameterDefinition
method to overwrite the
default value.
A parameter might be used by several unit tests. Tests using the same parameter must run independently, without accidentally affecting one another. In addition, a running test must not affect subsequent reruns of the same test. To ensure test run independence, initialize your parameterization properties with value objects. Using handle objects (such as MATLAB graphics objects) as parameter values is not recommended. For more information about the behavior of value and handle objects, see Comparison of Handle and Value Classes.
If you need to test handle objects in your parameterized test, consider
constructing them indirectly by using function handles as parameter values and
invoking those function handles in tests. For example, write a parameterized test to
test the default current point of figures created with the
figure
and uifigure
functions.
classdef FigureTest < matlab.unittest.TestCase properties (TestParameter) FigureType = {@figure, @uifigure}; end methods(Test) function defaultCurrentPoint(testCase,FigureType) fig = FigureType(); testCase.addTeardown(@close,fig) cp = fig.CurrentPoint; testCase.verifyEqual(cp,[0 0]) end end end
Specify Parameterization Level
You can parameterize a test class at three levels: class setup, method setup, and
test. Parameterizing at each level requires the parameterization properties to have
a specific property attribute. For example, at the highest level, a
TestClassSetup
method can be parameterized using a property
defined in a properties
block with the
ClassSetupParameter
attribute. At the lowest level, a
Test
method can be parameterized using a property defined in
a properties
block with the TestParameter
attribute.
This table shows different parameterization levels and the required method and property attributes for each level.
Parameterization Level | Parameterization Definition | Accessible Parameterization Properties | |
---|---|---|---|
Method Attribute | Property Attribute | ||
Class-setup level | TestClassSetup | ClassSetupParameter | ClassSetupParameter |
Method-setup level | TestMethodSetup | MethodSetupParameter | MethodSetupParameter and
ClassSetupParameter |
Test level | Test | TestParameter | TestParameter ,
MethodSetupParameter , and
ClassSetupParameter |
A parameterized method can access parameterization properties depending on the level at which the method is defined:
A parameterized
TestClassSetup
method can access parameterization properties only with theClassSetupParameter
attribute.A parameterized
TestMethodSetup
method can access parameterization properties only with theMethodSetupParameter
orClassSetupParameter
attributes.A parameterized
Test
method can access any parameterization properties.
For an example of how to parameterize a test class at different levels, see Create Advanced Parameterized Test.
Specify How Parameters Are Combined
When you pass more than one parameterization property to a method, you can use the
ParameterCombination
method attribute to specify how
parameters are combined. The testing framework invokes the method for the specified
combinations.
This table shows different parameter combination strategies.
ParameterCombination
Attribute | Method Invocation |
---|---|
'exhaustive' (default) | Methods are invoked for all combinations of parameter
values. The testing framework uses this default combination if
you do not specify the |
'sequential' | Methods are invoked with corresponding values from each parameter. Each parameter must contain the same number of values. For example, if a method is provided with two parameterization properties and each property specifies three parameter values, then the framework invokes the method three times. |
'pairwise' | Methods are invoked for every pair of parameter values at least one time. For example, if a method is provided with three parameterization properties, the testing framework guarantees that the method is invoked for every combination of parameter values specified by any two properties. Compared to
|
You can combine parameters at class-setup, method-setup, and test levels. For
example, use the combined method attributes TestMethodSetup,
ParameterCombination = 'sequential'
to specify sequential combination
of the method-setup-level parameters defined in the properties
block with the MethodSetupParameter
attribute.
For examples of how to combine test parameters, see Create Basic Parameterized Test and Create Advanced Parameterized Test.
Use External Parameters in Tests
When you create a parameterized test, you can redefine the parameters by injecting
inputs into your class-based test. To provide data that is defined outside of the
test file, create a Parameter
instance and use the 'ExternalParameter'
option when creating your test suite. For more information, see Use External Parameters in Parameterized Test.
See Also
matlab.unittest.parameters
| matlab.unittest.parameters.Parameter
| matlab.unittest.TestCase