matlab.unittest.TestRunner Class

Namespace: matlab.unittest

Class for running tests in unit testing framework

Description

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

The matlab.unittest.TestRunner class is a handle class.

Class Attributes

Sealed

true

For information on class attributes, see Class Attributes.

Creation

Create a TestRunner instance using one of its static methods:

• To create a default test runner, use the matlab.unittest.TestRunner.withDefaultPlugins method.

• To create a minimal test runner with no plugins, use the matlab.unittest.TestRunner.withNoPlugins method.

• To create a test runner configured for text output, use the matlab.unittest.TestRunner.withTextOutput method.

Alternatively, you can create a test runner by using the testrunner function.

Properties

ArtifactsRootFolder — Root folder where diagnostic artifacts are stored

string scalar | character vector

Root folder where diagnostic artifacts from the test run are stored, specified as a string scalar or character vector containing an absolute or relative path. By default, the value is string(tempdir), but you can set the property to any writable folder.

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. The testing framework creates a subfolder only if the test run produces diagnostic artifacts. For example, suppose that ArtifactsRootFolder is set to "C:\Temp" and the autogenerated test run identifier is "1231df38-7515-4dbe-a869-c3d9f885f379". If the test run produces a diagnostic artifact named "screenshot.png", then the testing framework stores the artifact as "C:\Temp\1231df38-7515-4dbe-a869-c3d9f885f379\screenshot.png".

Attributes:

GetAccess	public
SetAccess	public

PrebuiltFixtures — Fixtures set up outside test runner

matlab.unittest.fixtures.Fixture vector

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

The test runner considers prebuilt 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 that is also specified as a prebuilt fixture, then the test runner does not perform its setup and teardown actions.

Note

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

Attributes:

GetAccess	public
SetAccess	public

Methods

Public Methods

matlab.unittest.TestRunner.withDefaultPlugins	Create default test runner
matlab.unittest.TestRunner.withNoPlugins	Create minimal test runner with no plugins
matlab.unittest.TestRunner.withTextOutput	Create test runner configured for text output
addPlugin	Add plugin to test runner
addModelCoverage (Simulink Test)	Enable model coverage collection for Simulink tests
addSimulinkTestResults (Simulink Test)	Enable pushing test results to Simulink Test Manager
run	Run test suite
runInParallel	Run all tests in test suite in parallel

Examples

Create TestRunner Object Configured for Text Output

Add matlab.unittest classes to the current import list.

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

Create a TestSuite array.

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

Create the TestRunner object and run the suite.

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

Include Prebuilt Fixture

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)

Version History

Introduced in R2013a

R2025a: Create default test runner

To create a default test runner, use the matlab.unittest.TestRunner.withDefaultPlugins method.