matlab.unittest.selectors.HasParameter class

Package: matlab.unittest.selectors

Selector for TestSuite elements determined by parameterization

Description

The HasParameter selector filters TestSuite array elements determined by parameterization.

Construction

matlab.unittest.selectors.HasParameter constructs a selector for TestSuite elements determined by their parameterization. When you instantiate HasParameter without input arguments, the resulting TestSuite array only contains elements that have parameterized test methods.

matlab.unittest.selectors.HasParameter(Name,Value) constructs a selector with additional options specified by one or more Name,Value pair arguments. The selector filters based on the name of the property that defines a parameter, the name of the parameter, and the value of the parameter. For an element to be selected for the TestSuite array, it must have at least one parameter that satisfies all the conditions.

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.

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

Property	Name of the test class property that defines the parameter used by the test suite element, specified as a character vector, string scalar, or matlab.unittest.constraints.Constraint instance. If the specified property name is a character vector or string scalar, the testing framework creates an IsEqualTo constraint with Property as the expected value.
Name	Name of the parameter used by the test suite element, specified as a character vector, string scalar, or matlab.unittest.constraints.Constraint instance. If the specified name is a character vector or string scalar, the testing framework creates an IsEqualTo constraint with Name as the expected value. MATLAB® generates parameter names based on the test class property that defines the parameters: If the property value is a cell array, MATLAB generates parameter names from the elements of the cell array by taking into account their values, types, and dimensions. If the property value is a structure, MATLAB generates parameter names from the structure fields.
Value	Value of the parameter, specified as any MATLAB data type or as an instance of the matlab.unittest.constraints.Constraint class. If the specified property name is not a constraint, the testing framework creates an IsEqualTo constraint with the input data, Value, as the expected value.

Properties

PropertyConstraint	Condition that the test element’s parameter property name must satisfy to be included in the test suite, specified as an instance of the Constraint in the Property input argument.
NameConstraint	Condition that the test element’s parameter name must satisfy to be included in the test suite, specified as an instance of the Constraint in the Name input argument.
ValueConstraint	Condition that the test element’s parameter property value must satisfy to be included in the test suite, specified as an instance of the Constraint in the Value input argument.

Copy Semantics

Value. To learn how value classes affect copy operations, see Copying Objects.

Examples

Filter Test Suite by Parameterization

In your current folder, create the test class named testZeros. This class contains five test methods.

classdef testZeros < matlab.unittest.TestCase
    properties (TestParameter)
        type = {'single','double','uint16'};
        outSize = struct('s2d',[3 3],'s3d',[2 5 4]);
    end
    
    methods (Test)
        function testClass(testCase, type, outSize)
            testCase.verifyClass(zeros(outSize,type), type);
        end
        
        function testSize(testCase, outSize)
            testCase.verifySize(zeros(outSize), outSize);
        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

The test class contains two parameterized test methods, testClass and testSize.

At the command prompt, create a test suite from the file.

s = matlab.unittest.TestSuite.fromFile('testZeros.m');
{s.Name}'

ans =

  11×1 cell array

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

The suite contains 11 test elements: 6 from the parameterized testClass method, 2 from the parameterized testSize method, and 1 from each of the testDefaultClass, testDefaultSize, and testDefaultValue methods.

Select all of the test elements from parameterized test methods.

import matlab.unittest.selectors.HasParameter

s1 = s.selectIf(HasParameter);
{s1.Name}'

ans =

  8×1 cell array

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

The suite contains the eight test elements from the two parameterized test methods.

Select all of the test elements from nonparameterized test methods.

s2 = s.selectIf(~HasParameter);
{s2.Name}'

ans =

  3×1 cell array

    {'testZeros/testDefaultClass'}
    {'testZeros/testDefaultSize' }
    {'testZeros/testDefaultValue'}

Select all test elements that are parameterized and have a property named 'type' with a parameter name 'double'.

s3 = s.selectIf(HasParameter('Property','type','Name','double'));
{s3.Name}'

ans =

  2×1 cell array

    {'testZeros/testClass(type=double,outSize=s2d)'}
    {'testZeros/testClass(type=double,outSize=s3d)'}

The resulting suite contains two elements. The testClass method is the only method in testZeros that uses the 'type' property. Selecting only 'double' from the parameters results in two test elements — one for each value of 'outSize'.

Select all test elements that a have a parameter defined by a property starting with 't'.

import matlab.unittest.constraints.StartsWithSubstring

s4 = s.selectIf(HasParameter('Property',StartsWithSubstring('t')));
{s4.Name}'

ans =

  6×1 cell array

    {'testZeros/testClass(type=single,outSize=s2d)'}
    {'testZeros/testClass(type=single,outSize=s3d)'}
    {'testZeros/testClass(type=double,outSize=s2d)'}
    {'testZeros/testClass(type=double,outSize=s3d)'}
    {'testZeros/testClass(type=uint16,outSize=s2d)'}
    {'testZeros/testClass(type=uint16,outSize=s3d)'}

The resulting suite contains the six parameterized test elements from the testClass method. The testSize method is parameterized, but the elements from the method are not included in the suite because the method does not use a property that starts with 't'.

Select all test elements that are parameterized and test the zeros function with a 2-D array. A parameter value representing a 2-D array has a length of 1 (for example zeros(3)) or 2 (for example zeros(2,3)).

import matlab.unittest.constraints.HasLength

s5 = s.selectIf(HasParameter('Property','outSize',...
    'Value',HasLength(1)|HasLength(2)));
{s5.Name}'

ans =

  4×1 cell array

    {'testZeros/testClass(type=single,outSize=s2d)'}
    {'testZeros/testClass(type=double,outSize=s2d)'}
    {'testZeros/testClass(type=uint16,outSize=s2d)'}
    {'testZeros/testSize(outSize=s2d)'             }

Select only the test element that tests that the output is a double data type and that it has the correct size for a 2-D array.

s6 = s.selectIf(HasParameter('Property','type','Name','double')...
    & HasParameter('Property','outSize','Name','s2d'))

s6 = 

  Test with properties:

                  Name: 'testZeros/testClass(type=double,outSize=s2d)'
         ProcedureName: 'testClass'
             TestClass: "testZeros"
            BaseFolder: 'C:\work'
      Parameterization: [1×2 matlab.unittest.parameters.TestParameter]
    SharedTestFixtures: [0×0 matlab.unittest.fixtures.EmptyFixture]
                  Tags: {1×0 cell}

Tests Include:
   2 Unique Parameterizations, 0 Shared Test Fixture Classes, 0 Tags.

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.