Use External Parameters in Parameterized Test

This example shows how to use external parameters in tests. By using external parameters, you can inject variable inputs into your existing class-based test. To provide test data that is defined outside the test file for the test to use iteratively (via parameterized testing), create an array of matlab.unittest.parameters.Parameter instances, and then use the ExternalParameters name-value argument with TestSuite creation methods, such as fromClass.

Create Function to Test

To set up the example, define the cleanData function in a file named cleanData.m in your current folder. The function accepts a numeric array and returns a cleaned and sorted version of the array. It vectorizes the array, removes the NaN, 0, and Inf entries, and finally sorts the vector.

function Y = cleanData(X)
    Y = X(:);         % Vectorize array
    Y = rmmissing(Y); % Remove NaN
    % Remove 0 and Inf
    idx = (Y==0 | Y==Inf);
    Y = Y(~idx);
    % If array is empty, set to eps
    if isempty(Y)
        Y = eps;
    end
    Y = sort(Y);      % Sort vector
end

Create Parameterized Test Class

Create a parameterized test to test the cleanData function. The test repeats each of the four Test methods for the two data sets that are defined in the properties block.

classdef TestClean < matlab.unittest.TestCase
    properties (TestParameter)
        Data = struct("clean",[5 3 9; 1 42 5; 32 5 2], ...
            "needsCleaning",[1 13; NaN 0; Inf 42]);
    end
    methods (Test)
        function classCheck(testCase,Data)
            act = cleanData(Data);
            testCase.assertClass(act,"double")
        end
        function sortCheck(testCase,Data)
            act = cleanData(Data);
            testCase.verifyTrue(issorted(act))
        end
        function finiteCheck(testCase,Data)
            import matlab.unittest.constraints.IsFinite
            act = cleanData(Data);
            testCase.verifyThat(act,IsFinite)
        end
        function noZeroCheck(testCase,Data)
            import matlab.unittest.constraints.EveryElementOf
            import matlab.unittest.constraints.IsEqualTo
            act = cleanData(Data);
            testCase.verifyThat(EveryElementOf(act),~IsEqualTo(0))
        end
    end    
end

Run the tests. The testing framework runs the eight parameterized tests using the data defined in the test file.

import matlab.unittest.TestSuite
suite = TestSuite.fromClass(?TestClean);
results = suite.run;
table(results)

Running TestClean
........
Done TestClean
__________


ans =

  8×6 table

                        Name                         Passed    Failed    Incomplete    Duration       Details   
    _____________________________________________    ______    ______    __________    _________    ____________

    {'TestClean/classCheck(Data=clean)'         }    true      false       false         0.26906    {1×1 struct}
    {'TestClean/classCheck(Data=needsCleaning)' }    true      false       false         0.00675    {1×1 struct}
    {'TestClean/sortCheck(Data=clean)'          }    true      false       false       0.0064565    {1×1 struct}
    {'TestClean/sortCheck(Data=needsCleaning)'  }    true      false       false        0.002454    {1×1 struct}
    {'TestClean/finiteCheck(Data=clean)'        }    true      false       false         0.03521    {1×1 struct}
    {'TestClean/finiteCheck(Data=needsCleaning)'}    true      false       false       0.0034009    {1×1 struct}
    {'TestClean/noZeroCheck(Data=clean)'        }    true      false       false          1.5687    {1×1 struct}
    {'TestClean/noZeroCheck(Data=needsCleaning)'}    true      false       false       0.0082732    {1×1 struct}

Define External Parameters

Create a data set external to the test file.

A = [NaN 2 0; 1 Inf 3];

Create an array of Parameter instances from the external data set. The fromData static method accepts the name of the parameterization property from the properties block in TestClean and the new data as a cell array (or scalar structure).

import matlab.unittest.parameters.Parameter
newData = {A};
param = Parameter.fromData("Data",newData);

Create a new test suite using the external parameters. The framework appends the characters #ext to the end of the parameter names, indicating that the parameters are defined externally.

suite1 = TestSuite.fromClass(?TestClean,ExternalParameters=param);
{suite1.Name}'

ans =

  4×1 cell array

    {'TestClean/classCheck(Data=2x3_double#ext)' }
    {'TestClean/sortCheck(Data=2x3_double#ext)'  }
    {'TestClean/finiteCheck(Data=2x3_double#ext)'}
    {'TestClean/noZeroCheck(Data=2x3_double#ext)'}

For full control over parameter names in the suite, define the parameters using a structure. Then, run the tests.

newData = struct("commandLineData",A);
param = Parameter.fromData("Data",newData);
suite2 = TestSuite.fromClass(?TestClean,ExternalParameters=param);
{suite2.Name}'
results = suite2.run;

ans =

  4×1 cell array

    {'TestClean/classCheck(Data=commandLineData#ext)' }
    {'TestClean/sortCheck(Data=commandLineData#ext)'  }
    {'TestClean/finiteCheck(Data=commandLineData#ext)'}
    {'TestClean/noZeroCheck(Data=commandLineData#ext)'}

Running TestClean
....
Done TestClean
__________

Test Using Various Data Sets

Create another data set that is stored in an ASCII-delimited file.

B = rand(3);
B(2,4) = 0;
writematrix(B,"myFile.dat")
clear B

Create parameters from the stored data set and A, and then create a test suite.

newData = struct("commandLineData",A,"storedData",readmatrix("myFile.dat"));
param = Parameter.fromData("Data",newData);
suite3 = TestSuite.fromClass(?TestClean,ExternalParameters=param);

To run the tests using parameters defined in the test file and externally, concatenate the test suites. View the suite element names and run the tests.

suite4 = [suite suite3];
{suite4.Name}'
results = suite4.run;

ans =

  16×1 cell array

    {'TestClean/classCheck(Data=clean)'               }
    {'TestClean/classCheck(Data=needsCleaning)'       }
    {'TestClean/sortCheck(Data=clean)'                }
    {'TestClean/sortCheck(Data=needsCleaning)'        }
    {'TestClean/finiteCheck(Data=clean)'              }
    {'TestClean/finiteCheck(Data=needsCleaning)'      }
    {'TestClean/noZeroCheck(Data=clean)'              }
    {'TestClean/noZeroCheck(Data=needsCleaning)'      }
    {'TestClean/classCheck(Data=commandLineData#ext)' }
    {'TestClean/classCheck(Data=storedData#ext)'      }
    {'TestClean/sortCheck(Data=commandLineData#ext)'  }
    {'TestClean/sortCheck(Data=storedData#ext)'       }
    {'TestClean/finiteCheck(Data=commandLineData#ext)'}
    {'TestClean/finiteCheck(Data=storedData#ext)'     }
    {'TestClean/noZeroCheck(Data=commandLineData#ext)'}
    {'TestClean/noZeroCheck(Data=storedData#ext)'     }

Running TestClean
........
Done TestClean
__________

Running TestClean
........
Done TestClean
__________

Use Empty Property Value

Starting in R2026a, parameterization properties can contain an empty cell array or a scalar structure with no fields. For illustrative purposes, define a parameter using an empty cell array. The fromData static method returns a matlab.unittest.parameters.NullParameter object.

newData = {};
param = Parameter.fromData("Data",newData)

param = 

  NullParameter with properties:

    Property: 'Data'
        Name: ''
       Value: {1×0 cell}

When creating a test suite using a NullParameter instance as an external parameter, the framework automatically excludes all the tests associated with the parameter. In this example, the resulting test suite is empty because all tests in the TestClean class depend on the Data property, which the NullParameter instance specifies as having no data values.

suite5 = TestSuite.fromClass(?TestClean,ExternalParameters=param)

suite5 = 

  1×0 Test array with properties:

    Name
    ProcedureName
    TestClass
    BaseFolder
    Parameterization
    SharedTestFixtures
    Tags

Tests Include:
    0 Parameterizations, 0 Shared Test Fixture Classes, 0 Tags, 0 TestRequirements schedules.