matlab.unittest.TestRunner.withDefaultPlugins

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

Create default test runner

Since R2025a

Syntax

runner = matlab.unittest.TestRunner.withDefaultPlugins

runner = matlab.unittest.TestRunner.withDefaultPlugins(Name=Value)

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.

runner = matlab.unittest.TestRunner.withDefaultPlugins(Name=Value) 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

Specify optional pairs of arguments as Name1=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")

OutputDetail — Display level of test output

0 | 1 | 2 | 3 | 4 | matlab.automation.Verbosity enumeration object | text representation of enumeration

Display level of test output, specified as an integer scalar from 0 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 the matlab.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 the matlab.automation.Verbosity.Verbose level.

LoggingLevel — Verbosity level of logged diagnostics

1 (default) | 0 | 2 | 3 | 4 | matlab.automation.Verbosity enumeration object | text representation of enumeration

Verbosity level of logged diagnostics, specified as an integer scalar from 0 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 the matlab.automation.Verbosity.Terse level (level 1). To exclude logged diagnostics, specify LoggingLevel as matlab.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 the matlab.automation.Verbosity.Detailed level and below.

Attributes

Static

true

To learn about attributes of methods, see Method Attributes.

Examples

Access Diagnostics Recorded by Default Test Runner

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.

results(2)

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

Default Plugins

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 the TestRunProgressPlugin 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 the ReportCoverageFor 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