{"id":752,"date":"2016-10-31T14:50:40","date_gmt":"2016-10-31T14:50:40","guid":{"rendered":"https:\/\/blogs.mathworks.com\/developer\/?p=752"},"modified":"2016-10-31T16:21:25","modified_gmt":"2016-10-31T16:21:25","slug":"diagnostic-records","status":"publish","type":"post","link":"https:\/\/blogs.mathworks.com\/developer\/2016\/10\/31\/diagnostic-records\/","title":{"rendered":"Additional Ways to Consume the Secret Sauce"},"content":{"rendered":"

For today's blog entry I'd like to introduce Stephen Carter. Stephen is an engineer on the MATLAB Test Frameworks team and has been involved in many exciting new features over the past few releases (and he continues working on more to come!). Stephen was excited to write a post or two to give you a few hints to help your test diagnostic workflows.<\/i><\/p>

As Andy pointed out in a recent post<\/a>, we try to cook up our secret sauce in a way to make it taste just right. But is taste everything? For example, although Sam, from Dr Seuss's \"Green Eggs and Ham\", came to realize that he did in fact like to eat them in a boat, with a goat, in the rain, and on a train, I personally don't share the same viewpoint as Sam. Even if they are enjoyable on a boat or on a train, I don't think I would want them with a goat or in the rain.<\/p>

What I am getting at is this: in addition to enhancing the diagnostics themselves, we recognize the need to continually provide additional ways for users to consume our diagnostics if they are to be useful for those with different preferences and use cases. Our recent posts<\/a> have been demonstrating ways to consume our diagnostics for the continuous integration use case. But there are a lot more use cases to consider.<\/p>

First, let me start off with a scenario that some of you might relate to. You have just made some final changes to your source code and have already ran a handful of unit tests to give you some confidence to be able to run your full suite of tests before submitting your changes. You run the full suite using runtests<\/a>, which takes, let's say, five to ten minutes, and you see afterward that there are a few failures to address. From the MATLAB command window, you scroll up and find your first failure diagnostic and after reading it you try a few things at the command window to help you understand the failure better. And then of course you do what you always do when you are done playing around at the command window, and you type clc<\/tt> to clear the window<\/a>.<\/p>

Wait... what... oh no! You just lost your entire diagnostic output and you haven't even read the diagnostic messages for the other failures. At this point you are thinking, \"Do I really need to rerun my entire suite to find my failures?\".<\/p>

Before rerunning your entire test suite, first check to see if you still have the TestResult<\/a> output that runtests<\/a> produced.<\/p>

Prior to R2016a, you would see:<\/p>

     \r\nresults = \r\n\r\n  1x1151 TestResult array with properties:\r\n\r\n    Name\r\n    Passed\r\n    Failed\r\n    Incomplete\r\n    Duration\r\n \r\nTotals:\r\n   1148 Passed, 3 Failed, 0 Incomplete.\r\n   266.5616 seconds testing time.\r\n \r\n<\/pre>
You'll notice that pass\/fail information is available. You can use this to shrink the test suite down so that you only have to rerun the tests that did not pass:<\/p>
\r\ndidNotPassResults = results(~[results.Passed]);\r\ntestsToRerun = {didNotPassResults.Name};\r\nruntests(testsToRerun); % Give me my diagnostics back!<\/span><\/pre>
Starting in R2016a, we have provided a more efficient solution to this problem by serving up the diagnostics for you in a new way. You will now see the following TestResult<\/a> display:<\/p>
results\r\n<\/pre>
\r\nresults = \r\n\r\n  1×1151 TestResult array with properties:\r\n\r\n    Name\r\n    Passed\r\n    Failed\r\n    Incomplete\r\n    Duration\r\n    Details\r\n\r\nTotals:\r\n   1148 Passed, 3 Failed, 0 Incomplete.\r\n   261.3082 seconds testing time.\r\n\r\n<\/pre>
Do you see what's new? I'll give you a minute.... do you see the difference now? Ah yes, the new Details<\/tt> property. Let's take a look at the details of the first failing result:<\/p>
firstFailingIndex = find([results.Failed],1);\r\nfirstFailingDetails = results(firstFailingIndex).Details\r\n<\/pre>
\r\nfirstFailingDetails = \r\n\r\n  struct with fields:\r\n\r\n    DiagnosticRecord: [1×1 matlab.unittest.plugins.diagnosticrecord.QualificationDiagnosticRecord]\r\n\r\n<\/pre>
firstFailingDetails.DiagnosticRecord\r\n<\/pre>
\r\nans = \r\n\r\n  QualificationDiagnosticRecord with properties:\r\n\r\n         TestDiagnosticResult: {1×1 cell}\r\n    FrameworkDiagnosticResult: {'Negated IsSubsetOf failed....'}\r\n                        Stack: [1×1 struct]\r\n                        Event: 'VerificationFailed'\r\n                        Scope: 'ATitanicTest\/testAvoidanceSystem'\r\n                       Report: '==========================================...'\r\n\r\n<\/pre>
firstFailingDetails.DiagnosticRecord.Report\r\n<\/pre>
\r\nans =\r\n\r\n================================================================================\r\nVerification failed in ATitanicTest\/testAvoidanceSystem.\r\n\r\n    ----------------\r\n    Test Diagnostic:\r\n    ----------------\r\n    Let's try to avoid hitting things that could end in disaster.\r\n\r\n    ---------------------\r\n    Framework Diagnostic:\r\n    ---------------------\r\n    Negated IsSubsetOf failed.\r\n    --> The actual value is a subset of the prohibited superset.\r\n    \r\n    Actual Value (cell):\r\n            'iceberg'\r\n    Prohibited Superset (cell):\r\n            'land'    'iceberg'    'boat'\r\n\r\n    ------------------\r\n    Stack Information:\r\n    ------------------\r\n    In H:\\Documents\\MATLAB\\SecretSauce\\ATitanicTest.m (ATitanicTest.testAvoidanceSystem) at 5\r\n================================================================================\r\n\r\n\r\n<\/pre>
As you can see, runtests<\/a> now captures failing diagnostics on the TestResult<\/a> output. The driving force behind this is actually a new DiagnosticsRecordingPlugin<\/a>. Manually adding this plugin provides users with even more options, like recording passing diagnostics and controlling the verbosity at which logged diagnostics are recorded.<\/p>
For example, to record passing diagnostics you can do the following:<\/p>
\r\nimport matlab.unittest.TestRunner<\/span>;\r\nimport matlab.unittest.plugins.DiagnosticsRecordingPlugin<\/span>;\r\n\r\nrunner = TestRunner.withTextOutput;\r\nplugin = DiagnosticsRecordingPlugin('IncludingPassingDiagnostics'<\/span>,true);\r\nrunner.addPlugin(plugin);\r\n\r\nresults = runner.run(testsuite);<\/pre>
Now we can find the first passing diagnostic recorded:<\/p>
allDetails = [results.Details];\r\nallDiagnosticRecords = [allDetails.DiagnosticRecord]\r\npassedRecords = selectPassed(allDiagnosticRecords)\r\npassedRecords(1) % look at the record for the first passing event<\/span>\r\n<\/pre>
\r\nallDiagnosticRecords = \r\n\r\n  1×1151 QualificationDiagnosticRecord array with properties:\r\n\r\n    TestDiagnosticResult\r\n    FrameworkDiagnosticResult\r\n    Stack\r\n    Event\r\n    Scope\r\n    Report\r\n\r\n\r\npassedRecords = \r\n\r\n  1×1148 QualificationDiagnosticRecord array with properties:\r\n\r\n    TestDiagnosticResult\r\n    FrameworkDiagnosticResult\r\n    Stack\r\n    Event\r\n    Scope\r\n    Report\r\n\r\n\r\nans = \r\n\r\n  QualificationDiagnosticRecord with properties:\r\n\r\n         TestDiagnosticResult: {}\r\n    FrameworkDiagnosticResult: {'IsEqualTo passed....'}\r\n                        Stack: [1×1 struct]\r\n                        Event: 'VerificationPassed'\r\n                        Scope: 'CapitalGroupStrategyTest\/testStockTicker'\r\n                       Report: '==========================================...'\r\n\r\n<\/pre>
passedRecords(1).Report\r\n<\/pre>
\r\nans =\r\n\r\n================================================================================\r\nVerification passed in CapitalGroupStrategyTest\/testStockTicker.\r\n\r\n    ---------------------\r\n    Framework Diagnostic:\r\n    ---------------------\r\n    IsEqualTo passed.\r\n    --> StringComparator passed.\r\n        --> The character arrays are equal (ignoring case).\r\n        \r\n        Actual char:\r\n            Goog\r\n        Expected char:\r\n            GOOG\r\n\r\n    ------------------\r\n    Stack Information:\r\n    ------------------\r\n    In H:\\Documents\\MATLAB\\SecretSauce\\CapitalGroupStrategyTest.m (CapitalGroupStrategyTest.testStockTicker) at 5\r\n================================================================================\r\n\r\n\r\n<\/pre>
Stay tuned for even more ways to consume our secret sauce.<\/p>