matlab.unittest.TestRunner.withDefaultPlugins - Create default test runner - MATLAB (original) (raw)

Class: matlab.unittest.TestRunner
Namespace: matlab.unittest

Create default test runner

Since R2025a

Syntax

Description

runner = matlab.unittest.TestRunner.withDefaultPlugins creates a default test runner, which is equivalent to the runner that the testing framework configures by default when you call the runtests function. The method returns the test runner as a matlab.unittest.TestRunner object.

Use this method to create a test runner that provides essential test run features, such as displaying test run progress and test diagnostics. For more information on how the testing framework configures a default test runner, see Default Plugins.

example

runner = matlab.unittest.TestRunner.withDefaultPlugins([Name=Value](#namevaluepairarguments)) specifies options using one or more name-value arguments. For example, runner = matlab.unittest.TestRunner.withDefaultPlugins(OutputDetail="Verbose") creates a default test runner that displays test output at the maximum verbosity level.

Name-Value Arguments

expand all

Specify optional pairs of arguments asName1=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: runner = matlab.unittest.TestRunner.withDefaultPlugins(OutputDetail="Verbose",LoggingLevel="Detailed")

Display level of test output, specified as an integer scalar from0 through 4, a matlab.automation.Verbosity enumeration object, or a text representation of the enumeration.

Numeric Representation	Enumeration Member Name	Verbosity Description
0	None	No information
1	Terse	Minimal information
2	Concise	Moderate amount of information
3	Detailed	Some supplemental information
4	Verbose	Lots of supplemental information

By default, the test runner displays failing and logged events at thematlab.automation.Verbosity.Detailed level (level 3) and test run progress at the matlab.automation.Verbosity.Concise level (level 2).

Example: runner = matlab.unittest.TestRunner.withDefaultPlugins(OutputDetail="Verbose") creates a default test runner that displays test output at thematlab.automation.Verbosity.Verbose level.

Verbosity level of logged diagnostics, specified as an integer scalar from0 through 4, a matlab.automation.Verbosity enumeration object, or a text representation of the enumeration. The test runner includes diagnostics logged at the specified level and below.

Numeric Representation	Enumeration Member Name	Verbosity Description
0	None	No information
1	Terse	Minimal information
2	Concise	Moderate amount of information
3	Detailed	Some supplemental information
4	Verbose	Lots of supplemental information

By default, the test runner includes diagnostics logged at thematlab.automation.Verbosity.Terse level (level 1). To exclude logged diagnostics, specify LoggingLevel asmatlab.automation.Verbosity.None (level 0).

Logged diagnostics are diagnostics that you supply to the unit testing framework with the log (TestCase) and log (Fixture) methods.

Example: runner = matlab.unittest.TestRunner.withDefaultPlugins(LoggingLevel="Detailed") creates a default test runner that includes diagnostics logged at thematlab.automation.Verbosity.Detailed level and below.

Examples

expand all

Run a suite of tests using a default test runner, and then access the diagnostics recorded on the test results.

Create a function-based test file named sampleTest.m in your current folder. The file contains two tests that pass and one test that intentionally fails.

function tests = sampleTest tests = functiontests(localfunctions); end

function testA(testCase) % Test passes verifyEqual(testCase,2+3,5) end

function testB(testCase) % Test fails verifyGreaterThan(testCase,13,42) end

function testC(testCase) % Test passes verifySubstring(testCase,"Hello World!","llo") end

Create a test suite from the tests in sampleTest.m. Then, create a default test runner and run the tests.

suite = testsuite("SampleTest"); runner = matlab.unittest.TestRunner.withDefaultPlugins; results = run(runner,suite);

Running sampleTest .

Verification failed in sampleTest/testB. --------------------- Framework Diagnostic: --------------------- verifyGreaterThan failed. --> The value must be greater than the minimum value.
Actual Value: 13 Minimum Value (Exclusive): 42 ------------------ Stack Information: ------------------ In C:\work\sampleTest.m (testB) at 10

.. Done sampleTest

Failure Summary:

 Name              Failed  Incomplete  Reason(s)
===============================================================
 sampleTest/testB    X                 Failed by verification.

Display the result of the second test.

ans =

TestResult with properties:

      Name: 'sampleTest/testB'
    Passed: 0
    Failed: 1
Incomplete: 0
  Duration: 2.3628
   Details: [1×1 struct]

Totals: 0 Passed, 1 Failed, 0 Incomplete. 2.3628 seconds testing time.

A default test runner includes a matlab.unittest.plugins.DiagnosticsRecordingPlugin instance to record diagnostics on test results. Access the recorded diagnostics for the second test using the DiagnosticRecord field in the Details property of the corresponding TestResult object.

records = results(2).Details.DiagnosticRecord

records =

QualificationDiagnosticRecord with properties:

                      Event: 'VerificationFailed'
                 EventScope: TestMethod
              EventLocation: 'sampleTest/testB'
      TestDiagnosticResults: [1×0 matlab.automation.diagnostics.DiagnosticResult]
 FrameworkDiagnosticResults: [1×1 matlab.automation.diagnostics.DiagnosticResult]
AdditionalDiagnosticResults: [1×0 matlab.automation.diagnostics.DiagnosticResult]
                      Stack: [1×1 struct]
                     Report: 'Verification failed in sampleTest/testB...'

More About

expand all

To configure a default test runner, the testing framework first creates a test runner with no plugins and then adds these plugins to it:

TestRunProgressPlugin instance to display test run progress
DiagnosticsOutputPlugin instance to direct diagnostics to the output stream
DiagnosticsRecordingPlugin instance to record diagnostics on test results

If you specify the name-value arguments of the withDefaultPlugins static method, then the framework creates plugins that respect the specified options. For example, if you specify the OutputDetail name-value argument, then theTestRunProgressPlugin instance that the framework adds to the test runner displays test run progress at the specified verbosity level.

In addition to the plugins that always exist on a default test runner, the testing framework might include additional plugins depending on the available products and the way the test runner is created. For example, if you specify theReportCoverageFor name-value argument of the runtests function, the framework adds a CodeCoveragePlugin instance to the default test runner it creates for running the tests.

Version History

Introduced in R2025a