Extending Function-Based Tests

Typically, with function-based tests, you create a test file and pass the file name to the runtests function without explicitly creating a suite of Test objects. However, if you create an explicit test suite, additional features are available in function-based testing. These features include:

Test logging and verbosity
Test selection
Plugins to customize the test runner

For additional functionality, consider using Class-Based Unit Tests.

Fixtures for Setup and Teardown Code

When writing tests, use the TestCase.applyFixture method to handle setup and teardown code for actions such as:

Changing the current working folder
Adding a folder to the path
Creating a temporary folder
Suppressing the display of warnings

These fixtures take the place of manually coding the actions in the setupOnce, teardownOnce, setup, and teardown functions of your function-based test.

For example, if you manually write setup and teardown code to set up a temporary folder for each test, and then you make that folder your current working folder, your setup and teardown functions could look like this.

function setup(testCase)
% store current folder
testCase.TestData.origPath = pwd;

% create temporary folder
testCase.TestData.tmpFolder = ['tmpFolder' datestr(now,30)];
mkdir(testCase.TestData.tmpFolder)

% change to temporary folder
cd(testCase.TestData.tmpFolder)
end

function teardown(testCase)
% change to original folder
cd(testCase.TestData.origPath)

% delete temporary folder
rmdir(testCase.TestData.tmpFolder)
end

However, you also can use a fixture to replace both of those functions with just a modified setup function. The fixture stores the information necessary to restore the initial state and performs the teardown actions.

function setup(testCase)
% create temporary folder
f = testCase.applyFixture(matlab.unittest.fixtures.TemporaryFolderFixture);

% change to temporary folder
testCase.applyFixture(matlab.unittest.fixtures.CurrentFolderFixture(f.Folder));
end

Test Logging and Verbosity

Your test functions can use the TestCase.log method. By default, the test runner reports diagnostics logged at verbosity level 1 (Terse). Use the LoggingPlugin.withVerbosity method to respond to messages of other verbosity levels. Construct a TestRunner object, add the LoggingPlugin, and run the suite with the TestRunner.run method. For more information on creating a test runner, see Test Runner Customization.

Test Suite Creation

Calling your function-based test returns a suite of Test objects. You also can use the testsuite function or the TestSuite.fromFile method. If you want a particular test and you know the test name, you can use TestSuite.fromName. If you want to create a suite from all tests in a particular folder, you can use TestSuite.fromFolder.

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 fromFile.
Use a selectors instance and optional constraints instance.

Use these approaches in a suite generation method, such as fromFile, or create a suite and filter it using the TestSuite.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 TestSuite.selectIf method, the testing framework creates a full test suite and then filters it. For large test suites, this approach can have performance implications.

Test Running

There are several ways to run a function-based test.

To Run All Tests	Use Function
In a file	`runtests` with the name of the test file
In a suite	`TestSuite.run` with the suite
In a suite with a custom test runner	`TestRunner.run`. (See Test Runner Customization.)

For more information, see Run Tests for Various Workflows.

Programmatic Access of Test Diagnostics

If you run tests with the runtests function or the run method of TestSuite or TestCase, the test framework uses a DiagnosticsRecordingPlugin plugin that records diagnostics on test results.

After you run tests, you can access recorded diagnostics via the DiagnosticRecord field in the Details property on TestResult. For example, if your test results are stored in the variable results, find the recorded diagnostics for the second test in the suite by invoking records = result(2).Details.DiagnosticRecord.

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

By default, the DiagnosticsRecordingPlugin plugin records qualification failures and logged events at the matlab.unittest.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.

Documentation