matlab.unittest.plugins.DiagnosticsOutputPlugin class

Package: matlab.unittest.plugins

Plugin to direct diagnostics to output stream

Since R2018b

Description

The DiagnosticsOutputPlugin class creates a plugin to direct diagnostics to an output stream. To configure the type of diagnostics and detail level that the testing framework outputs, add this plugin to a TestRunner instance.

Construction

matlab.unittest.plugins.DiagnosticsOutputPlugin creates a plugin that directs diagnostics for failed events and for events logged at the Verbosity.Terse level to the ToStandardOutput stream.

matlab.unittest.plugins.DiagnosticsOutputPlugin(stream) redirects diagnostics to the specified output stream. For example, you can redirect output to a stream created using ToFile.

matlab.unittest.plugins.DiagnosticsOutputPlugin(___,Name,Value) creates a plugin with additional options specified by one or more Name,Value pair arguments. For example, DiagnosticsOutputPlugin('LoggingLevel',4,'IncludingPassingDiagnostics',true) creates a plugin that displays diagnostics logged at any level and also displays passing diagnostics.

Input Arguments

stream — Output location

ToStandardOutput (default) | instance of matlab.automation.streams.OutputStream

Output location, specified as an instance of the OutputStream class. The plugin directs diagnostic information to the specified location. By default, the plugin uses the matlab.automation.streams.ToStandardOutput stream.

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: DiagnosticsOutputPlugin('IncludingPassingDiagnostics',true,'OutputDetail',4) creates a plugin that includes passing diagnostics and displays diagnostics at a verbose detail level.

ExcludingFailureDiagnostics — Exclude diagnostics from failing events

false (default) | true

Whether to exclude diagnostics from failing events, specified as false or true. By default the plugin includes diagnostics from failing events.

Data Types: logical

IncludingPassingDiagnostics — Include passing event diagnostics

false (default) | true

Whether to include passing event diagnostics, specified as false or true. By default the plugin does not include diagnostics from passing events.

Data Types: logical

LoggingLevel — Maximum level of logged diagnostics

1 (default) | 0 | 2 | 3 | 4 | matlab.automation.Verbosity enumeration | enumeration name as string or char vector

Maximum level at which logged diagnostics are included by the plugin instance, specified as an integer value from 0 through 4, a matlab.automation.Verbosity enumeration object, or a string scalar or character vector corresponding to one of the predefined enumeration member names. The plugin includes diagnostics that are logged at this level and below. Integer values correspond to the members of the matlab.automation.Verbosity 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 plugin includes diagnostics logged at the matlab.automation.Verbosity.Terse level (level 1). To exclude logged diagnostics, specify LoggingLevel as Verbosity.None (level 0).

Logged diagnostics are diagnostics that you supply to the testing framework with a call to the log (TestCase) or log (Fixture) method.

OutputDetail — Detail level for reported events

3 (default) | 0 | 1 | 2 | 4 | matlab.automation.Verbosity enumeration | enumeration name as string or char vector

Detail level for reported events, specified as an integer value from 0 through 4, a matlab.automation.Verbosity enumeration object, or a string scalar or character vector corresponding to one of the predefined enumeration member names. Integer values correspond to the members of the matlab.automation.Verbosity enumeration.

The plugin reports passing, failing, and logged events with the amount of detail specified by OutputDetail. By default the plugin records events at the matlab.automation.Verbosity.Detailed level (level 3).

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

Properties

ExcludeFailureDiagnostics — Indicator if diagnostics for failing events are excluded

false (default) | true

This property is read-only.

Indicator if diagnostics for failing events are excluded, specified as false or true (logical 0 or 1). By default, ExcludeFailureDiagnostics is false and the diagnostics from failing events are included in the output. To exclude diagnostics from failing events from the output, specify ExcludeFailureDiagnostics as true during plugin construction.

IncludePassingDiagnostics — Indicator if diagnostics for passing events are included

false (default) | true

This property is read-only.

Indicator if diagnostics for passing events are included, specified as false or true (logical 0 or 1). By default, IncludePassingDiagnostics is false and the diagnostics from passing events are excluded from the output. To include diagnostics from passing events in the output, specify IncludePassingDiagnostics as true during plugin construction.

LoggingLevel — Maximum verbosity level for logged diagnostics included by the plugin

matlab.automation.Verbosity.Terse (default) | matlab.automation.Verbosity enumeration object

This property is read-only.

Maximum verbosity level for logged diagnostics included by the plugin, returned as a matlab.automation.Verbosity enumeration object. The plugin includes diagnostics that are logged at this level and below. By default this property value is matlab.automation.Verbosity.Terse. You can specify a different logging level during plugin construction.

Logged diagnostics are diagnostics that you supply to the testing framework with a call to the log (TestCase) or log (Fixture) method.

OutputDetail — Detail level for reported events

Detailed (default) | matlab.automation.Verbosity instance

This property is read-only.

Detail level for reported events, returned as a matlab.automation.Verbosity enumeration object. By default this property value is matlab.automation.Verbosity.Detailed. You can specify a different output detail level during plugin construction.

Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects.

Examples

Create Plugin to Customize Diagnostics Display

Create a file ExampleDiagOutputTest.m containing the following test class.

classdef ExampleDiagOutputTest < matlab.unittest.TestCase
    methods(Test)
        function testOne(testCase)
            import matlab.automation.Verbosity
            testCase.log(Verbosity.Detailed,'Testing failing event')
            testCase.verifyEqual(42,13,'42 == 13')
        end
        function testTwo(testCase)
            testCase.log(3,'Testing passing event')
            testCase.verifyTrue(true,'true is true')
        end
    end
end

Create a test suite from the ExampleDiagOutputTest class. Create a test runner with no plugins.

import matlab.unittest.TestRunner
import matlab.unittest.TestSuite
import matlab.automation.Verbosity
import matlab.unittest.plugins.DiagnosticsOutputPlugin

suite = TestSuite.fromClass(?ExampleDiagOutputTest);
runner = TestRunner.withNoPlugins();

Create a default DiagnosticsOutputPlugin, add it to the runner, and run the tests.

plugin = DiagnosticsOutputPlugin;
runner.addPlugin(plugin);
result = runner.run(suite);

================================================================================
Verification failed in ExampleDiagOutputTest/testOne.
    ----------------
    Test Diagnostic:
    ----------------
    42 == 13
    ---------------------
    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\ExampleDiagOutputTest.m (ExampleDiagOutputTest.testOne) at 6
================================================================================
Failure Summary:

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

Create another test runner and a DiagnosticsOutputPlugin that displays diagnostics, including passing diagnostics, at a Terse level, and displays diagnostics that are logged at a Detailed level or lower. Add it to the runner and rerun the tests.

runner = TestRunner.withNoPlugins();
plugin = DiagnosticsOutputPlugin('OutputDetail',Verbosity.Terse, ...
    'LoggingLevel',3,'IncludingPassingDiagnostics',true);
runner.addPlugin(plugin);
result = runner.run(suite);

[Detailed] Diagnostic logged (2022-10-15 18:30:46): Testing failing event

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

[Detailed] Diagnostic logged (2022-10-15 18:30:47): Testing passing event

PASS: ExampleDiagOutputTest/testTwo in ExampleDiagOutputTest.testTwo at 10 :: verifyTrue passed.

Version History

Introduced in R2018b