Use Parameters in Class-Based Tests

Often, you need to iteratively run 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.

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 a parameter in your class-based test, specify the data in 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)
        num = {1,2,'3',4,5};
    end
    methods(Test)
        function testDouble(testCase,num)
            testCase.verifyClass(num,'double')
        end
    end
end

Because num 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(num=value1)'}
    {'SampleTest/testDouble(num=value2)'}
    {'SampleTest/testDouble(num=value3)'}
    {'SampleTest/testDouble(num=value4)'}
    {'SampleTest/testDouble(num=value5)'}

When you define a parameterization property, you must specify a default value for the property. Specify the default value as a nonempty cell array or scalar structure with at least one field. MATLAB^® uses the default 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.

You can use local functions in classdef files to assign default values to parameterization properties. However, the local functions must return a cell array or scalar structure.

The testing framework enables you to specify parameters at different test 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. To get started, see Create Basic Parameterized Test.

Specify Parameterization Level

You can parameterize a test class at class setup, method setup, and test levels. Parameterizing at each level requires the parameterization properties to have a specific property attribute. For example, a TestClassSetup method can be parameterized using a property defined in a properties block with the ClassSetupParameter attribute.

This table shows different parameterization levels and the required method and property attributes for each level.

Parameterization Level	Parameterization Definition		Accessible Parameterization Properties
Parameterization Level	Method Attribute	Property Attribute	Accessible Parameterization Properties
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 the ClassSetupParameter attribute.
A parameterized TestMethodSetup method can access parameterization properties only with the MethodSetupParameter or ClassSetupParameter 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

`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 `ParameterCombination` attribute.
`'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 `'exhaustive'` combination, `'pairwise'` combination typically results in fewer tests and therefore faster test execution. While the framework guarantees that tests are created for every pair of values at least one time, you should not rely on the suite size, ordering, or specific set of test suite elements.

'exhaustive' (default)

Methods are invoked for all combinations of parameter values. The testing framework uses this default combination if you do not specify the ParameterCombination attribute.

'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 'exhaustive' combination, 'pairwise' combination typically results in fewer tests and therefore faster test execution. While the framework guarantees that tests are created for every pair of values at least one time, you should not rely on the suite size, ordering, or specific set of test suite elements.

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.

Documentation