matlab.unittest.qualifications.FatalAssertable class

Package: matlab.unittest.qualifications

Qualification to abort test execution

Description

The FatalAssertable class provides a qualification to abort test execution. Apart from actions performed for failures, the FatalAssertable class works the same as matlab.unittest qualifications.

Upon a fatal assertion failure, the FatalAssertable class informs the testing framework of the failure by throwing a FatalAssertionFailedException. The test running framework then displays diagnostic information for the failure and aborts the entire test session. This is useful when the software under test contains so many errors that it does not make sense to continue the test session. Also, you can use fatal assertions in fixture teardown to guarantee the fixture state is restored correctly. If it is not restored, the full testing session will aborts and indicates to restart MATLAB^® before you resume testing. This allows later tests to run in a consistent MATLAB state. If you can recover the fixture teardown and make it Exception Safe for failures, use assertions instead.

Fatal assertions prevent false test failures due to the failure of a fundamental test. They also prevent false test failures when a prior test failed to restore test fixtures. If the test framework cannot properly tear down fixtures, restart MATLAB to ensure testing can resume in a clean state.

Methods

fatalAssertClass	Fatally assert exact class of specified value
fatalAssertEmpty	Fatally assert value is empty
fatalAssertEqual	Fatally assert value is equal to specified value
fatalAssertError	Fatally assert function throws specified exception
fatalAssertFail	Produce unconditional fatal assertion failure
fatalAssertFalse	Fatally assert value is false
fatalAssertGreaterThanOrEqual	Fatally assert value is greater than or equal to specified value
fatalAssertInstanceOf	Fatally assert value is object of specified type
fatalAssertLength	Fatally assert value has specified length
fatalAssertLessThan	Fatally assert value is less than specified value
fatalAssertLessThanOrEqual	Fatally assert value is less than or equal to specified value
fatalAssertMatches	Fatally assert string matches specified regular expression
fatalAssertNotEmpty	Fatally assert value is not empty
fatalAssertNotEqual	Fatally assert value is not equal to specified value
fatalAssertNotSameHandle	Fatally assert value is not handle to specified instance
fatalAssertNumElements	Fatally assert value has specified element count
fatalAssertReturnsTrue	Fatally assert function returns true when evaluated
fatalAssertSameHandle	Fatally assert two values are handles to same instance
fatalAssertSize	Fatally assert value has specified size
fatalAssertSubstring	Fatally assert string contains specified string
fatalAssertThat	Fatally assert value meets specified constraint
fatalAssertTrue	Fatally assert value is true
fatalAssertWarning	Fatally assert function issues specified warning
fatalAssertWarningFree	Fatally assert function issues no warnings

Events

`FatalAssertionFailed`	Triggered upon failing fatal assertion. A `QualificationEventData` object is passed to listener callback functions.
`FatalAssertionPassed`	Triggered upon passing fatal assertion. A `QualificationEventData` object is passed to listener callback functions.

Definitions

Exception Safe

Test content is exception safe when all fixture teardown is performed with addTeardown or through the appropriate object destructors when a failure occurs. This ensures that the failure does not affect later testing due to stale fixtures.

This code is not exception safe. After an assertion failure, the test framework does not close the figure.

% Not exception safe
f = figure;
testCase.fatalAssertEqual(actual, expected)
close(f)

This code is exception safe because the test framework closes the figure in all cases.

% Exception safe
f = figure;
testCase.addTeardown(@close, f)
testCase.fatalAssertEqual(actual, expected)

However, tearing down a fixture using addTeardown does not guarantee code is exception safe. This code shows a failure in fatalAssertEqual.

% Not exception safe
f = figure;
testCase.fatalAssertEqual(actual, expected);
testCase.addTeardown(@close, f)

Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects in the MATLAB documentation.

Examples

expand all

Write Helper Function Using Fatal Assertions

A fatal assertion renders the remainder of the current test method invalid because the state is unrecoverable. A helper function is a function in the TestCase class but not located within any of the methods block statement. Execution of these functions is not controlled by the matlab.unittest framework.

Add the DocPolynomSaveLoadTest.m file to a folder on your MATLAB path. Refer to the helper function, cleanUpTemporaryFolder, in the DocPolynomSaveLoadTest test case.

DocPolynomSaveLoadTest Class Definition File

classdef DocPolynomSaveLoadTest < matlab.unittest.TestCase 
    
    methods (TestClassSetup) 
        function addDocPolynomClassToPath(testCase) 
            origPath = path; 
            testCase.addTeardown(@path, origPath); 
            addpath(fullfile(matlabroot, ... 
                'help', 'techdoc', 'matlab_oop', 'examples')); 
        end 
    end 
     
    methods (Test) 
        function testSaveLoad(testCase) 
             
            import matlab.unittest.diagnostics.Diagnostic; 
             
            %% Phase 1: Setup 
            % Create a temporary working folder 
            tempFolder = tempname; 
            [success, message] = mkdir(tempFolder); 
            testCase.assertTrue(success, ... 
                Diagnostic.join('Could not create temporary folder.',... 
                message)); 
            testCase.addTeardown(@() testCase.cleanUpTemporaryFolder(...
                tempFolder)); 
             
            % Change to the temporay folder and register the 
            % teardown, which restores the original folder 
            origFolder = pwd; 
            testCase.addTeardown(@cd, origFolder); 
            cd(tempFolder); 
             
            %% Phase 2: Exercise 
            % Save the instance to a mat file. 
            p = DocPolynom([1, 0, 1]); 
            save('DocPolynomFile', 'p'); 
             
            % Validate Precondition. Save resulted in valid .mat file 
            testCase.assertEqual(exist('DocPolynomFile.mat','file'),... 
                2, Diagnostic.join(...
                'mat file was not saved correctly.',@() dir(pwd))); 
             
            loaded = load('DocPolynomFile'); 
             
             
            %% Phase 3: Verify             
            testCase.verifyEqual(loaded.p, p,...
                'Loaded polynom did not equal original polynom.');
             
             
            %% Phase 4: Teardown 
            % Done inline via calls to addTeardown at the points
            % at which the state was changed. 

             
        end 
    end 
     
    methods(Access=private) 
        function cleanUpTemporaryFolder(testCase,tempFolder)
            % Clean up the temporary folder and fatally assert
            % that it was correctly cleaned up.
             
            import matlab.unittest.diagnostics.Diagnostic; 
             
            [success, message] = rmdir(tempFolder, 's'); 
            testCase.fatalAssertTrue(success, ... 
                Diagnostic.join('Could not remove temporary folder.',... 
                message)); 
        end 
    end 
             
end

Make the cleanUpTemporaryFolder function a helper function by placing it inside a separate methods block.

methods(Access=private) 
    function cleanUpTemporaryFolder(testCase, tempFolder) 
        % code 
    end 
end

Use the fatalAssertTrue method to test the rmdir success argument for errors. If a fatal assertion occurs, the test run is aborted.

function cleanUpTemporaryFolder(testCase, tempFolder) 
     
    import matlab.unittest.diagnostics.Diagnostic
     
    [success, message] = rmdir(tempFolder, 's'); 
    testCase.fatalAssertTrue(success, ... 
        Diagnostic.join('Could not remove the temporary folder.',... 
        message))
end

If the rmdir function fails, then this test has failed to restore the state of MATLAB and the machine at initial startup. Aborting prevents subsequent tests to fail because MATLAB is left in an unexpected state by this test.

Documentation

matlab.unittest.qualifications.FatalAssertable class

Description

Methods

Events

Definitions

Exception Safe

Copy Semantics

Examples

Write Helper Function Using Fatal Assertions

See Also

More About

Introduced in R2013a

MATLAB Documentation

Other Documentation

Support