matlab.unittest.plugins.LoggingPlugin.withVerbosity

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

Create plugin that displays logged diagnostics at specified verbosity

Syntax

plugin = matlab.unittest.plugins.LoggingPlugin.withVerbosity(level)

plugin = matlab.unittest.plugins.LoggingPlugin.withVerbosity(level,stream)

plugin = matlab.unittest.plugins.LoggingPlugin.withVerbosity(___,Name=Value)

Description

plugin = matlab.unittest.plugins.LoggingPlugin.withVerbosity(level) creates a plugin that displays diagnostics logged at the specified level and below. By default, the plugin directs its text output to the screen.

Logged diagnostics are diagnostics that you supply to the unit testing framework with the log (TestCase) and log (Fixture) methods.

plugin = matlab.unittest.plugins.LoggingPlugin.withVerbosity(level,stream) creates a plugin that directs its data to the specified output stream.

plugin = matlab.unittest.plugins.LoggingPlugin.withVerbosity(___,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.LoggingPlugin.withVerbosity("Detailed",ExcludingLowerLevels=true) creates a plugin that displays diagnostics logged only at the matlab.automation.Verbosity.Detailed level.

Input Arguments

level — Verbosity level

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

Verbosity level, specified as an integer scalar from 0 through 4, a matlab.automation.Verbosity enumeration object, or a text representation of the enumeration. The plugin displays 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

Example: 3

Example: "Detailed"

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.LoggingPlugin.withVerbosity("Detailed",ExcludingLowerLevels=true)

Description — Description of logged diagnostic messages

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

Description of logged diagnostic messages, specified as a string scalar or character vector. The plugin displays the description alongside each logged message. If you specify an empty value, the plugin does not include a description.

ExcludingLowerLevels — Option to exclude diagnostics logged at lower levels

false or 0 (default) | true or 1

Option to exclude diagnostics logged at levels below level, specified as a numeric or logical 0 (false) or 1 (true). If the value is true, then the plugin displays diagnostics logged only at the specified level. By default, the plugin displays diagnostics logged at the specified level and below.

HideLevel — Option to hide logging level

false or 0 (default) | true or 1

Option to hide the logging level of logged messages, specified as a numeric or logical 0 (false) or 1 (true). If the value is true, then the plugin does not display the logging level alongside each logged message. By default, the plugin displays the logging levels.

HideTimestamp — Option to hide timestamp

false or 0 (default) | true or 1

Option to hide the timestamp of logged messages, specified as a numeric or logical 0 (false) or 1 (true). If the value is true, then the plugin does not display the timestamp alongside each logged message. By default, the plugin displays the timestamps.

NumStackFrames — Number of stack frames to display

0 (default) | Inf | nonnegative integer scalar

Number of stack frames to display after each logged message, specified as Inf or a nonnegative integer scalar. By default, the plugin does not display stack information. If the value is Inf, then the plugin displays all the available stack frames.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Attributes

Static

true

To learn about attributes of methods, see Method Attributes.

Examples

Display Logged Diagnostics

Run tests and display logged diagnostics by using the LoggingPlugin class.

In a file named sampleTest.m in your current folder, create a function-based test that includes logged diagnostics.

function tests = sampleTest
tests = functiontests(localfunctions);
end

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)
end

Import the LoggingPlugin class.

import matlab.unittest.plugins.LoggingPlugin

Create a test suite from the test file.

suite = testsuite("sampleTest.m");

Run the test using a default test runner. The test runner displays diagnostics logged at the matlab.automation.Verbosity.Terse level (level 1).

runner = testrunner;
results = runner.run(suite);

Running sampleTest

[Terse] Diagnostic logged (2024-08-16 17:11:33): About to call SVD

[Terse] Diagnostic logged (2024-08-16 17:11:33): SVD finished
.
Done sampleTest
__________

Create a new test runner and configure it using a plugin that displays diagnostics logged at or below the matlab.automation.Verbosity.Concise level (level 2). Then, rerun the test using the test runner. The plugin displays all the logged diagnostics associated with the test.

runner = testrunner("minimal");
plugin = LoggingPlugin.withVerbosity("Concise");
runner.addPlugin(plugin)
results = runner.run(suite);

 [Concise] Diagnostic logged (2024-08-16T17:13:11): Generating matrix
   [Terse] Diagnostic logged (2024-08-16T17:13:11): About to call SVD
   [Terse] Diagnostic logged (2024-08-16T17:13:11): SVD finished

Customize Display of Logged Diagnostics

Customize the display of logged diagnostics by using the LoggingPlugin class.

In a file named ExampleTest.m in your current folder, create the ExampleTest test class. Each test in the test class includes three logged diagnostics.

classdef ExampleTest < 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

Import the classes used in this example.

import matlab.unittest.plugins.LoggingPlugin
import matlab.automation.streams.ToFile

Create a test suite from the ExampleTest class.

suite = testsuite("ExampleTest");

Using a LoggingPlugin instance, run the tests and display the diagnostics logged at the matlab.automation.Verbosity.Verbose level (level 4) and below. By default, the plugin directs its text output to the screen.

runner = testrunner("minimal");
plugin = LoggingPlugin.withVerbosity("Verbose");
runner.addPlugin(plugin)
results = runner.run(suite);

[Detailed] Diagnostic logged (2024-08-16T17:44:46): Starting test
 [Concise] Diagnostic logged (2024-08-16T17:44:46): Testing 5==4
 [Verbose] Diagnostic logged (2024-08-16T17:44:47): Test complete
[Detailed] Diagnostic logged (2024-08-16T17:44:47): Starting test
 [Concise] Diagnostic logged (2024-08-16T17:44:47): Testing 5==5
 [Verbose] Diagnostic logged (2024-08-16T17:44:47): Test complete

Create a new test runner and configure it using a plugin that directs its output to a file named myOutput.log in your current folder. If you rerun the tests, the logged diagnostics no longer appear in the Command Window. The plugin directs the text output to the specified file instead of the screen.

runner = testrunner("minimal");
plugin = LoggingPlugin.withVerbosity("Verbose",ToFile("myOutput.log"));
runner.addPlugin(plugin)
results = runner.run(suite);

Display the contents of the file created by the plugin.

disp(fileread("myOutput.log"))

[Detailed] Diagnostic logged (2024-08-16T17:47:11): Starting test
 [Concise] Diagnostic logged (2024-08-16T17:47:11): Testing 5==4
 [Verbose] Diagnostic logged (2024-08-16T17:47:11): Test complete
[Detailed] Diagnostic logged (2024-08-16T17:47:11): Starting test
 [Concise] Diagnostic logged (2024-08-16T17:47:11): Testing 5==5
 [Verbose] Diagnostic logged (2024-08-16T17:47:11): Test complete

Now, run the tests using a plugin that displays diagnostics logged at the matlab.automation.Verbosity.Detailed level (level 3) and below, without logging levels or timestamps.

runner = testrunner("minimal");
plugin = LoggingPlugin.withVerbosity("Detailed", ...
    HideLevel=true,HideTimestamp=true);
runner.addPlugin(plugin)
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