matlab.unittest.TestSuite.fromRequirements

Create test suite from requirements

Since R2023a

Syntax

suite = matlab.unittest.TestSuite.fromRequirements(requirements)

suite = matlab.unittest.TestSuite.fromRequirements(requirements,selector)

suite = matlab.unittest.TestSuite.fromRequirements(___,Name=Value)

Description

suite = matlab.unittest.TestSuite.fromRequirements(requirements) creates a test suite that contains the tests that verify the specified requirements and returns the test suite as a matlab.unittest.TestSuite array. You must have Requirements Toolbox™ installed to use this method.

The method searches only the tests linked to requirements with the Verify link type. For more information about link types, see Create and Store Links (Requirements Toolbox).

suite = matlab.unittest.TestSuite.fromRequirements(requirements,selector) includes only the tests that satisfy the conditions set by the specified selector.

suite = matlab.unittest.TestSuite.fromRequirements(___,Name=Value) specifies options using one or more name-value arguments in addition to the input argument combinations in previous syntaxes. For example, suite = matlab.unittest.TestSuite.fromRequirements("myRequirementSet.slreqx",DependsOn="myFolder") creates a suite of tests that verify the specified requirement set and that depend on the specified source folder.

Input Arguments

requirements — Requirements

vector of requirement set files | array of slreq.ReqSet objects | array of slreq.Requirement objects

Requirements, specified as a vector of requirement set files, an array of slreq.ReqSet (Requirements Toolbox) objects, or an array of slreq.Requirement (Requirements Toolbox) objects.

Example: "myRequirementSet.slreqx"

selector — Selector

matlab.unittest.selectors.Selector object

Selector, specified as a matlab.unittest.selectors.Selector object.

Example: matlab.unittest.selectors.HasTag

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.fromRequirements("myRequirementSet.slreqx",DependsOn="myFolder")

ExternalParameters — External parameters to use in test

array of matlab.unittest.parameters.Parameter objects

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

BaseFolder — Name of base folder

string array | character vector | cell array of character vectors

Name of the base folder that contains the test file, specified as a string array, character vector, or cell array of character vectors. Use this argument to filter the test suite. For the method to include a test in the filtered suite, the Test element must be in one of the base folders specified by BaseFolder. If none of the Test elements match a base folder, the method returns an empty test suite. Use the wildcard character (*) to match any number of characters. Use the question mark character (?) to match a single character.

For test files defined in namespaces, the base folder is the parent of the top-level namespace folder.

DependsOn — Names of source files and folders

string vector | character vector | cell vector of character vectors

Names of the files and folders that contain source code, specified as a string vector, character vector, or cell vector of character vectors. Use this argument to filter the test suite. The argument filters the test suite by including only the tests that depend on the specified source code. If none of the tests depend on the source code, the method returns an empty test suite.

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

For more information about selecting tests by source code dependency, see matlabtest.selectors.DependsOn.

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

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

Name — Name of test

string array | character vector | cell array of character vectors

Name of the test, specified as a string array, character vector, or cell array of character vectors. Use this argument to filter the test suite. For the method to include a test in the filtered suite, the Name property of the Test element must match one of the names specified by Name. If none of the Test elements have a matching name, the method returns an empty test suite. Use the wildcard character (*) to match any number of characters. Use the question mark character (?) to match a single character.

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.

ParameterProperty — Name of parameterization property

string array | character vector | cell array of character vectors

Name of a test class property that defines a parameter used by the test, specified as a string array, character vector, or cell array of character vectors. Use this argument to filter the test suite. For the method to include a test in the filtered 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 have a matching property name, the method returns an empty test suite. Use the wildcard character (*) to match any number of characters. Use the question mark character (?) to match to a single character.

ParameterName — Name of parameter

string array | character vector | cell array of character vectors

Name of a parameter used by the test, specified as a string array, character vector, or cell array of character vectors. The testing framework generates parameter names based on the test class property that defines the parameters. For example:

• If the property value is a cell array, the framework 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, the framework generates parameter names from the structure fields.

Use this argument to filter the test suite. For the method to include a test in the filtered 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 have a matching parameter name, the method returns an empty test suite. Use the wildcard character (*) to match any number of characters. Use the question mark character (?) to match a single character.

For more information about parameter names, see Use Parameters in Class-Based Tests.

ProcedureName — Name of test procedure

string array | character vector | cell array of character vectors

Name of the test procedure, specified as a string array, character vector, or cell array of character vectors. Use this argument to filter the test suite. For the method to include a test in the filtered suite, the ProcedureName property of the Test element must match one of the procedure names specified by ProcedureName. If none of the Test elements have a matching procedure name, the method returns an empty test suite. 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 name of a test procedure is the name of a Test method that contains the test. In a function-based test, it is the name of a local function that contains the test. In a script-based test, it is a name generated from the test section title. Unlike the name of a test suite element, the name of a test procedure does not include any namespace name, filename, or information about parameterization.

Superclass — Name of class that test class derives from

string array | character vector | cell array of character vectors

Name of the class that the test class derives from, specified as a string array, character vector, or cell array of character vectors. Use this argument to filter the test suite. For the method to include a test in the filtered 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 match a class, the method returns an empty test suite.

Tag — Name of tag

string array | character vector | cell array of character vectors

Name of a tag used by the test, specified as a string array, character vector, or cell array of character vectors. Use this argument to filter the test suite. For the method to include a test in the filtered suite, the Tag property of the Test element must contain at least one of the tag names specified by Tag. If none of the Test elements have a matching tag name, the method returns an empty test suite. Use the wildcard character (*) to match any number of characters. Use the question mark character (?) to match a single character.

Attributes

Static

true

To learn about attributes of methods, see Method Attributes.

Examples

Create Suites of Tests That Verify Requirements

Create suites of tests that verify functional requirements in a project.

Import the TestSuite class.

import matlab.unittest.TestSuite

Open the ShortestPath project and then create a Project object from the currently loaded project. For more information about the project used in this example, see Verify a MATLAB Algorithm by Using Requirements-Based Tests (Requirements Toolbox).

openExample("matlabtest/ShortestPathExample")
proj = currentProject;

Create a test suite from the test files in the project with the Test label. Then, display the names of the TestSuite array elements.

suite = TestSuite.fromProject(proj);
disp({suite.Name}')

    {'graph_unit_tests/check_invalid_start_1'         }
    {'graph_unit_tests/check_invalid_start_2'         }
    {'graph_unit_tests/check_invalid_end_1'           }
    {'graph_unit_tests/check_invalid_end_2'           }
    {'graph_unit_tests/check_longest_path'            }
    {'graph_unit_tests/check_unity_path'              }
    {'graph_unit_tests/check_non_unique'              }
    {'graph_unit_tests/check_no_path'                 }
    {'graph_unit_tests/check_edgeless_graph'          }
    {'graph_unit_tests/check_edgeless_start'          }
    {'graph_unit_tests/check_edgeless_end'            }
    {'graph_unit_tests/check_edgeless_graph_self_loop'}
    {'graph_unit_tests/check_start_end_same'          }
    {'graph_unit_tests/check_invalid_idx_empty_adj'   }

The ShortestPath project contains functional and test requirement sets. Create a suite of tests that verify the functional requirement set.

suite1 = TestSuite.fromRequirements("shortest_path_func_reqs.slreqx");
disp({suite1.Name}')

    {'graph_unit_tests/check_edgeless_end'            }
    {'graph_unit_tests/check_edgeless_graph'          }
    {'graph_unit_tests/check_edgeless_graph_self_loop'}
    {'graph_unit_tests/check_edgeless_start'          }
    {'graph_unit_tests/check_invalid_end_1'           }
    {'graph_unit_tests/check_invalid_end_2'           }
    {'graph_unit_tests/check_invalid_start_1'         }
    {'graph_unit_tests/check_invalid_start_2'         }
    {'graph_unit_tests/check_longest_path'            }
    {'graph_unit_tests/check_no_path'                 }
    {'graph_unit_tests/check_start_end_same'          }
    {'graph_unit_tests/check_unity_path'              }

Create a suite of tests that verify a specific functional requirement.

reqSet = slreq.load("shortest_path_func_reqs.slreqx");
req = reqSet.find(ID="5");
suite2 = TestSuite.fromRequirements(req);
disp({suite2.Name}')

    {'graph_unit_tests/check_edgeless_graph_self_loop'}
    {'graph_unit_tests/check_start_end_same'          }

Create a suite of tests that verify the functional requirements and that have "invalid" as part of their procedure name.

suite3 = TestSuite.fromRequirements(reqSet,ProcedureName="*invalid*");
disp({suite3.Name}')

    {'graph_unit_tests/check_invalid_end_1'  }
    {'graph_unit_tests/check_invalid_end_2'  }
    {'graph_unit_tests/check_invalid_start_1'}
    {'graph_unit_tests/check_invalid_start_2'}

Version History

Introduced in R2023a

R2025a: Improved accuracy of test selection by source code dependency

When you select function-based or class-based tests using the DependsOn name-value argument or the matlabtest.selectors.DependsOn class, the method selects tests that depend on the specified source code with greater accuracy. If the method can determine which individual tests in the test file depend on the source code, then it selects only the dependent tests and excludes the rest. Otherwise, the method includes all the tests in the test file.

In previous releases, the method includes all the tests in a test file if the file depends on the specified source code, without attempting to exclude tests that are not dependent on the source code.

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

You can specify any type of source file using the DependsOn name-value argument or the matlabtest.selectors.DependsOn class. In previous releases, you can specify files only with a .m, .p, .mlx, .mlapp, .mat, or .slx extension.