addTeardown

Class: matlab.unittest.TestCase
Namespace: matlab.unittest

Dynamically add teardown code to test case

Syntax

addTeardown(testCase,teardownFcn)

addTeardown(testCase,teardownFcn,input1,...,inputN)

Description

addTeardown(testCase,teardownFcn) registers the teardown code teardownFcn with the test case. To dynamically run teardown code when tests run, use addTeardown within a Test method, TestMethodSetup method, or TestClassSetup method. The timing and frequency of the teardown actions depend on the scope in which you call the method:

• Test method — teardownFcn runs after the current test.

• TestMethodSetup method — teardownFcn runs after each test in the test class.

• TestClassSetup method — teardownFcn runs a single time after all the tests in the class.

To restore the environment, the method enforces a last-in, first-out (LIFO) policy so that teardown actions are performed in the reverse order of their corresponding setup actions. Use addTeardown to achieve test content that is exception safe.

addTeardown(testCase,teardownFcn,input1,...,inputN) also specifies the input arguments with which teardownFcn is invoked for fixture teardown.

Input Arguments

testCase — Test case

matlab.unittest.TestCase object

Test case, specified as a matlab.unittest.TestCase object.

teardownFcn — Teardown code

function handle

Teardown code, specified as a function handle.

Example: addTeardown(testCase,@() format(originalFormat))

input1,...,inputN — Input arguments of function handle

comma-separated list

Input arguments with which the function handle teardownFcn is invoked for fixture teardown, specified as a comma-separated list of values.

Example: addTeardown(testCase,@close,fig)

Example: addTeardown(testCase,@setenv,"UserName",originalUserName)

Attributes

Sealed

true

To learn about attributes of methods, see Method Attributes.

Examples

Add Teardown Code for Each Test

Dynamically execute teardown code after each test runs.

In a file in your current folder, create the FigurePropertiesTest class. Define two Test methods in the class that each verify a figure property. To create a fresh figure for each test, use a TestMethodSetup methods block. To restore the environment after each test, call the addTeardown method in the same block.

classdef FigurePropertiesTest < matlab.unittest.TestCase
    properties
        TestFigure
    end

    methods (TestMethodSetup)
        function createFigure(testCase)
            testCase.TestFigure = figure;
            testCase.addTeardown(@close,testCase.TestFigure)
        end
    end

    methods (Test)
        function defaultCurrentPoint(testCase)
            cp = testCase.TestFigure.CurrentPoint;
            testCase.verifyEqual(cp,[0 0], ...
                "Default current point must be [0 0].")
        end

        function defaultCurrentObject(testCase)
            import matlab.unittest.constraints.IsEmpty
            co = testCase.TestFigure.CurrentObject;
            testCase.verifyThat(co,IsEmpty, ...
                "Default current object must be empty.")
        end
    end
end

Run the tests. Once a test runs to completion, the testing framework automatically closes the figure for that test by invoking the function handle passed to addTeardown.

results = runtests("FigurePropertiesTest");

Running FigurePropertiesTest

.

.
Done FigurePropertiesTest
__________

More About

Exception Safe

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.assertEqual(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.assertEqual(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 to addTeardown is after the test. If the test fails, the framework does not close the figure.

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

Version History

Introduced in R2013a