matlab.unittest.selectors.HasName Class

Namespace: matlab.unittest.selectors
Superclasses: matlab.unittest.selectors.Selector

Select TestSuite array elements by name

Description

The matlab.unittest.selectors.HasName class provides a selector for filtering a test suite based on test names.

For a given test file, the name of a test uniquely identifies the smallest runnable portion of the test content. The test name includes the namespace name, filename (excluding the extension), procedure name, and information about parameterization.

Class Attributes

Sealed

true

For information on class attributes, see Class Attributes.

Creation

Description

selector = matlab.unittest.selectors.HasName(name) creates a selector that selects TestSuite array elements whose name matches the specified value.

Input Arguments

name — Name of test

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

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

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

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

This argument sets the Constraint property.

Properties

Constraint — Condition that test name must satisfy

matlab.unittest.constraints.Constraint object

Condition that the test name 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 input 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 test name.

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

Attributes:

GetAccess	public
SetAccess	immutable

Examples

Select Tests by Name

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

In a file named ZerosTest.m in your current folder, create the ZerosTest class, which tests the zeros function.

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.HasName
import matlab.unittest.constraints.ContainsSubstring

Create a test suite from the ZerosTest class. Then, display the names of the TestSuite array elements. Each name includes the class name and the corresponding Test method name. For the parameterized tests, the names also include information about parameterization.

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'               }

Select a specific test using its name. The filtered test suite has a single Test element.

suite1 = suite.selectIf(HasName("ZerosTest/testDefaultClass"));
disp({suite1.Name}')

    {'ZerosTest/testDefaultClass'}

Select all the tests whose name contains "Size" or "Value".

suite2 = suite.selectIf(HasName(ContainsSubstring("Size")) | ...
    HasName(ContainsSubstring("Value")));
disp({suite2.Name}')

    {'ZerosTest/testSize(size=s2d)'}
    {'ZerosTest/testSize(size=s3d)'}
    {'ZerosTest/testDefaultSize'   }
    {'ZerosTest/testDefaultValue'  }

Create a filtered test suite directly from the ZerosTest class by including only tests whose name contains the substring "Class".

suite3 = TestSuite.fromClass(?ZerosTest, ...
    HasName(ContainsSubstring("Class")));
disp({suite3.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/testDefaultClass'               }

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.