Extend Script-Based Tests - MATLAB & Simulink (original) (raw)

Typically, with script-based tests, you create a test file, and pass the file name to the runtests function without explicitly creating a suite ofTest objects. If you create an explicit test suite, there are additional features available in script-based testing. These features include selecting tests and using plugins to customize the test runner. For additional functionality, consider using function-based or class-based unit tests. For more information, see Ways to Write Unit Tests.

Test Suite Creation

To create a test suite from a script-based test directly, use the testsuite function. For a more explicit test suite creation, use the matlab.unittest.TestSuite.fromFile method of TestSuite. Then you can use the run method instead of the runtests function to run the tests. For example, if you have a script-based test in a file rightTriTolTest.m, these three approaches are equivalent.

% Implicit test suite result = runtests('rightTriTolTest.m');

% Explicit test suite suite = testsuite('rightTriTolTest.m'); result = run(suite);

% Explicit test suite suite = matlab.unittest.TestSuite.fromFile('rightTriTolTest.m'); result = run(suite);

Also, you can create a test suite from all the test files in a specified folder using the matlab.unittest.TestSuite.fromFolder method. If you know the name of a particular test in your script-based test file, you can create a test suite from that test using matlab.unittest.TestSuite.fromName.

Test Selection

With an explicit test suite, use selectors to refine your suite. Several of the selectors are applicable only for class-based tests, but you can select tests for your suite based on the test name:

• Use the 'Name' name-value pair argument in a suite generation method, such as matlab.unittest.TestSuite.fromFile.
• Use a selectors instance and optional constraints instance.

Use these approaches in a suite generation method, such as matlab.unittest.TestSuite.fromFile, or create a suite and filter it using the selectIf method. For example, in this listing, the four values of suite are equivalent.

import matlab.unittest.selectors.HasName import matlab.unittest.constraints.ContainsSubstring import matlab.unittest.TestSuite.fromFile

f = 'rightTriTolTest.m'; selector = HasName(ContainsSubstring('Triangle'));

% fromFile, name-value pair suite = TestSuite.fromFile(f,'Name','Triangle')

% fromFile, selector suite = TestSuite.fromFile(f,selector)

% selectIf, name-value pair fullSuite = TestSuite.fromFile(f); suite = selectIf(fullSuite,'Name','Triangle')

% selectIf, selector fullSuite = TestSuite.fromFile(f); suite = selectIf(fullSuite,selector)

If you use one of the suite creation methods with a selector or name-value pair, the testing framework creates the filtered suite. If you use the selectIf method, the testing framework creates a full test suite and then filters it. For large test suites, this approach can have performance implications.

Programmatic Access of Test Diagnostics

In certain cases, the testing framework uses a DiagnosticsRecordingPlugin instance to record diagnostics on test results. The framework uses the plugin by default if you take any of these actions:

• Run tests using the runtests function.
• Run tests using a default test runner created with the testrunner function or the withDefaultPlugins static method.
• Run tests using the run method of the TestSuite or TestCase class.
• Run performance tests using the runperf function or therun method of the TimeExperiment class.

After your tests run, you can access recorded diagnostics using theDiagnosticRecord field in the Details property of TestResult objects. For example, if your test results are stored in the variable results, thenresult(2).Details.DiagnosticRecord contains the recorded diagnostics for the second test in the suite.

The recorded diagnostics are DiagnosticRecord objects. To access particular types of test diagnostics for a test, use the selectFailed,selectPassed, selectIncomplete, andselectLogged methods of the DiagnosticRecord class.

By default, the DiagnosticsRecordingPlugin plugin records qualification failures and logged events at thematlab.automation.Verbosity.Terse level of verbosity. For more information, see DiagnosticsRecordingPlugin and DiagnosticRecord.

Test Runner Customization

Use a TestRunner object to customize the way the framework runs a test suite. With a TestRunner object you can:

• Produce no output in the command window using the withNoPlugins method.
• Run tests in parallel using the runInParallel method.
• Add plugins to the test runner using the addPlugin method.

For example,use test suite, suite, to create a silent test runner and run the tests with the run method of TestRunner.

runner = matlab.unittest.TestRunner.withNoPlugins; results = runner.run(suite);

Use plugins to customize the test runner further. For example, you can redirect output, determine code coverage, or change how the test runner responds to warnings. For more information, see Add Plugin to Test Runner and the plugins classes.

See Also

plugins | selectors | matlab.unittest.constraints | TestRunner | TestSuite

Topics

• Add Plugin to Test Runner