matlab.unittest.plugins.LoggingPlugin.withVerbosity - Create plugin that displays logged diagnostics at specified

        verbosity - MATLAB ([original](https://in.mathworks.com/help/matlab/ref/matlab.unittest.plugins.loggingplugin.withverbosity.html)) ([raw](?raw))

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

Create plugin that displays logged diagnostics at specified verbosity

Syntax

Description

plugin = matlab.unittest.plugins.LoggingPlugin.withVerbosity([level](#mw%5F602c1ee9-5f54-470f-b3b2-3034a1f55475)) 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.

example

plugin = matlab.unittest.plugins.LoggingPlugin.withVerbosity([level](#mw%5F602c1ee9-5f54-470f-b3b2-3034a1f55475),[stream](#mw%5F42580106-d569-41f7-8a5a-f49042873e50)) creates a plugin that directs its data to the specified output stream.

example

plugin = matlab.unittest.plugins.LoggingPlugin.withVerbosity(___,[Name=Value](#namevaluepairarguments)) 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 thematlab.automation.Verbosity.Detailed level.

example

Input Arguments

expand all

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"

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

expand all

Specify optional pairs of arguments asName1=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 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.

Option to exclude diagnostics logged at levels belowlevel, specified as a numeric or logical0 (false) or1 (true). If the value istrue, then the plugin displays diagnostics logged only at the specified level. By default, the plugin displays diagnostics logged at the specified level and below.

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

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

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 isInf, then the plugin displays all the available stack frames.

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

Examples

expand all

Run tests and display logged diagnostics by using theLoggingPlugin 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,USV',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 the display of logged diagnostics by using theLoggingPlugin 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 thematlab.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