Main Content

selectFailed

Class: matlab.unittest.plugins.diagnosticrecord.DiagnosticRecord
Package: matlab.unittest.plugins.diagnosticrecord

Return diagnostic records for failed events

Syntax

selectedRecords = selectFailed(records)

Description

selectedRecords = selectFailed(records) returns the diagnostic records for failed events as an array of matlab.unittest.plugins.diagnosticrecord.QualificationDiagnosticRecord and matlab.unittest.plugins.diagnosticrecord.ExceptionDiagnosticRecord instances.

Failed events are events that result in a failure on the TestResult. These events include verification failures, assertion failures, and uncaught MException objects.

Input Arguments

expand all

Recorded diagnostics on a test result, specified as an array of matlab.unittest.plugins.diagnosticrecord.DiagnosticRecord instances. Access recorded diagnostics via the DiagnosticRecord field in the Details property on TestResult. For example, if your test results are stored in the variable results, find the recorded diagnostics for the second test by invoking records = result(2).Details.DiagnosticRecord.

Examples

expand all

In your working folder, create a file, ExampleTest.m, containing the following test class. The intent of this test is to illustrate how to use the DiagnosticsRecordingPlugin plugin, and it is not intended to be a representative unit test.

classdef ExampleTest < matlab.unittest.TestCase  
    methods (Test)
        function testA(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 testB(testCase)
            % This test contains an intentional error - passing a character
            % instead of a variable to the ones function.
            a = [1 2];
            testCase.verifyEqual(ones('a'),[1 1]);  % errors
        end
    end
end

At the command prompt, create a test suite from the ExampleTest class.

suite   = testsuite('ExampleTest');

Create a test runner with no plugins. This code creates a silent runner and provides you with complete control over the installed plugins. Add a DiagnosticsRecordingPlugin to the test runner.

import matlab.unittest.TestRunner;
import matlab.unittest.plugins.DiagnosticsRecordingPlugin;

runner = TestRunner.withNoPlugins;
runner.addPlugin(DiagnosticsRecordingPlugin);

Run the tests.

results = runner.run(suite);

Display the result from the second test. The test fails and is incomplete.

results(2)
ans = 

  TestResult with properties:

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

Totals:
   0 Passed, 1 Failed, 1 Incomplete.
   0.00078912 seconds testing time.

Index into the diagnostic record to display more information.

results(2).Details.DiagnosticRecord
ans = 

  ExceptionDiagnosticRecord with properties:

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

The test throws an uncaught exception.

Collect the diagnostic records for the first test, testA.

testA_records = results(1).Details.DiagnosticRecord
testA_records = 

  1×3 heterogeneous DiagnosticRecord (LoggedDiagnosticRecord, QualificationDiagnosticRecord) array with properties:

    Event
    EventScope
    EventLocation
    Stack
    Report

View the events that the plugin recorded for testA.

{testA_records.Event}'
ans =

  3×1 cell array

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

The plugin records the message logged at a Terse level of verbosity, and the verification and assertion failures.

Create a plugin that records messages at all verbosity levels and includes passing diagnostics. Rerun the tests and collect the diagnostic records for testA.

runner = TestRunner.withNoPlugins;
runner.addPlugin(DiagnosticsRecordingPlugin(...
    'IncludingPassingDiagnostics',true,'OutputDetail',4,'LoggingLevel',4));
results = runner.run(suite);
testA_records = results(1).Details.DiagnosticRecord;

View the events that the plugin recorded for testA.

{testA_records.Event}'
ans =

  6×1 cell array

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

The plugin records diagnostic information for all the qualifications and calls to the log method.

Select all the records with failing event diagnostics.

failedRecords = selectFailed(testA_records)
failedRecords = 

  1×2 QualificationDiagnosticRecord array with properties:

    Event
    EventScope
    EventLocation
    TestDiagnosticResults
    FrameworkDiagnosticResults
    AdditionalDiagnosticResults
    Stack
    Report

Select all the records with passing event diagnostics and display the report for the first record.

passedRecords = selectPassed(testA_records);
passedRecords(1).Report
ans =

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

Select all the records for incomplete events.

incompleteRecords = selectIncomplete(testA_records)
incompleteRecords = 

  QualificationDiagnosticRecord with properties:

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

Since this event is an assertion failure, the framework also returns this record with the failing diagnostics as failedRecords(2).

Select all the records with logged events and display the logged messages.

loggedRecords = selectLogged(testA_records);
{loggedRecords.Report}'
ans =

  2×1 cell array

    {'[Terse] Diagnostic logged (2018-04-12 13:15:23): Terse log message'      }
    {'[Detailed] Diagnostic logged (2018-04-12 13:15:23): Detailed log message'}
Introduced in R2016a