matlab.unittest.plugins.LoggingPlugin Class

Namespace: matlab.unittest.plugins
Superclasses: matlab.unittest.plugins.TestRunnerPlugin, matlab.unittest.plugins.Parallelizable

Plugin that displays logged diagnostics

expand all in page

Description

The matlab.unittest.plugins.LoggingPlugin class provides a plugin that displays logged diagnostic messages. Logged diagnostics are diagnostics that you supply to the unit testing framework with the log (TestCase) and log (Fixture) methods.

The matlab.unittest.plugins.LoggingPlugin class is a handle class.

Creation

To create a LoggingPlugin instance, use the withVerbosity static method.

Properties

expand all

Verbosity levels, specified as an integer scalar from 0 through 4, a matlab.automation.Verbosity enumeration object, or a text representation of the enumeration, and stored as a matlab.automation.Verbosity enumeration vector. The plugin displays diagnostics logged at the levels in the stored enumeration vector.

You must specify a verbosity level during creation of the plugin, and this property stores a vector of all verbosity levels at or below the specified level. If you specify the ExcludingLowerLevels name-value argument as true during creation of the plugin, then this property stores just the specified verbosity level.

Attributes:

GetAccess
public
SetAccess
private

Description of logged diagnostic messages, specified as a string scalar or character vector, and stored as a character vector. The plugin displays the description alongside each logged message. You can specify the value of this property during creation of the plugin.

Attributes:

GetAccess
public
SetAccess
private

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. You can specify the value of this property during creation of the plugin.

Attributes:

GetAccess
public
SetAccess
private

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. You can specify the value of this property during creation of the plugin.

Attributes:

GetAccess
public
SetAccess
private

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. You can specify the value of this property during creation of the plugin.

Attributes:

GetAccess
public
SetAccess
private

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

Methods

expand all

Examples

collapse all

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

See Also

Functions

Classes