matlab.unittest.plugins.DiagnosticsRecordingPlugin - Plugin that records diagnostics on test results - MATLAB (original) (raw)

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 thematlab.automation.Verbosity.Terse level.

example

plugin = matlab.unittest.plugins.DiagnosticsRecordingPlugin([Name=Value](#namevaluepairarguments)) 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.

example

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

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.

Verbosity level of logged diagnostics, specified as an integer scalar from0 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 thematlab.automation.Verbosity.Terse level (level 1). To exclude logged diagnostics, specify LoggingLevel asmatlab.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"

Recording level of event details, specified as an integer scalar from0 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 thematlab.automation.Verbosity.Detailed level (level 3).

This argument sets the OutputDetail property.

Example: OutputDetail="Concise"

Properties

expand all

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

Verbosity level of logged diagnostics, specified as an integer scalar from0 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 thematlab.automation.Verbosity.Terse level.

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

Attributes:

GetAccess public
SetAccess private

Recording level of event details, specified as an integer scalar from0 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 thematlab.automation.Verbosity.Detailed level.

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

Attributes:

GetAccess public
SetAccess private

Examples

collapse all

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

In a file named ExampleTest.m in your current folder, create theExampleTest 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 theones 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 aDiagnosticsRecordingPlugin 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.

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 theDiagnosticRecord 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, aDiagnosticsRecordingPlugin instance records only diagnostics for failing events and events logged at thematlab.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 thematlab.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 thelog 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

See Also

Classes