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(
specifies options using one or more name-value arguments. For example, Name=Value
)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)
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 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"
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
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 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 |
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
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
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)