matlab.unittest.TestSuite.fromName

Class: matlab.unittest.TestSuite
Namespace: matlab.unittest

Create test suite from single test name

Syntax

suite = matlab.unittest.TestSuite.fromName(testName)

suite = matlab.unittest.TestSuite.fromName(testName,Name,Value)

Description

suite = matlab.unittest.TestSuite.fromName(testName) creates a test suite composed of a single Test object from the specified test name.

When you create and run a scalar test suite, the test class, function, or script specified by testName must be on the path.

suite = matlab.unittest.TestSuite.fromName(testName,Name,Value) specifies options using one or more name-value arguments. For example, suite = matlab.unittest.TestSuite.fromName(testName,"ExternalParameters",param) uses the specified external parameters to create a scalar test suite.

Input Arguments

testName — Test name

string scalar | character vector

Test name, specified as a string scalar or character vector. 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.

The testName argument corresponds to the Name property of the Test object.

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.

Example: suite = matlab.unittest.TestSuite.fromName(testName,ExternalParameters=param)

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

Example: suite = matlab.unittest.TestSuite.fromName(testName,"ExternalParameters",param)

ExternalParameters — External parameters to use in tests

array of matlab.unittest.parameters.Parameter objects

External parameters to use in the tests, specified as an array of matlab.unittest.parameters.Parameter objects. Use this argument to specify external parameters instead of the existing parameters in a parameterized test. For more information, see Use External Parameters in Parameterized Test.

DependsOn — Names of source files and folders

string vector | character vector | cell vector of character vectors

Names of the source files and folders required by the test, specified as a string vector, character vector, or cell vector of character vectors. When you use this argument, the test must depend on the specified source code. Otherwise, the method returns an empty test suite.

The specified value must represent at least one existing file. If you specify a folder, the framework extracts the paths to the files within the folder.

You must have a MATLAB^® Test™ license to use DependsOn. For more information about selecting tests by source code dependency, see matlabtest.selectors.DependsOn (MATLAB Test).

Example: ["myFile.m" "myFolder"]

Example: ["folderA" "C:\work\folderB"]

Attributes

Static

true

To learn about attributes of methods, see Method Attributes.

Examples

Create Test Suites from Test Names

Create scalar test suites from test names by using the fromName static method.

In a file in your current folder, create the add5 function. The function accepts a numeric input and increments it by 5. If called with a nonnumeric input, the function throws an error.

function y = add5(x)
% add5 - Increment input by 5
if ~isa(x,"numeric")
    error("add5:InputMustBeNumeric","Input must be numeric.")
end
y = x + 5;
end

To test the add5 function, create the Add5Test class in a file named Add5Test.m in your current folder. The class tests the function against numeric and nonnumeric inputs.

classdef Add5Test < matlab.unittest.TestCase
    properties (TestParameter)
        type = {'double','single','int8','int32'};
    end

    methods (Test)
        function numericInput(testCase,type)
            actual = add5(cast(1,type));
            testCase.verifyClass(actual,type)
        end
        function nonnumericInput(testCase)
            testCase.verifyError(@() add5("0"),"add5:InputMustBeNumeric")
        end
    end
end

Import the TestSuite class.

import matlab.unittest.TestSuite

Create a test suite from the Add5Test class and display the test names.

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

    {'Add5Test/numericInput(type=double)'}
    {'Add5Test/numericInput(type=single)'}
    {'Add5Test/numericInput(type=int8)'  }
    {'Add5Test/numericInput(type=int32)' }
    {'Add5Test/nonnumericInput'          }

Create a test suite from the name of the test that corresponds to the nonnumericInput method. The resulting test suite contains a single Test object. Then run the test.

suite1 = TestSuite.fromName("Add5Test/nonnumericInput");
result1 = run(suite1);

Running Add5Test
.
Done Add5Test
__________

Create a scalar test suite from the name of a parameterized test, and run the test.

suite2 = TestSuite.fromName("Add5Test/numericInput(type=single)");
result2 = run(suite2);

Running Add5Test
.
Done Add5Test
__________

Version History

Introduced in R2014a

R2025a: Improved accuracy of test selection by source code dependency

When you select a function-based or class-based test using the DependsOn name-value argument (requires MATLAB Test), the method performs test selection more accurately. If the method can determine which individual tests in the test file depend on the specified source code, then it includes the test only if the test itself depends on the source code. In previous releases, the method includes the test as long as its test file depends on the specified source code.

R2024a: Specify any type of source file when filtering test suite by source code dependency

If you have a MATLAB Test license, you can specify any type of source file using the DependsOn name-value argument. In previous releases, you can specify files only with a .m, .p, .mlx, .mlapp, .mat, or .slx extension.

R2023a: Filter test suite by source code dependency

When creating a test suite from a test name, you can filter the suite by test file dependency on specified source code. Use the DependsOn name-value argument (requires MATLAB Test) to specify the source files and folders.

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.