Tag Unit Tests

You can use test tags to group tests into categories and then run tests with specified tags. Typical test tags identify a particular feature or describe the type of test.

Tag Tests

To define test tags, use a cell array of meaningful character vectors or a string array. For example, TestTags = {'Unit'} or TestTags = ["Unit","FeatureA"].

• To tag individual tests, use the TestTags method attribute.

• To tag all the tests within a class, use the TestTags class attribute. If you use the TestTags class attribute in a superclass, tests in the subclasses inherit the tags.

This sample test class, ExampleTagTest, uses the TestTags method attribute to tag individual tests.

classdef ExampleTagTest < 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

Several of the tests in class ExampleTagTest are tagged. For example, testD is tagged with 'Unit' and 'FeatureA'. One test, testA, is not tagged.

This sample test class, ExampleTagClassTest, uses a TestTags class attribute to tag all the tests within the class, and a TestTags method attribute to add tags to individual tests.

classdef (TestTags = {'FeatureB'}) ...
        ExampleTagClassTest < matlab.unittest.TestCase
    methods (Test)
        function testF (testCase)
            % test code
        end
    end
    methods (Test, TestTags = {'FeatureC','System'})
        function testG (testCase)
            % test code
        end
    end
    methods (Test, TestTags = {'System','FeatureA'})
        function testH (testCase)
            % test code
        end
    end
end

Each test in class ExampleTagClassTest is tagged with 'FeatureB'. Additionally, individual tests are tagged with various tags including 'FeatureA', 'FeatureC', and 'System'.

Select and Run Tests

There are three ways of selecting and running tagged tests:

• Run Selected Tests Using runtests

• Select Tests Using TestSuite Methods

• Select Tests Using HasTag Selector

Run Selected Tests Using runtests

Use the runtests function to select and run tests without explicitly creating a test suite. Select and run all the tests from ExampleTagTest and ExampleTagClassTest that include the 'FeatureA' tag.

results = runtests({'ExampleTagTest','ExampleTagClassTest'},'Tag','FeatureA');

Running ExampleTagTest
..
Done ExampleTagTest
__________

Running ExampleTagClassTest
.
Done ExampleTagClassTest
__________

runtests selected and ran three tests.

Display the results in a table.

table(results)

ans =

  3×6 table

               Name                Passed    Failed    Incomplete     Duration       Details   
    ___________________________    ______    ______    __________    __________    ____________

    'ExampleTagTest/testE'         true      false     false         0.00039529    [1×1 struct]
    'ExampleTagTest/testD'         true      false     false         0.00045658    [1×1 struct]
    'ExampleTagClassTest/testH'    true      false     false         0.00043899    [1×1 struct]

The selected tests are testE and testD from ExampleTagTest, and testH from ExampleTagClassTest.

Select Tests Using TestSuite Methods

Create a suite of tests from the ExampleTagTest class that are tagged with 'FeatureA'.

import matlab.unittest.TestSuite
sA = TestSuite.fromClass(?ExampleTagTest,'Tag','FeatureA');

Create a suite of tests from the ExampleTagClassTest class that are tagged with 'FeatureC'.

sB = TestSuite.fromFile('ExampleTagClassTest.m','Tag','FeatureC');

Concatenate the suite and view the names of the tests.

suite = [sA sB];
{suite.Name}'

ans =

  3×1 cell array

    'ExampleTagTest/testE'
    'ExampleTagTest/testD'
    'ExampleTagClassTest/testG'

Select Tests Using HasTag Selector

Create a suite of all the tests from the ExampleTagTest and ExampleTagClassTest classes.

import matlab.unittest.selectors.HasTag
sA = TestSuite.fromClass(?ExampleTagTest);
sB = TestSuite.fromFile('ExampleTagClassTest.m');
suite = [sA sB];

Select all the tests that do not have tags.

s1 =  suite.selectIf(~HasTag)

s1 = 

  Test with properties:

                  Name: 'ExampleTagTest/testA'
         ProcedureName: 'testA'
             TestClass: "ExampleTagTest"
            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.

Select all the tests with the 'Unit' tag and display their names.

s2 = suite.selectIf(HasTag('Unit'));
{s2.Name}'

ans =

  3×1 cell array

    'ExampleTagTest/testD'
    'ExampleTagTest/testB'
    'ExampleTagTest/testC'

Select all the tests with the 'FeatureB' or 'System' tag using a constraint.

import matlab.unittest.constraints.IsEqualTo
constraint = IsEqualTo('FeatureB') | IsEqualTo('System');
s3 = suite.selectIf(HasTag(constraint));
{s3.Name}'

ans =

  4×1 cell array

    'ExampleTagTest/testE'
    'ExampleTagClassTest/testH'
    'ExampleTagClassTest/testG'
    'ExampleTagClassTest/testF'