matlab.unittest.selectors.HasTag Class

Namespace: matlab.unittest.selectors

Select TestSuite array elements by test tag

Description

The matlab.unittest.selectors.HasTag class provides a selector for filtering a test suite based on test tags.

In a class-based test, test tags are specified by the TestTags class-level or method-level attribute of the corresponding TestCase class. For more information, see Tag Unit Tests.

Class Attributes

Sealed

true

For information on class attributes, see Class Attributes.

Creation

Description

selector = matlab.unittest.selectors.HasTag creates a selector that selects any tagged TestSuite array elements.

selector = matlab.unittest.selectors.HasTag(tag) creates a selector that selects tests with the specified tag. For the selector to include a test in the filtered suite, the Tag property of the Test element must contain at least one test tag that matches tag.

Input Arguments

tag — Test tag

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

Test tag, specified as a string scalar, character vector, or matlab.unittest.constraints.Constraint object. Test selection by test tag depends on how you specify tag:

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

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

This argument sets the Constraint property.

Properties

Constraint — Condition that test tag must satisfy

matlab.unittest.constraints.Constraint object

Condition that a test tag 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 tag 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 tag.

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

Attributes:

GetAccess	public
SetAccess	immutable

Examples

Select Tests by Tag

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

In a file named ExampleTest.m in your current folder, create the ExampleTest class, which uses the TestTags method-level attribute to tag individual tests. To simplify the test code, the Test methods in this example use unconditional test failures as placeholders for unimplemented tests.

classdef ExampleTest < matlab.unittest.TestCase
    methods (Test)
        function testA(testCase)
            testCase.verifyFail("Implement the test.")
        end
    end
    methods (Test,TestTags="Unit")
        function testB(testCase)
            testCase.verifyFail("Implement the test.")
        end
        function testC(testCase)
            testCase.verifyFail("Implement the test.")
        end
    end
    methods (Test,TestTags=["Unit" "FeatureA"])
        function testD(testCase)
            testCase.verifyFail("Implement the test.")
        end
    end
    methods (Test,TestTags=["System" "FeatureB"])
        function testE(testCase)
            testCase.verifyFail("Implement the test.")
        end
    end
end

Import the classes used in this example.

import matlab.unittest.TestSuite
import matlab.unittest.selectors.HasTag
import matlab.unittest.constraints.StartsWithSubstring

Create a test suite from the ExampleTest class and display the test names. The suite contains five Test elements.

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

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

Select all the tests that have the tag "Unit".

suite1 = suite.selectIf(HasTag("Unit"));
disp({suite1.Name}')

    {'ExampleTest/testD'}
    {'ExampleTest/testB'}
    {'ExampleTest/testC'}

Select all the tests that have no tags.

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

    {'ExampleTest/testA'}

Create a filtered test suite directly from the ExampleTest class by including only tests that have a tag that starts with "Feature".

suite3 = TestSuite.fromClass(?ExampleTest, ...
    HasTag(StartsWithSubstring("Feature")));
disp({suite3.Name}')

    {'ExampleTest/testE'}
    {'ExampleTest/testD'}

Alternative Functionality

Use the HasTag class for maximum flexibility when filtering a test suite based on test tags. Alternatively, you can create a filtered test suite using the Tag name-value argument. For example:

filteredSuite = matlab.unittest.TestSuite.fromClass(?ExampleTest, ...
    "Tag","Unit");

You can also select and run tagged tests using the Tag name-value argument of the runtests or runperf function. For example:

results = runtests("ExampleTest.m","Tag","Unit");

Version History

Introduced in R2015a