matlab.unittest.TestRunner class

Package: matlab.unittest

Class for running tests in matlab.unittest framework

expand all in page

Description

The matlab.unittest.TestRunner class is the fundamental API used to run a suite of tests in the matlab.unittest framework. It runs and operates on TestSuite arrays. Use this class to customize running tests.

The TestRunner class is a sealed class; you cannot derive classes from the TestRunner class.

Construction

To create a simple, silent TestRunner object, call the static withNoPlugins method.

runner = matlab.unittest.TestRunner.withNoPlugins

To create a TestRunner object to run tests from the MATLAB® Command Window, call the static withTextOutput method.

runner = matlab.unittest.TestRunner.withTextOutput

To create a customized TestRunner object, call the addPlugin method.

runner = TestRunner.withNoPlugins;
runner.addPlugin(SomePlugin())

Properties

expand all

Root folder where test run artifacts are stored, specified as a string scalar or character vector. By default, the value of ArtifactsRootFolder is the value from string(tempdir), but you can set it to any writable folder.

Any artifacts produced during a test run are stored in a subfolder within ArtifactsRootFolder. The subfolder name is a unique identifier associated with the specific test run. MATLAB creates a subfolder only if the test run produces artifacts.

For example, assume the ArtifactsRootFolder is set to "C:\Temp" and the automatically-generated test run identifier is "1231df38-7515-4dbe-a869-c3d9f885f379". If a test run produces an artifact, "artifact.txt", the artifact is stored as "C:\Temp\1231df38-7515-4dbe-a869-c3d9f885f379\artifact.txt".

Fixtures that are set up outside the test runner, specified as a scalar or row vector of matlab.unittest.fixtures.Fixture instances. Use this property to specify that the environmental configuration is performed manually instead of automatically during fixture setup and teardown.

The test runner considers these fixtures as already set up and never attempts to set up or tear down any fixtures specified by the PrebuiltFixtures property. If a test suite requires a shared test fixture and that test fixture is specified as a prebuilt fixture, the test runner does not perform set up or tear down actions.

Note

The test runner uses a prebuilt fixture only if it is specified by the PrebuiltFixtures property and is listed as a SharedTestFixture in the test class definition. The test runner does not use a prebuilt fixture if the fixture is registered using the TestCase.applyFixture method.

Methods

addPluginAdd plugin to TestRunner object
runRun all tests in TestSuite array
runInParallelRun all tests in TestSuite array in parallel
withNoPluginsCreate simplest runner possible
withTextOutputCreate TestRunner object for command window output

Examples

collapse all

Add matlab.unittest classes to the current import list.

import matlab.unittest.TestRunner;
import matlab.unittest.TestSuite;

Create a TestSuite array.

suite = TestSuite.fromClass(?mypackage.MyTestClass);

Create the TestRunner object and run the suite.

runner = TestRunner.withTextOutput;
result = run(runner,suite);

This example uses a shared test fixture and then specifies the fixture as prebuilt. The test runner does not set up and tear down the prebuilt fixture. Since the test assumes that the fixture exists, you must manually perform the setup work that the fixture ordinarily performs.

Create a test class in a file in your working folder. The test class uses a PathFixture as a shared test fixture. This example assumes that the subfolder, helperFiles, exists in your working folder.

classdef (SharedTestFixtures={ ...
        matlab.unittest.fixtures.PathFixture('helperFiles')}) ...
        SampleTest < matlab.unittest.TestCase
    methods(Test)
        function test1(testCase)
            f = testCase.getSharedTestFixtures;
            
            import matlab.unittest.constraints.ContainsSubstring
            testCase.assertThat(path,ContainsSubstring(f.Folder))
        end
    end
end

Create a test suite and test runner at the command prompt.

import matlab.unittest.TestRunner;
import matlab.unittest.TestSuite;

suite = TestSuite.fromClass(?SampleTest);
runner = TestRunner.withTextOutput;

Run the tests using the shared test fixture. In this case, the fixture is not prebuilt.

runner.run(suite);
Setting up PathFixture
Done setting up PathFixture: Added 'C:\Work\helperFiles' to the path.
__________

Running SampleTest
.
Done SampleTest
__________

Tearing down PathFixture
Done tearing down PathFixture: Restored the path to its original state.
__________

The test runner sets up and tears down the shared test fixture.

Create an instance of the fixture and add it to the test runner.

f = matlab.unittest.fixtures.PathFixture('helperFiles');
runner.PrebuiltFixtures = f;

Manually add the 'helperFiles' folder to your path. The PathFixture adds the specified folder to your path, and the tests rely on this setup action. However, since the fixture is defined as prebuilt, the test runner does not perform set up or tear down actions, and you must perform them manually. In this case, if you do not manually add it to your path, the test fails.

p = fullfile(pwd,'helperFiles');
oldPath = addpath(p);

Run the tests.

runner.run(suite);
Running SampleTest
.
Done SampleTest
__________

The test runner assumes that the fixture is prebuilt and does not set it up or tear it down.

Manually reset your path.

path(oldPath)

See Also

|

Topics

Introduced in R2013a

MATLAB Documentation

Support