matlab.unittest.plugins.DiagnosticsOutputPlugin Class

Namespace: matlab.unittest.plugins
Superclasses: matlab.unittest.plugins.TestRunnerPlugin, matlab.unittest.plugins.Parallelizable

Plugin that directs diagnostics to output stream

Description

The matlab.unittest.plugins.DiagnosticsOutputPlugin class provides a plugin that directs diagnostics to an output stream. To control the type and amount of diagnostic information to display, add this plugin to the test runner.

The matlab.unittest.plugins.DiagnosticsOutputPlugin class is a handle class.

Creation

Description

plugin = matlab.unittest.plugins.DiagnosticsOutputPlugin creates a plugin that displays diagnostics for failing events and events logged at the matlab.automation.Verbosity.Terse level. By default, the plugin directs its text output to the screen.

plugin = matlab.unittest.plugins.DiagnosticsOutputPlugin(stream) creates a plugin that directs its data to the specified output stream.

plugin = matlab.unittest.plugins.DiagnosticsOutputPlugin(___,Name=Value) specifies options using one or more name-value arguments in addition to any of the input argument combinations in previous syntaxes. For example, plugin = matlab.unittest.plugins.DiagnosticsOutputPlugin(IncludingPassingDiagnostics=true) creates a plugin that displays both the failing and passing event diagnostics.

Input Arguments

stream — Output stream where plugin directs text output

matlab.automation.streams.ToStandardOutput object (default) | matlab.automation.streams.OutputStream object

Output stream where the plugin directs text output, specified as a matlab.automation.streams.OutputStream object. By default, the plugin directs its output to the screen.

Example: matlab.automation.streams.ToFile("myFile.txt")

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: plugin = matlab.unittest.plugins.DiagnosticsOutputPlugin(IncludingPassingDiagnostics=true)

ExcludingFailureDiagnostics — Option to exclude diagnostics for failing events

false or 0 (default) | true or 1

Option to exclude the diagnostics for failing events, specified as a numeric or logical 0 (false) or 1 (true). By default, the plugin includes the diagnostics for failing events.

This argument sets the ExcludeFailureDiagnostics property.

IncludingPassingDiagnostics — Option to include diagnostics for passing events

false or 0 (default) | true or 1

Option to include the diagnostics for passing events, specified as a numeric or logical 0 (false) or 1 (true). By default, the plugin does not include the diagnostics for passing events.

This argument sets the IncludePassingDiagnostics property.

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 plugin 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 plugin 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 testing framework with the log (TestCase) and log (Fixture) methods.

This argument sets the LoggingLevel property.

Example: LoggingLevel="Detailed"

OutputDetail — Display level of event details

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

Display level of event details, 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

The plugin supports the display of passing, failing, and logged events. By default, the plugin displays event details at the matlab.automation.Verbosity.Detailed level (level 3).

This argument sets the OutputDetail property.

Example: OutputDetail="Concise"

Properties

ExcludeFailureDiagnostics — Option to exclude diagnostics for failing events

false or 0 (default) | true or 1

Option to exclude the diagnostics for failing events, specified as a numeric or logical 0 (false) or 1 (true). If the value is true, then the plugin does not include the diagnostics for failing events. By default, the plugin includes the diagnostics for failing events.

This property is set by the ExcludingFailureDiagnostics name-value argument.

Attributes:

GetAccess	public
SetAccess	immutable

IncludePassingDiagnostics — Option to include diagnostics for passing events

false or 0 (default) | true or 1

Option to include the diagnostics for passing events, specified as a numeric or logical 0 (false) or 1 (true). If the value is true, then the plugin includes the diagnostics for passing events. By default, the plugin does not include the diagnostics for passing events.

This property is set by the IncludingPassingDiagnostics name-value argument.

Attributes:

GetAccess	public
SetAccess	immutable

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, and stored as a matlab.automation.Verbosity enumeration object. By default, the plugin includes diagnostics logged at the matlab.automation.Verbosity.Terse level.

This property is set by the LoggingLevel name-value argument.

Attributes:

GetAccess	public
SetAccess	private

OutputDetail — Display level of event details

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

Display level of event details, specified as an integer scalar from 0 through 4, a matlab.automation.Verbosity enumeration object, or a text representation of the enumeration, and stored as a matlab.automation.Verbosity enumeration object. By default, the plugin displays event details at the matlab.automation.Verbosity.Detailed level.

This property is set by the OutputDetail name-value argument.

Attributes:

GetAccess	public
SetAccess	private

Examples

Display Test Diagnostics

Run tests and display diagnostics by using the DiagnosticsOutputPlugin class.

In a file named ExampleTest.m in your current folder, create the ExampleTest test class. Each Test method in the class includes a diagnostic logged at the matlab.automation.Verbosity.Detailed level (level 3) as well as a test diagnostic supplied to a qualification.

classdef ExampleTest < matlab.unittest.TestCase
    methods (Test)
        function testOne(testCase)
            import matlab.automation.Verbosity
            testCase.log(Verbosity.Detailed,"Testing failing event")
            testCase.verifyEqual(42,13,"Values must be equal")
        end
        
        function testTwo(testCase)
            testCase.log(3,"Testing passing event")
            testCase.verifyTrue(true,"Value must be true")
        end
    end
end

Import the DiagnosticsOutputPlugin class.

import matlab.unittest.plugins.DiagnosticsOutputPlugin

Create a test suite from the test class.

suite = testsuite("ExampleTest");

Using a DiagnosticsOutputPlugin instance, run the tests and display the diagnostics. By default, the plugin displays diagnostics only for failing events and events logged at the matlab.automation.Verbosity.Terse level.

runner = testrunner("minimal");
plugin = DiagnosticsOutputPlugin;
runner.addPlugin(plugin)
results = runner.run(suite);

================================================================================
Verification failed in ExampleTest/testOne.
    ----------------
    Test Diagnostic:
    ----------------
    Values must be equal
    ---------------------
    Framework Diagnostic:
    ---------------------
    verifyEqual failed.
    --> The numeric values are not equal using "isequaln".
    --> Failure table:
            Actual    Expected    Error     RelativeError  
            ______    ________    _____    ________________
                                                           
              42         13        29      2.23076923076923
    
    Actual Value:
        42
    Expected Value:
        13
    ------------------
    Stack Information:
    ------------------
    In C:\work\ExampleTest.m (ExampleTest.testOne) at 6
================================================================================
Failure Summary:

     Name                 Failed  Incomplete  Reason(s)
    ==================================================================
     ExampleTest/testOne    X                 Failed by verification.

Now, run the tests using a plugin that displays the details of all events (that is, passing events, failing events, and events logged at any level) at the matlab.automation.Verbosity.Terse level.

runner = testrunner("minimal");
plugin = DiagnosticsOutputPlugin( ...
    IncludingPassingDiagnostics=true, ...
    LoggingLevel="Verbose", ...
    OutputDetail="Terse");
runner.addPlugin(plugin)
results = runner.run(suite);

[Detailed] Diagnostic logged (2024-08-19 16:21:47): Testing failing event

FAIL: ExampleTest/testOne in ExampleTest.testOne at 6 :: verifyEqual failed.

[Detailed] Diagnostic logged (2024-08-19 16:21:48): Testing passing event

PASS: ExampleTest/testTwo in ExampleTest.testTwo at 11 :: verifyTrue passed.

Version History

Introduced in R2018b