onFailure
Class: matlab.unittest.TestCase
Namespace: matlab.unittest
Dynamically add diagnostics for test failures
Syntax
Description
onFailure(
adds diagnostics for test failures. If a test fails, then the testing framework
executes the diagnostics. By default, these diagnostics execute upon verification
failures, assertion failures, fatal assertion failures, and uncaught
exceptions.testcase
,failureDiag
)
onFailure(
indicates if the testing framework also executes diagnostics upon assumption
failures. To execute diagnostics upon assumption failures also, set
testcase
,failureDiag
,'IncludingAssumptionFailures',tf)tf
to true
.
Input Arguments
testCase
— Instance of test case
matlab.unittest.TestCase
instance
Instance of test case, specified as a
matlab.unittest.TestCase
object.
failureDiag
— Diagnostic information
character vector | string array | function handle | array of matlab.automation.diagnostics.Diagnostic
instances
Diagnostic information to display upon a failure, specified as a character vector,
string array, function handle, or array of
matlab.automation.diagnostics.Diagnostic
instances.
Example: @() disp('Failure Detected')
Example: matlab.unittest.diagnostics.ScreenshotDiagnostic
tf
— React to assumption failures
false
(default) | true
React to assumption failures, specified as false
(logical
0) or true
(logical
1). By default, this value is false
and the testing framework executes diagnostics upon verification failures, assertion
failures, fatal assertion failures, and uncaught exceptions. However, the framework does
not execute diagnostics upon assumption failures. To execute additional diagnostics upon
assumption failures, specify this value as true
.
Examples
Add Diagnostics to Execute upon Test Failure
In your current folder, create the SampleOnFailureTest
test class.
classdef SampleOnFailureTest < matlab.unittest.TestCase methods (TestMethodSetup) function addFailureDiag(testCase) testCase.onFailure('Failure Detected') end end methods (Test) function verificationFailTest(testCase) testCase.onFailure(@()disp(datetime)) testCase.verifyEqual(42,13) end function passingTest(testCase) testCase.assertTrue(true) end function assumptionFailTest(testCase) testCase.assumeEmpty(rand(2)) end function assertionFailTest(testCase) act = randi(100,1,15); floor = randi(100,1,15); f = figure; plot(1:length(act),act,1:length(floor),floor) legend('actual','floor') testCase.addTeardown(@close,f) import matlab.unittest.diagnostics.FigureDiagnostic testCase.onFailure(FigureDiagnostic(f,'Formats','png')) testCase.assertGreaterThan(act,floor) end end end
At the command prompt, run the tests. The SampleOnFailureTest
class has these results:
The diagnostic message
'Failure Detected'
is displayed for each test with a verification, assertion, or fatal assertion failure, becauseaddFailureDiag
callsonFailure
in aTestMethodSetup
block.The
verificationFailTest
test adds another diagnostic upon failure that displays the current date and time.The
assumptionFailTest
test fails by assumption. Therefore, the'Failure Detected'
message is not displayed.The
assertionFailTest
test plots the data. If the test fails, the testing framework saves the plot.
results = runtests('SampleOnFailureTest');
Running SampleOnFailureTest ================================================================================ Verification failed in SampleOnFailureTest/verificationFailTest. --------------------- Framework Diagnostic: --------------------- verifyEqual failed. --> The numeric values are not equal using "isequaln". --> Failure table: Actual Expected Error RelativeError ______ ________ _____ ________________ 42 13 29 2.23076923076923 Actual Value: 42 Expected Value: 13 ---------------------- Additional Diagnostic: ---------------------- Failure Detected ---------------------- Additional Diagnostic: ---------------------- 05-Feb-2021 12:13:36 ------------------ Stack Information: ------------------ In C:\work\MyExamples\SampleOnFailureTest.m (SampleOnFailureTest.verificationFailTest) at 10 ================================================================================ .. ================================================================================ SampleOnFailureTest/assumptionFailTest was filtered. ================================================================================ . ================================================================================ Assertion failed in SampleOnFailureTest/assertionFailTest and it did not run to completion. --------------------- Framework Diagnostic: --------------------- assertGreaterThan failed. --> Each element must be greater than each corresponding element of the minimum value array. Failing Indices: 3 8 10 11 13 15 Actual Value: Columns 1 through 13 44 59 29 8 93 66 31 55 84 52 18 97 23 Columns 14 through 15 95 2 Minimum Value (Exclusive): Columns 1 through 13 3 23 32 5 43 1 17 76 62 91 51 33 26 Columns 14 through 15 11 100 ---------------------- Additional Diagnostic: ---------------------- Failure Detected ---------------------- Additional Diagnostic: ---------------------- Figure saved to: --> C:\work\Temp\Figure_20a2887e-85de-4398-8aa4-26ef8d3d921d.png ------------------ Stack Information: ------------------ In C:\work\MyExamples\SampleOnFailureTest.m (SampleOnFailureTest.assertionFailTest) at 27 ================================================================================ . Done SampleOnFailureTest __________ Failure Summary: Name Failed Incomplete Reason(s) ======================================================================================= SampleOnFailureTest/verificationFailTest X Failed by verification. --------------------------------------------------------------------------------------- SampleOnFailureTest/assumptionFailTest X Filtered by assumption. --------------------------------------------------------------------------------------- SampleOnFailureTest/assertionFailTest X X Failed by assertion.
Tips
To add a diagnostic for each test in your class, call
onFailure
from a method in theTestMethodSetup
block.
Version History
Introduced in R2017b
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)