Main Content

selectIf

Class: matlab.unittest.TestSuite
Package: matlab.unittest

Select test suite elements that satisfy conditions

expand all in page

Syntax

newsuite = selectIf(suite,s)
newsuite = selectIf(suite,Name,Value)

Description

example

newsuite = selectIf(suite,s) selects from suite the test elements that satisfy the conditions specified by the selector, s, and returns them in the TestSuite array, newsuite.

example

newsuite = selectIf(suite,Name,Value) creates a TestSuite array with additional options specified by one or more Name,Value pair arguments.

Input Arguments

suite

Set of tests, specified as a matlab.unittest.TestSuite array.

s

Selector, specified as an instance of a class from the matlab.unittest.selector package.

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.

BaseFolder

Name of the folder that contains the file defining the tests, specified as a string array, character vector, or cell array of character vectors. This argument filters TestSuite array elements. For the testing framework to include a test in the suite, the Test element must be contained in one of the base folders specified by BaseFolder. If none of the Test elements matches a base folder, an empty test suite is returned. Use the wildcard character * to match any number of characters. Use the question mark character ? to match a single character.

Name

Name of the suite element, specified as a string array, character vector, or cell array of character vectors. This argument filters TestSuite array elements. For the testing framework to include a test in the suite, the Name property of the Test element must match one of the names specified by Name. If none of the Test elements has a matching name, an empty test suite is returned. Use the wildcard character * to match any number of characters. Use the question mark character ? to match a single character.

ParameterProperty

Name of a test class property that defines a parameter used by the test suite element, specified as a string array, character vector, or cell array of character vectors. This argument filters TestSuite array elements. For the testing framework to include a test in the suite, the Parameterization property of the Test element must contain at least one of the property names specified by ParameterProperty. If none of the Test elements has a matching property name, an empty test suite is returned. Use the wildcard character * to match any number of characters. Use the question mark character ? to match to a single character.

ParameterName

Name of a parameter used by the test suite element, specified as a string array, character vector, or cell array of character vectors. 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.

The ParameterName argument filters TestSuite array elements. For the testing framework to include a test in the suite, the Parameterization property of the Test element must contain at least one of the parameter names specified by ParameterName. If none of the Test elements has a matching parameter name, an empty test suite is returned. Use the wildcard character * to match any number of characters. Use the question mark character ? to match a single character.

ProcedureName

Name of the test procedure, specified as a string array, character vector, or cell array of character vectors. This argument filters TestSuite array elements. For the testing framework to include a test in the suite, the ProcedureName property of the Test element must match one of the procedure names specified by ProcedureName. If none of the Test elements has a matching procedure name, an empty test suite is returned. Use the wildcard character * to match any number of characters. Use the question mark character ? to match a single character.

In a class-based test, the ProcedureName is the name of the test method. In a function-based test, it is the name of the local function that contains the test. In a script-based test, it is a name generated from the test section title. Unlike Name, the name of the test procedure does not include any class or package name or information about parameterization.

Superclass

Name of the class that the test class derives from, specified as a string array, character vector, or cell array of character vectors. This argument filters TestSuite array elements. For the testing framework to include a test in the suite, the TestClass property of the Test element must point to a test class that derives from one of the classes specified by Superclass. If none of the Test elements matches a class, an empty test suite is returned.

Tag

Name of a test tag used by the test suite element, specified as a string array, character vector, or cell array of character vectors. This argument filters TestSuite array elements. For the testing framework to include a test in the suite, the Tags property of the Test element must contain at least one of the tag names specified by Tag. If none of the Test elements has a matching tag name, an empty test suite is returned. Use the wildcard character * to match any number of characters. Use the question mark character ? to match a single character.

Examples

expand all

In your working folder, create the file ExampleTest.m containing the following test class.

classdef (SharedTestFixtures={...
        matlab.unittest.fixtures.PathFixture(fullfile(...
        matlabroot, 'help', 'techdoc', 'matlab_oop', 'examples'))})...
        ExampleTest < matlab.unittest.TestCase
    methods(Test)
        function testPathAdd(testCase)
            % test code
        end
        function testOne(testCase)
            % test code
        end
         function testTwo(testCase)
            % test code
        end
    end
end

At the command prompt, create a test suite from the ExampleTest class.

import matlab.unittest.TestSuite;
import matlab.unittest.selectors.HasSharedTestFixture;
import matlab.unittest.selectors.HasName;
import matlab.unittest.fixtures.PathFixture;
import matlab.unittest.constraints.EndsWithSubstring;
import matlab.unittest.constraints.ContainsSubstring;

suite = TestSuite.fromClass(?ExampleTest)
suite = 

  1×3 Test array with properties:

    Name
    ProcedureName
    TestClass
    BaseFolder
    Parameterization
    SharedTestFixtures
    Tags

Tests Include:
   0 Parameterizations, 1 Unique Shared Test Fixture Class, 0 Tags.

The test suite contains three test elements.

Create a filtered test suite of tests comprising tests with names that contain the case-insensitive text 'pAtH'.

newSuite = selectIf(suite,HasName(ContainsSubstring('pAtH','IgnoringCase',true)))
newSuite = 

  Test with properties:

                  Name: 'ExampleTest/testPathAdd'
         ProcedureName: 'testPathAdd'
             TestClass: "ExampleTest"
            BaseFolder: 'C:\work'
      Parameterization: [0×0 matlab.unittest.parameters.EmptyParameter]
    SharedTestFixtures: [1×1 matlab.unittest.fixtures.PathFixture]
                  Tags: {1×0 cell}

Tests Include:
   0 Parameterizations, 1 Unique Shared Test Fixture Class, 0 Tags.

Only the testPathAdd test is part of the suite.

Alternatively, create the same suite using a name-value pair.

newSuite = selectIf(suite,'Name','*Path*');

However, unlike the ContainsSubstring constraint, the name-value pair does not have an option to ignore case.

Create a filtered suite of tests comprising tests that use a shared path fixture and do not have names ending with 'One'.

newSuite = suite.selectIf(~HasName(EndsWithSubstring('One')) ...
    & HasSharedTestFixture(PathFixture(fullfile(matlabroot, 'help',...
    'techdoc', 'matlab_oop', 'examples'))));
{newSuite.Name}
ans = 

    'ExampleTest/testPathAdd'    'ExampleTest/testTwo'

The test suite contains two tests. All of the tests use the specified path fixture, but the test named 'testOne' is excluded from the suite.

In your working folder, create testZeros.m. This class contains four 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. Six from the parameterized testClass method, two from the parameterized testSize method, and one 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 non-parameterized 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('ParameterProperty','type', 'ParameterName','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, and selecting only 'double' from the parameters results in two test elements — one for each value of 'outSize'.

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

s4 = s.selectIf('ParameterProperty','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 will have a length of 1 (e.g. zeros(3)) or 2 (e.g. 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 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.

Create the following test class in a file, ExampleTest.m, in your current folder.

classdef ExampleTest < matlab.unittest.TestCase
    methods (Test)
        function testA (testCase)
            % test code
        end
    end
    methods (Test, TestTags = {'Unit'})
        function testB (testCase)
            % test code
        end
        function testC (testCase)
            % test code
        end
    end
    methods (Test, TestTags = {'Unit','FeatureA'})
        function testD (testCase)
            % test code
        end
    end
    methods (Test, TestTags = {'System','FeatureA'})
        function testE (testCase)
            % test code
        end
    end
end

At the command prompt, create a test suite from the ExampleTest class and examine the contents.

import matlab.unittest.TestSuite
import matlab.unittest.selectors.HasTag

suite = TestSuite.fromClass(?ExampleTest)
suite = 

  1×5 Test array with properties:

    Name
    ProcedureName
    TestClass
    BaseFolder
    Parameterization
    SharedTestFixtures
    Tags

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

Click the hyperlink for 3 Unique Tags to display all the tags in the suite.

        Tag     
    ____________

    {'FeatureA'}
    {'System'  }
    {'Unit'    }

Select all the test suite elements that have the tag 'Unit'.

s1 = suite.selectIf(HasTag('Unit'))
s1 = 

  1×3 Test array with properties:

    Name
    ProcedureName
    TestClass
    BaseFolder
    Parameterization
    SharedTestFixtures
    Tags

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

Select all the test suite elements that do not contain the tag 'FeatureA'.

s2 =  suite.selectIf(~HasTag('FeatureA'));
{s2.Name}
ans =

  1×3 cell array

    {'ExampleTest/testB'}    {'ExampleTest/testC'}    {'ExampleTest/testA'}

Select all the test suite elements that have no tags.

s3 =  suite.selectIf(~HasTag)
s3 = 

  Test with properties:

                  Name: 'ExampleTest/testA'
         ProcedureName: 'testA'
             TestClass: "ExampleTest"
            BaseFolder: 'C:\work'
      Parameterization: [0×0 matlab.unittest.parameters.EmptyParameter]
    SharedTestFixtures: [0×0 matlab.unittest.fixtures.EmptyFixture]
                  Tags: {1×0 cell}

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

Version History

Introduced in R2014a

expand all

See Also

|