matlab.unittest.selectors.HasParameter Class

Namespace: matlab.unittest.selectors

Select TestSuite array elements by parameterization

Description

The matlab.unittest.selectors.HasParameter class provides a selector for filtering a test suite based on parameterization. For more information about parameterized tests, see Use Parameters in Class-Based Tests.

Class Attributes

Sealed

true

For information on class attributes, see Class Attributes.

Creation

Description

selector = matlab.unittest.selectors.HasParameter creates a selector that selects any parameterized TestSuite array elements.

selector = matlab.unittest.selectors.HasParameter(Name,Value) creates a selector with additional options specified by one or more name-value arguments. For example, selector = matlab.unittest.selectors.HasParameter("Property","type") creates a selector that selects all the parameterized tests with the parameterization property "type".

Input Arguments

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: selector = matlab.unittest.selectors.HasParameter(Property="type")

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: selector = matlab.unittest.selectors.HasParameter("Property","type")

Property — Name of parameterization property

string scalar | character vector | matlab.unittest.constraints.Constraint object

Name of the parameterization property, specified as a string scalar, character vector, or matlab.unittest.constraints.Constraint object. Test selection by property name is subject to these conditions:

• If you specify a string scalar or character vector, the name of the parameterization property of the test must be the same as the specified value.

• If you specify a constraint, the name of the parameterization property of the test must satisfy the constraint.

This argument sets the PropertyConstraint property.

Name — Parameter name

string scalar | character vector | matlab.unittest.constraints.Constraint object

Parameter name, specified as a string scalar, character vector, or matlab.unittest.constraints.Constraint object. Test selection by parameter name is subject to these conditions:

• If you specify a string scalar or character vector, the parameter name of the test must be the same as the specified value.

• If you specify a constraint, the parameter name of the test must satisfy the constraint.

This argument sets the NameConstraint property.

Value — Parameter value

any value

Parameter value, specified as a value of any data type. Test selection by parameter value is subject to these conditions:

• If you specify a value other than a constraint, the parameter value of the test must be the same as the specified value.

• If you specify a constraint, the parameter value of the test must satisfy the constraint.

This argument sets the ValueConstraint property.

Properties

PropertyConstraint — Condition that parameterization property must satisfy

matlab.unittest.constraints.Constraint object

Condition that the parameterization property of the test must satisfy for the test to be included in the filtered test suite, returned as a matlab.unittest.constraints.Constraint object.

This property is set by the Property name-value argument:

• If you specify a string scalar or character vector, the testing framework sets the property to the IsEqualTo constraint with the expected value as the specified parameterization property name.

• If you specify a constraint, the testing framework sets the property to the constraint.

Attributes:

GetAccess	public
SetAccess	immutable

NameConstraint — Condition that parameter name must satisfy

matlab.unittest.constraints.Constraint object

Condition that the parameter name of the test must satisfy for the test to be included in the filtered test suite, returned as a matlab.unittest.constraints.Constraint object.

This property is set by the Name name-value argument:

• If you specify a string scalar or character vector, the testing framework sets the property to the IsEqualTo constraint with the expected value as the specified parameter name.

• If you specify a constraint, the testing framework sets the property to the constraint.

Attributes:

GetAccess	public
SetAccess	immutable

ValueConstraint — Condition that parameter value must satisfy

matlab.unittest.constraints.Constraint object

Condition that the parameter value of the test must satisfy for the test to be included in the filtered test suite, returned as a matlab.unittest.constraints.Constraint object.

This property is set by the Value name-value argument:

• If you specify a value other than a constraint, the testing framework sets the property to the IsEqualTo constraint with the expected value as the specified parameter value.

• If you specify a constraint, the testing framework sets the property to the constraint.

Attributes:

GetAccess	public
SetAccess	immutable

Examples

Select Tests by Parameterization

Create filtered test suites by selecting tests using the HasParameter class.

In a file named ZerosTest.m in your current folder, create the ZerosTest class, which tests the zeros function. The class has two parameterized Test methods: testClass and testSize.

classdef ZerosTest < matlab.unittest.TestCase
    properties (TestParameter)
        type = {'single','double','uint16'};
        size = struct("s2d",[3 3],"s3d",[2 5 4]);
    end
    
    methods (Test)
        function testClass(testCase,size,type)
            testCase.verifyClass(zeros(size,type),type)
        end
        
        function testSize(testCase,size)
            testCase.verifySize(zeros(size),size)
        end
        
        function testDefaultClass(testCase)
            testCase.verifyClass(zeros,"double")
        end

        function testDefaultSize(testCase)
            testCase.verifySize(zeros,[1 1])
        end
        
        function testDefaultValue(testCase)
            testCase.verifyEqual(zeros,0)
        end
    end
end

Import the classes used in this example.

import matlab.unittest.TestSuite
import matlab.unittest.selectors.HasParameter
import matlab.unittest.constraints.StartsWithSubstring
import matlab.unittest.constraints.HasLength

Create a test suite from the ZerosTest class and display the test names. The suite contains 11 Test elements.

suite = testsuite("ZerosTest");
disp({suite.Name}')

    {'ZerosTest/testClass(size=s2d,type=single)'}
    {'ZerosTest/testClass(size=s2d,type=double)'}
    {'ZerosTest/testClass(size=s2d,type=uint16)'}
    {'ZerosTest/testClass(size=s3d,type=single)'}
    {'ZerosTest/testClass(size=s3d,type=double)'}
    {'ZerosTest/testClass(size=s3d,type=uint16)'}
    {'ZerosTest/testSize(size=s2d)'             }
    {'ZerosTest/testSize(size=s3d)'             }
    {'ZerosTest/testDefaultClass'               }
    {'ZerosTest/testDefaultSize'                }
    {'ZerosTest/testDefaultValue'               }

Create a filtered test suite by selecting all the parameterized tests.

suite1 = suite.selectIf(HasParameter);
disp({suite1.Name}')

    {'ZerosTest/testClass(size=s2d,type=single)'}
    {'ZerosTest/testClass(size=s2d,type=double)'}
    {'ZerosTest/testClass(size=s2d,type=uint16)'}
    {'ZerosTest/testClass(size=s3d,type=single)'}
    {'ZerosTest/testClass(size=s3d,type=double)'}
    {'ZerosTest/testClass(size=s3d,type=uint16)'}
    {'ZerosTest/testSize(size=s2d)'             }
    {'ZerosTest/testSize(size=s3d)'             }

Select all the tests that are not parameterized.

suite2 = suite.selectIf(~HasParameter);
disp({suite2.Name}')

    {'ZerosTest/testDefaultClass'}
    {'ZerosTest/testDefaultSize' }
    {'ZerosTest/testDefaultValue'}

Select all the parameterized tests with the parameterization property "type" and the parameter name "double".

suite3 = suite.selectIf(HasParameter("Property","type","Name","double"));
disp({suite3.Name}')

    {'ZerosTest/testClass(size=s2d,type=double)'}
    {'ZerosTest/testClass(size=s3d,type=double)'}

Select all the parameterized tests with a parameterization property whose name starts with "t".

suite4 = suite.selectIf(HasParameter("Property",StartsWithSubstring("t")));
disp({suite4.Name}')

    {'ZerosTest/testClass(size=s2d,type=single)'}
    {'ZerosTest/testClass(size=s2d,type=double)'}
    {'ZerosTest/testClass(size=s2d,type=uint16)'}
    {'ZerosTest/testClass(size=s3d,type=single)'}
    {'ZerosTest/testClass(size=s3d,type=double)'}
    {'ZerosTest/testClass(size=s3d,type=uint16)'}

Select all the parameterized tests that test the zeros function when it returns a 2-D array (such as zeros(2) and zeros(2,3)).

suite5 = suite.selectIf(HasParameter("Property","size", ...
    "Value",HasLength(1) | HasLength(2)));
disp({suite5.Name}')

    {'ZerosTest/testClass(size=s2d,type=single)'}
    {'ZerosTest/testClass(size=s2d,type=double)'}
    {'ZerosTest/testClass(size=s2d,type=uint16)'}
    {'ZerosTest/testSize(size=s2d)'             }

Create a filtered test suite directly from the ZerosTest class by including only tests that test for a 2-D double array.

suite6 = TestSuite.fromClass(?ZerosTest, ...
    HasParameter("Property","type","Name","double") & ...
    HasParameter("Property","size","Name","s2d"));
disp({suite6.Name}')

    {'ZerosTest/testClass(size=s2d,type=double)'}

Version History

Introduced in R2014a

R2022b: Parameter names generated from cell arrays are more descriptive

When you assign a nonempty cell array to a parameterization property, the testing framework generates parameter names from the elements of the cell array by taking into account their values, types, and dimensions. In previous releases, if the property value is a cell array of character vectors, the framework generates parameter names from the values in the cell array. Otherwise, the framework specifies parameter names as value1, value2, …, valueN.

If your code uses parameter names to create or filter test suites, replace the old parameter names with the descriptive parameter names. For example, update suite = testsuite(pwd,"ParameterName","value1") by replacing value1 with a descriptive parameter name.