onFailure

Class: matlab.unittest.fixtures.Fixture
Package: matlab.unittest.fixtures

Dynamically add diagnostics for failures during fixture setup and teardown

expand all in page

In release R2019a, onFailure method has protected access.

Syntax

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

Description

example

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.

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.unittest.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 test framework executes diagnostics upon verification failures, assertion failures, fatal assertion failures, and uncaught exceptions. However, the test 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 = get(0,'Format');
            set(0,'Format','hex')
            fixture.addTeardown(@set,0,'Format',fixture.OriginalFormat)
            
            fixture.onFailure(['Failure detected in ' mfilename('class')])
            fixture.assertEqual(get(0,'Format'),'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('SampleFixtureTest');
Running SampleFixtureTest

================================================================================
Assertion failed in SampleFixtureTest/test1 and it did not run to completion.

    ---------------------
    Framework Diagnostic:
    ---------------------
    assertEqual failed.
    --> The character arrays are not equal.
    
    Actual char:
        hex
    Expected char:
        short

    ----------------------
    Additional Diagnostic:
    ----------------------
    Failure Detected in FormatHexFixture

    ------------------
    Stack Information:
    ------------------
    In C:\work\FormatHexFixture.m (FormatHexFixture.setup) at 11
================================================================================
.
Done SampleFixtureTest
__________

Failure Summary:

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

Compatibility Considerations

expand all

Behavior changed in R2019a

See Also

Introduced in R2017b

MATLAB Documentation

Support