MATLAB Examples

Write Test Using Setup and Teardown Functions

This example shows how to write a unit test for a couple of MATLAB® figure axes properties using fresh fixtures and file fixtures.

Contents

Create axesPropertiesTest File

Create a file containing the main function that tests figure axes properties and include two test functions. One function verifies that the x-axis limits are correct, and the other one verifies that the face color of a surface is correct.

In a folder on your MATLAB path, create axesPropertiesTest.m. In the main function of this file, have functiontests create an array of tests from each local function in axesPropertiesTest.m with a call to the localfunctions function.


% Copyright 2015 The MathWorks, Inc.

function tests = axesPropertiesTest
tests = functiontests(localfunctions);
end

Create File Fixture Functions

File fixture functions are setup and teardown code that runs a single time in your test file. These fixtures are shared across the test file. In this example, the file fixture functions create a temporary folder and set it as the current working folder. They also create and save a new figure for testing. After tests are complete, the framework reinstates the original working folder and deletes the temporary folder and saved figure.

In this example, a helper function creates a simple figure — a red cylinder. In a more realistic scenario, this code is part of the product under test and is computationally expensive, thus motivating the intent to create the figure only once and to load independent copies of the result for each test function. For this example, however, you want to create this helper function as a local function to axesPropertiesTest. Note that the test array does not include the function because its name does not start or end with ‘test’.

Write a helper function that creates a simple red cylinder and add it as a local function to axesPropertiesTest.


% Copyright 2015 The MathWorks, Inc.

function f = createFigure
f = figure;
ax = axes('Parent', f);
cylinder(ax,10)
h = findobj(ax,'Type','surface');
h.FaceColor = [1 0 0];
end

You must name the setup and teardown functions of a file test fixture setupOnce and teardownOnce, respectively. These functions take a single input argument, testCase, into which the test framework automatically passes a function test case object. This test case object contains a TestData structure that allows data to pass between setup, test, and teardown functions. In this example, the TestData structure uses assigned fields to store the original path, the temporary folder name, and the figure file name.

Create the setup and teardown functions as a local functions to axesPropertiesTest.


% Copyright 2015 The MathWorks, Inc.

function setupOnce(testCase)
% create and change to temporary folder
testCase.TestData.origPath = pwd;
testCase.TestData.tmpFolder = ['tmpFolder' datestr(now,30)];
mkdir(testCase.TestData.tmpFolder)
cd(testCase.TestData.tmpFolder)

% create and save a figure
testCase.TestData.figName = 'tmpFig.fig';
aFig = createFigure;
saveas(aFig,testCase.TestData.figName,'fig')
close(aFig)
end

function teardownOnce(testCase)
delete(testCase.TestData.figName)
cd(testCase.TestData.origPath)
rmdir(testCase.TestData.tmpFolder)
end

Create Fresh Fixture Functions

Fresh fixtures are function level setup and teardown code that runs before and after each test function in your file. In this example, the functions open the saved figure and find the handles. After testing, the framework closes the figure.

You must name fresh fixture functions setup and teardown, respectively. Similar to the file fixture functions, these functions take a single input argument, testCase. In this example, these functions create a new field in the TestData structure that includes handles to the figure and to the axes. This allows information to pass between setup, test, and teardown functions.

Create the setup and teardown functions as a local functions to axesPropertiesTest. Open the saved figure for each test to ensure test independence.


% Copyright 2015 The MathWorks, Inc.

function setup(testCase)
testCase.TestData.Figure = openfig(testCase.TestData.figName);
testCase.TestData.Axes = findobj(testCase.TestData.Figure,...
    'Type','Axes');
end

function teardown(testCase)
close(testCase.TestData.Figure)
end

In addition to custom setup and teardown code, the Unit Testing Framework provides some classes for creating fixtures. For more information see matlab.unittest.fixtures.

Create Test Functions

Each test is a local function that follows the naming convention of having ‘test’ at the beginning or end of the function name. The test array does not include local functions that do not follow this convention. Similar to setup and teardown functions, individual test functions must accept a single input argument, testCase. Use this test case object for verifications, assertions, assumptions, and fatal assertions functions.

The testDefaultXLim function test verifies that the x-axis limits are large enough to display the cylinder. The lower limit needs to be less than -10, and the upper limit needs to be greater than 10. These values come from the figure generated in the helper function — a cylinder with a 10 unit radius centered on the origin. This test function opens the figure created and saved in the setupOnce function, queries the axes limit, and verifies the limits are correct. The qualification functions, verifyLessThanOrEqual and verifyGreaterThanOrEqual, takes the test case, the actual value, the expected value, and optional diagnostic information to display in the case of failure as inputs.

Create the testDefaultXLim function as local function to axesPropertiesTest.


% Copyright 2015 The MathWorks, Inc.

function testDefaultXLim(testCase)
xlim = testCase.TestData.Axes.XLim;
verifyLessThanOrEqual(testCase, xlim(1), -10,...
    'Minimum x-limit was not small enough')
verifyGreaterThanOrEqual(testCase, xlim(2), 10,...
    'Maximum x-limit was not big enough')
end

The surfaceColorTest function accesses the figure that you created and saved in the setupOnce function. surfaceColorTest queries the face color of the cylinder and verifies that it is red. The color red has an RGB value of [1 0 0]. The qualification function, verifyEqual, takes as inputs the test case, the actual value, the expected value, and optional diagnostic information to display in the case of failure. Typically when using verifyEqual on floating point-values, you specify a tolerance for the comparison. For more information, see matlab.unittest.constraints.

Create the surfaceColorTest function as local function to axesPropertiesTest.


% Copyright 2015 The MathWorks, Inc.

function surfaceColorTest(testCase)
h = findobj(testCase.TestData.Axes,'Type','surface');
co = h.FaceColor;
verifyEqual(testCase, co, [1 0 0],'FaceColor is incorrect')
end

Now the axesPropertiesTest.m file is complete with a main function, file fixture functions, fresh fixture functions, and two local test functions. You are ready to run the tests.

Run Tests

The next step is to run the tests using the runtests function. In this example, the call to runtests results in the following steps:

  1. The main function creates a test array.
  2. The file fixture records the working folder, creates a temporary folder, sets the temporary folder as the working folder, then generates and saves a figure.
  3. The fresh fixture setup opens the saved figure and finds the handles.
  4. The testDefaultXLim test is run.
  5. The fresh fixture teardown closes the figure.
  6. The fresh fixture setup opens the saved figure and finds the handles.
  7. The surfaceColorTest test is run.
  8. The fresh fixture teardown closes the figure.
  9. The file fixture teardown deletes the saved figure, changes back to the original path and deletes the temporary folder.

At the command prompt, generate and run the test suite.

results = runtests('axesPropertiesTest.m')
Running axesPropertiesTest
..
Done axesPropertiesTest
__________


results = 

  1x2 TestResult array with properties:

    Name
    Passed
    Failed
    Incomplete
    Duration
    Details

Totals:
   2 Passed, 0 Failed, 0 Incomplete.
   3.5192 seconds testing time.

Create Table of Test Results

To access functionality available to tables, create one from the TestResult object.

rt = table(results)
rt =

  2x6 table

                    Name                     Passed    Failed    Incomplete    Duration      Details   
    _____________________________________    ______    ______    __________    ________    ____________

    'axesPropertiesTest/testDefaultXLim'     true      false     false         2.4919      [1x1 struct]
    'axesPropertiesTest/surfaceColorTest'    true      false     false         1.0273      [1x1 struct]

Export test results to an Excel® spreadsheet.

writetable(rt,'myTestResults.xls')

Sort the test results by increasing duration.

sortrows(rt,'Duration')
ans =

  2x6 table

                    Name                     Passed    Failed    Incomplete    Duration      Details   
    _____________________________________    ______    ______    __________    ________    ____________

    'axesPropertiesTest/surfaceColorTest'    true      false     false         1.0273      [1x1 struct]
    'axesPropertiesTest/testDefaultXLim'     true      false     false         2.4919      [1x1 struct]