matlab.unittest.plugins.DiagnosticsRecordingPlugin Class

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

Plugin that records diagnostics on test results

Description

The matlab.unittest.plugins.DiagnosticsRecordingPlugin class provides a plugin that records diagnostics on test results. After running tests using a test runner configured with this plugin, you can programmatically access the recorded diagnostics from the DiagnosticRecord field in the Details property of TestResult objects. For more information, see Programmatically Access Test Diagnostics.

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

Creation

Description

plugin = matlab.unittest.plugins.DiagnosticsRecordingPlugin creates a plugin that records diagnostics on test results. By default, the plugin records diagnostics for failing events and events logged at the matlab.automation.Verbosity.Terse level.

plugin = matlab.unittest.plugins.DiagnosticsRecordingPlugin(Name=Value) specifies options using one or more name-value arguments. For example, plugin = matlab.unittest.plugins.DiagnosticsRecordingPlugin(IncludingPassingDiagnostics=true) creates a plugin that records passing diagnostics in addition to diagnostics for failing and logged events.

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.DiagnosticsRecordingPlugin(IncludingPassingDiagnostics=true)

IncludingPassingDiagnostics — Option to include diagnostics for passing events

false or 0 (default) | true or 1

Option to include the diagnostics for passing events, specified as a numeric or logical 0 (false) or 1 (true). By default, the plugin does not include the diagnostics for passing events.

This argument sets the IncludePassingDiagnostics property.

LoggingLevel — Verbosity level of logged diagnostics

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

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

By default, the plugin includes diagnostics logged at the matlab.automation.Verbosity.Terse level (level 1). To exclude logged diagnostics, specify LoggingLevel as matlab.automation.Verbosity.None (level 0).

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

This argument sets the LoggingLevel property.

Example: LoggingLevel="Detailed"

OutputDetail — Recording level of event details

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

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

The plugin supports the recording of passing, failing, and logged events. By default, the plugin records event details at the matlab.automation.Verbosity.Detailed level (level 3).

This argument sets the OutputDetail property.

Example: OutputDetail="Concise"

Properties

IncludePassingDiagnostics — Option to include diagnostics for passing events

false or 0 (default) | true or 1

Option to include the diagnostics for passing events, specified as a numeric or logical 0 (false) or 1 (true). If the value is true, then the plugin includes the diagnostics for passing events. By default, the plugin does not include the diagnostics for passing events.

This property is set by the IncludingPassingDiagnostics name-value argument.

Attributes:

GetAccess	public
SetAccess	immutable

LoggingLevel — Verbosity level of logged diagnostics

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

Verbosity level of logged diagnostics, 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 object. By default, the plugin includes diagnostics logged at the matlab.automation.Verbosity.Terse level.

This property is set by the LoggingLevel name-value argument.

Attributes:

GetAccess	public
SetAccess	private

OutputDetail — Recording level of event details

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

Recording level of event details, 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 object. By default, the plugin records event details at the matlab.automation.Verbosity.Detailed level.

This property is set by the OutputDetail name-value argument.

Attributes:

GetAccess	public
SetAccess	private

Examples

Record Diagnostics on Test Results

Run tests and record diagnostics on the test results by using the DiagnosticsRecordingPlugin class.

In a file named ExampleTest.m in your current folder, create the ExampleTest test class. The contents of the Test methods in the class are for illustrative purposes. The testOne method includes diagnostics logged at the Terse and Detailed levels and qualifications that pass and fail. The testTwo method includes an intentional bug—the test passes a character instead of a variable to the ones function.

classdef ExampleTest < matlab.unittest.TestCase
    methods (Test)
        function testOne(testCase)
            testCase.log(1,"Terse log message")     % logs
            testCase.log(3,"Detailed log message")  % logs
            testCase.verifyEqual(3+2,5)             % passes
            testCase.assumeTrue(true)               % passes
            testCase.verifyGreaterThan(5,9)         % fails
            testCase.assertEqual(3.14,pi)           % fails/incomplete
        end

        function testTwo(testCase)
            a = [1 2];
            testCase.verifyEqual(ones('a'),[1 1])   % errors
        end
    end
end

Import the DiagnosticsRecordingPlugin class.

import matlab.unittest.plugins.DiagnosticsRecordingPlugin

Create a test suite from the test class.

suite = testsuite("ExampleTest");

Create a test runner and configure it using a DiagnosticsRecordingPlugin instance. Then, run the tests. The plugin records diagnostics on the test results.

runner = testrunner("minimal");
plugin = DiagnosticsRecordingPlugin;
runner.addPlugin(plugin)
results = runner.run(suite);

Display the result of the second test. Due to the intentional error in the test code, the test fails and remains incomplete.

results(2)

ans = 

  TestResult with properties:

          Name: 'ExampleTest/testTwo'
        Passed: 0
        Failed: 1
    Incomplete: 1
      Duration: 8.0680e-04
       Details: [1×1 struct]

Totals:
   0 Passed, 1 Failed (rerun), 1 Incomplete.
   0.0008068 seconds testing time.

Access the recorded diagnostic for the second test using the DiagnosticRecord field in the Details property of the TestResult object. The record indicates that the test threw an uncaught error.

results(2).Details.DiagnosticRecord

ans = 

  ExceptionDiagnosticRecord with properties:

                          Event: 'ExceptionThrown'
                     EventScope: TestMethod
                  EventLocation: 'ExampleTest/testTwo'
                      Exception: [1×1 MException]
    AdditionalDiagnosticResults: [1×0 matlab.automation.diagnostics.DiagnosticResult]
                          Stack: [1×1 struct]
                         Report: 'Error occurred in ExampleTest/testTwo and it did not run to completion.↵ ...'

View the events that the plugin recorded for testOne. By default, a DiagnosticsRecordingPlugin instance records only diagnostics for failing events and events logged at the matlab.automation.Verbosity.Terse level.

testOneRecords = results(1).Details.DiagnosticRecord;
{testOneRecords.Event}'

ans =

  3×1 cell array

    {'DiagnosticLogged'  }
    {'VerificationFailed'}
    {'AssertionFailed'   }

Now, run the tests using a plugin that records the details of all events (that is, passing events, failing events, and events logged at any level) at the matlab.automation.Verbosity.Detailed level.

runner = testrunner("minimal");
plugin = DiagnosticsRecordingPlugin( ...
    IncludingPassingDiagnostics=true, ...
    LoggingLevel="Verbose", ...
    OutputDetail="Detailed");
runner.addPlugin(plugin)
results = runner.run(suite);

View the events that the plugin recorded for testOne. The plugin recorded diagnostic information for all the qualifications and calls to the log method.

testOneRecords = results(1).Details.DiagnosticRecord;
{testOneRecords.Event}'

ans =

  6×1 cell array

    {'DiagnosticLogged'  }
    {'DiagnosticLogged'  }
    {'VerificationPassed'}
    {'AssumptionPassed'  }
    {'VerificationFailed'}
    {'AssertionFailed'   }

Return the diagnostic records for failed events in testOne.

failedRecords = selectFailed(testOneRecords)

failedRecords = 

  1×2 QualificationDiagnosticRecord array with properties:

    Event
    EventScope
    EventLocation
    TestDiagnosticResults
    FrameworkDiagnosticResults
    AdditionalDiagnosticResults
    Stack
    Report

Return the records for passed events, and display the report for the first record.

passedRecords = selectPassed(testOneRecords);
passedRecords(1).Report

ans =

    'Verification passed in ExampleTest/testOne.
         ---------------------
         Framework Diagnostic:
         ---------------------
         verifyEqual passed.
         --> The numeric values are equal using "isequaln".
         
         Actual Value:
              5
         Expected Value:
              5
         ------------------
         Stack Information:
         ------------------
         In C:\work\ExampleTest.m (ExampleTest.testOne) at 6'

Return the records for any incomplete events in testOne. Because the incomplete event in the test is due to an assertion failure, the testing framework also includes this record as part of the records for failed events (failedRecords(2)).

incompleteRecords = selectIncomplete(testOneRecords)

incompleteRecords = 

  QualificationDiagnosticRecord with properties:

                          Event: 'AssertionFailed'
                     EventScope: TestMethod
                  EventLocation: 'ExampleTest/testOne'
          TestDiagnosticResults: [1×0 matlab.automation.diagnostics.DiagnosticResult]
     FrameworkDiagnosticResults: [1×1 matlab.automation.diagnostics.DiagnosticResult]
    AdditionalDiagnosticResults: [1×0 matlab.automation.diagnostics.DiagnosticResult]
                          Stack: [1×1 struct]
                         Report: 'Assertion failed in ExampleTest/testOne and it did not run to completion.↵ ...'

Return the records for logged events, and display the logged messages.

loggedRecords = selectLogged(testOneRecords);
{loggedRecords.Report}'

ans =

  2×1 cell array

    {'[Terse] Diagnostic logged (2024-08-21 17:00:01): Terse log message'      }
    {'[Detailed] Diagnostic logged (2024-08-21 17:00:01): Detailed log message'}

Version History

Introduced in R2016a