Main Content

matlab.unittest.qualifications.FatalAssertable Class

Namespace: matlab.unittest.qualifications

Qualification to abort test execution

expand all in page

Description

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

Upon a fatal assertion failure, the FatalAssertable class informs the testing framework of the failure by throwing a FatalAssertionFailedException object. The framework then displays diagnostic information for the failure and aborts the test session. This behavior is useful when the failure is so fundamental that continuing testing does not make sense. Also, you can use fatal assertions in fixture teardown to guarantee that the environment state is restored correctly. If you can make the fixture teardown exception safe and restore the state after failure, 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 fails to restore the state. If the framework cannot properly tear down fixtures, you must manually reset the state. For example, you might need to restart MATLAB®.

The matlab.unittest.qualifications.FatalAssertable class is a handle class.

Methods

expand all

Events

Event NameTriggerEvent DataEvent Attributes
FatalAssertionFailedTriggered upon failing fatal assertion. A QualificationEventData object is passed to listener callback functions.matlab.unittest.qualifications.QualificationEventData

NotifyAccess: private

ListenAccess: public

FatalAssertionPassedTriggered upon passing fatal assertion. A QualificationEventData object is passed to listener callback functions.matlab.unittest.qualifications.QualificationEventData

NotifyAccess: private

ListenAccess: public

Examples

collapse all

Open Live Script

Test a function that sets the value of an operating system environment variable. If the environment variable cannot be reset to its original value after the test, abort the test session using a fatal assertion failure.

In a file in your current folder, create the setUserName function. The function uses a call to setenv to set the 'UserName' environment variable.

function setUserName(name)
setenv('UserName',name)
end

To test the setUserName function, create a test class named SetUserNameTest in your current folder. Define the necessary class members for your test:

  • OriginalUserName property — Use this property to reset the environment variable after the test.

  • testUpdate Test method — Store the original value of the environment variable, call the function under test, and verify that the function sets the environment variable to the expected value. Because the state changes during the test, include a call to addTeardown to restore the state once the test runs to completion.

  • resetUserName helper method — Call the setUserName function to reset the environment variable. If the operation is not successful, abort the test session using a fatal assertion failure.

classdef SetUserNameTest < matlab.unittest.TestCase
    properties (SetAccess = private)
        OriginalUserName
    end
    
    methods (Test)
        function testUpdate(testCase)
            testCase.OriginalUserName = getenv('UserName');
            setUserName('David')
            testCase.addTeardown(@() testCase.resetUserName)
            testCase.verifyEqual(getenv('UserName'),'David')
        end
    end

    methods (Access = private)
        function resetUserName(testCase)
            setUserName(testCase.OriginalUserName)
            testCase.fatalAssertEqual(getenv('UserName'),testCase.OriginalUserName)
        end
    end
end

Run the SetUserNameTest class. The test passes.

runtests("SetUserNameTest")
Running SetUserNameTest
.
Done SetUserNameTest
__________

ans = 
  TestResult with properties:

          Name: 'SetUserNameTest/testUpdate'
        Passed: 1
        Failed: 0
    Incomplete: 0
      Duration: 0.0226
       Details: [1×1 struct]

Totals:
   1 Passed, 0 Failed, 0 Incomplete.
   0.022649 seconds testing time.

More About

expand all

Version History

Introduced in R2013a

expand all

See Also

Classes

Topics