matlab.unittest.qualifications.FatalAssertable - Qualification to abort test execution - MATLAB (original) (raw)

Namespace: 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 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

The FatalAssertable class provides several qualification methods for testing values and responding to failures. For example, fatalAssertEmpty tests that a value is empty, and fatalAssertTrue tests that the actual value is true.

Note

The methods of the FatalAssertable class correspond to the methods of the Verifiable class. They differ only in terms of qualification type. You can call the FatalAssertable methods in the same way you call the Verifiable methods.

General Purpose

Errors and Warnings

Inequalities

Array Size

Type

Strings

Baselines

Events

Examples

collapse all

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

Depending on the test runner configuration, the testing framework might display diagnostics when a qualification passes or fails. By default, the framework displays diagnostics only when the qualification fails. You can override the default behavior by customizing the test runner. For example, you can use a DiagnosticsOutputPlugin instance to display both failing and passing event diagnostics.

To add a diagnostic message to a test case, use the optionaldiagnostic argument in any of the qualification methods. You can specify diagnostic as a string array, character array, function handle, or array of matlab.automation.diagnostics.Diagnostic objects.

Test content sometimes changes the state of its environment. The content is exception safe when the environment can be restored to its original state, even in the presence of exceptions. Exception safety ensures that a test that throws an exception does not affect subsequent tests by corrupting the environment. To achieve exception safety, perform all teardown actions using the addTeardown method. Call addTeardown immediately before or after the original state change, without any other code in between that can throw an exception.

For example, this code is not exception safe. If the test fails, the testing framework does not close the figure. The presence of this figure might cause subsequent tests to fail.

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

On the other hand, this code is exception safe, because the framework closes the figure regardless of the test outcome.

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

Tearing down a fixture using addTeardown does not guarantee that code is exception safe. This code is not exception safe, because the call toaddTeardown is after the test. If the test fails, the framework does not close the figure.

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

Version History

Introduced in R2013a

expand all

If you have a MATLAB Test license, you can use the fatalAssertEqualsBaseline method to test if a value is equal to baseline data.

See Also

Classes

• matlab.unittest.qualifications.Verifiable | matlab.unittest.qualifications.Assumable | matlab.unittest.qualifications.Assertable | matlab.unittest.TestCase | matlab.unittest.qualifications.QualificationEventData

Topics

• Table of Verifications, Assertions, and Other Qualifications