Main Content

onFailure

Class: matlab.unittest.fixtures.Fixture
Namespace: matlab.unittest.fixtures

Dynamically add diagnostics for failures during fixture setup and teardown

expand all in page

Syntax

onFailure(fixture,failureDiag)
onFailure(fixture,failureDiag,'IncludingAssumptionFailures',tf)

Description

onFailure(fixture,failureDiag) adds diagnostics for failures during fixture setup and teardown routines. If the test framework encounters a failure, then it executes the diagnostics. By default, these diagnostics execute upon verification failures, assertion failures, fatal assertion failures, and uncaught exceptions.

example

onFailure(fixture,failureDiag,'IncludingAssumptionFailures',tf) indicates if the test framework also executes diagnostics upon assumption failures. To execute diagnostics upon assumption failures also, set tf to true.

Input Arguments

expand all

Instance of fixture, specified as a matlab.unittest.fixtures.Fixture.

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

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

expand all

In your current working folder, create the FormatHexFixture fixture. The test framework encounters an assertion failure during fixture setup and displays the diagnostic message upon failure.

classdef FormatHexFixture < matlab.unittest.fixtures.Fixture
    properties (Access=private)
        OriginalFormat
    end
    methods
        function setup(fixture)
            fixture.OriginalFormat = format().NumericFormat;
            format("hex")
            fixture.addTeardown(@format,fixture.OriginalFormat)
            
            fixture.onFailure(['Failure detected in ' mfilename("class")])
            fixture.assertEqual(format().NumericFormat,"short")
        end
    end
end

Create the following test class, SampleTest.m, in your current working folder.

classdef SampleTest < matlab.unittest.TestCase
    methods (Test)
        function test1(testCase)
            testCase.applyFixture(FormatHexFixture);
            actStr = getColumnForDisplay([1;2;3], 'Small Integers');
            expStr = ['Small Integers  '
                '3ff0000000000000'
                '4000000000000000'
                '4008000000000000'];
            testCase.verifyEqual(actStr, expStr)
        end
    end
end

function str = getColumnForDisplay(values, title)
elements = cell(numel(values)+1, 1);
elements{1} = title;
for idx = 1:numel(values)
    elements{idx+1} = displayNumber(values(idx));
end
str = char(elements);
end

function str = displayNumber(n)
str = strtrim(evalc('disp(n);'));
end

Run the test. Note the onFailure diagnostics appear under the "Additional Diagnostics" heading.

results = runtests('SampleTest');
Running SampleTest

================================================================================
Assertion failed in SampleTest/test1 and it did not run to completion.
    ---------------------
    Framework Diagnostic:
    ---------------------
    assertEqual failed.
    --> The strings are not equal.
    
    Actual Value:
        "hex"
    Expected Value:
        "short"
    ----------------------
    Additional Diagnostic:
    ----------------------
    Failure detected in FormatHexFixture
    ------------------
    Stack Information:
    ------------------
    In C:\work\FormatHexFixture.m (FormatHexFixture.setup) at 12
================================================================================
.
Done SampleTest
__________

Failure Summary:

     Name              Failed  Incomplete  Reason(s)
    ============================================================
     SampleTest/test1    X         X       Failed by assertion.

Version History

Introduced in R2017b

expand all

See Also