matlab.unittest.plugins.DiagnosticsOutputPlugin class

Package: matlab.unittest.plugins

Plugin to direct diagnostics to output stream

expand all in page

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

expand all

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.unittest.plugins.ToStandardOutput stream.

Example: matlab.unittest.plugins.ToFile('myFile.txt')

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

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

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

Data Types: logical

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

Maximum level at which logged diagnostics are included by the plugin instance, specified as an integer value from 0 through 4, a matlab.unittest.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.unittest.Verbosity enumeration.

Numeric RepresentationEnumeration Member NameVerbosity Description
0None

No information

1Terse

Minimal information

2Concise

Moderate amount of information

3Detailed

Some supplemental information

4Verbose

Lots of supplemental information

By default the plugin includes diagnostics logged at the matlab.unittest.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.

Detail level for reported events, specified as an integer value from 0 through 4, a matlab.unittest.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.unittest.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.unittest.Verbosity.Detailed level (level 3).

Numeric RepresentationEnumeration Member NameVerbosity Description
0None

No information

1Terse

Minimal information

2Concise

Moderate amount of information

3Detailed

Some supplemental information

4Verbose

Lots of supplemental information

Properties

expand all

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.

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.

This property is read-only.

Maximum verbosity level for logged diagnostics included by the plugin, returned as a matlab.unittest.Verbosity enumeration object. The plugin includes diagnostics that are logged at this level and below. By default this property value is matlab.unittest.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.

This property is read-only.

Detail level for reported events, returned as a matlab.unittest.Verbosity enumeration object. By default this property value is matlab.unittest.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

collapse all

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

classdef ExampleDiagOutputTest < matlab.unittest.TestCase
    methods(Test)
        function testOne(testCase)
            import matlab.unittest.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.unittest.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 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 5
================================================================================
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 (2018-04-13 13:47:34): Testing failing event

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

[Detailed] Diagnostic logged (2018-04-13 13:47:34): Testing passing event

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

See Also

| |

Introduced in R2018b

MATLAB Documentation

Support