matlab.unittest.plugins.LoggingPlugin.withVerbosity

Class: matlab.unittest.plugins.LoggingPlugin
Namespace: matlab.unittest.plugins

Construct LoggingPlugin for messages of specified verbosity

Syntax

matlab.unittest.plugins.LoggingPlugin.withVerbosity(v)
matlab.unittest.plugins.LoggingPlugin.withVerbosity(v,stream)
matlab.unittest.plugins.LoggingPlugin.withVerbosity(v,Name,Value)


Description

matlab.unittest.plugins.LoggingPlugin.withVerbosity(v) constructs a LoggingPlugin for messages of the specified verbosity.

matlab.unittest.plugins.LoggingPlugin.withVerbosity(v,stream) redirects the text output to the output stream.

matlab.unittest.plugins.LoggingPlugin.withVerbosity(v,Name,Value) includes additional options specified by one or more Name,Value pair arguments.

Input Arguments

v — Verbosity levels supported by plugin instance

0 | 1 | 2 | 3 | 4 | matlab.automation.Verbosity enumeration | enumeration name as string or character vector

Verbosity levels supported by the plugin instance, specified as an integer value between 0 and 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 reacts to diagnostics that are logged at this level and lower. 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

stream — Location where plugin directs text output

ToStandardOutput instance (default) | OutputStream instance

Location where the plugin directs text output, specified as an OutputStream instance. By default, the plugin uses the OutputStream subclass ToStandardOutput as the stream.

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.

Description — Logged diagnostic message description

'Diagnostic logged' (default) | character vector | string scalar

Logged diagnostic message description, specified as a character vector or string scalar. This value is printed alongside each logged diagnostic message. If the value empty, the test framework does not display a description.

ExcludingLowerLevels — Indicator to display messages logged at levels lower than the verbosity level

false (default) | true

Indicator to display messages logged at levels lower than the verbosity level, v, specified as false or true (logical(0) or logical(1)). By default, the value is false and the plugin reacts to all messages logged at level v or lower. If the value is true, the plugin reacts only to messages logged at level v.

HideLevel — Indicator to display verbosity level

false (default) | true

Indicator to display the verbosity level alongside each logged diagnostic, specified as false or true (logical(0) or logical(1)). By default, the value is false and the test framework displays the verbosity level.

HideTimestamp — Indicator to display timestamp

false (default) | true

Indicator to display the timestamp from when the test framework generates the logged message alongside each logged diagnostic, specified as false or true (logical(0) or logical(1)). By default, the value is false and the test framework displays the timestamp.

NumStackFrames — Number of stack frames to display

0 (default) | integer value | Inf

Number of stack frames to display after each logged diagnostic message, specified as an integer value. By default, the value is 0, and the test framework does not display stack information. If NumStackFrames is Inf, the test framework displays all available stack frames.

Examples

Create Logging Plugin

Create a function-based test in a file, sampleLogTest.m, in your working folder.

function tests = sampleLogTest
tests = functiontests(localfunctions);

function svdTest(testCase)
import matlab.automation.Verbosity

log(testCase,'Generating matrix.')
m = rand(1000);

log(testCase,1,'About to call SVD.')
[U,S,V] = svd(m);

log(testCase,Verbosity.Terse,'SVD finished.')

verifyEqual(testCase,U*S*V',m,'AbsTol',1e-6)

At the command prompt, run the test.

results = run(sampleLogTest);

Running sampleLogTest

[Terse] Diagnostic logged (2022-10-15 18:35:02): About to call SVD.

[Terse] Diagnostic logged (2022-10-15 18:35:20): SVD finished.
.
Done sampleLogTest
__________

The default runner reports the diagnostics at level 1 (Terse).

Create a test runner to report the diagnostics at levels 1 and 2, and rerun the test.

import matlab.unittest.TestRunner
import matlab.unittest.plugins.LoggingPlugin

runner = TestRunner.withNoPlugins;
p = LoggingPlugin.withVerbosity(2);
runner.addPlugin(p)

results = runner.run(sampleLogTest);

 [Concise] Diagnostic logged (2022-10-15T18:36:05): Generating matrix.
   [Terse] Diagnostic logged (2022-10-15T18:36:05): About to call SVD.
   [Terse] Diagnostic logged (2022-10-15T18:36:05): SVD finished.

Configure Logged Message Output

Create the following class in a file in your current working folder, ExampleLogTest.m.

classdef ExampleLogTest < matlab.unittest.TestCase
    methods(Test)
        function testOne(testCase)  % Test fails
            log(testCase,3,'Starting Test')
            log(testCase,'Testing 5==4')
            testCase.verifyEqual(5,4)
            log(testCase,4,'Test Complete')
        end
        function testTwo(testCase)  % Test passes
            log(testCase,'Detailed','Starting Test')
            log(testCase,'Testing 5==5')
            testCase.verifyEqual(5,5)
            log(testCase,'Verbose','Test Complete')
        end
    end
end

At the command prompt, create a test suite and a runner at verbosity level 4, and then run the test.

import matlab.unittest.TestSuite
import matlab.unittest.TestRunner
import matlab.unittest.plugins.LoggingPlugin
suite = TestSuite.fromClass(?ExampleLogTest);

runner = TestRunner.withNoPlugins;
p = LoggingPlugin.withVerbosity(4);
runner.addPlugin(p)

results = runner.run(suite);

[Detailed] Diagnostic logged (2022-10-15T18:45:43): Starting Test
 [Concise] Diagnostic logged (2022-10-15T18:45:43): Testing 5==4
 [Verbose] Diagnostic logged (2022-10-15T18:45:44): Test Complete
[Detailed] Diagnostic logged (2022-10-15T18:45:44): Starting Test
 [Concise] Diagnostic logged (2022-10-15T18:45:44): Testing 5==5
 [Verbose] Diagnostic logged (2022-10-15T18:45:44): Test Complete

Create a new plugin to direct the output to a file, myOutput.log, and rerun the tests.

import matlab.automation.streams.ToFile
outFile = 'myOutput.log';

runner = TestRunner.withNoPlugins;
p = LoggingPlugin.withVerbosity(4,ToFile(outFile));
runner.addPlugin(p)

results = runner.run(suite);

Observe the contents in the file created by the plugin.

disp(fileread(outFile))

[Detailed] Diagnostic logged (2022-10-15T18:46:09): Starting Test
 [Concise] Diagnostic logged (2022-10-15T18:46:09): Testing 5==4
 [Verbose] Diagnostic logged (2022-10-15T18:46:09): Test Complete
[Detailed] Diagnostic logged (2022-10-15T18:46:09): Starting Test
 [Concise] Diagnostic logged (2022-10-15T18:46:09): Testing 5==5
 [Verbose] Diagnostic logged (2022-10-15T18:46:09): Test Complete

Create a new plugin that does not display level 4 messages. Do not display the verbosity level or timestamp. Rerun the tests.

runner = TestRunner.withNoPlugins;
p = LoggingPlugin.withVerbosity('Detailed', ...
    'HideLevel',true,'HideTimestamp',true);
runner.addPlugin(p)

results = runner.run(suite);

Diagnostic logged: Starting Test
Diagnostic logged: Testing 5==4
Diagnostic logged: Starting Test
Diagnostic logged: Testing 5==5

Version History

Introduced in R2014b