Overview of App Testing Framework

Use the MATLAB^® app testing framework to test App Designer apps, or apps built programmatically using the uifigure function. The app testing framework lets you author a test class that programmatically performs a gesture on a UI component, such as pressing a button or dragging a slider, and verifies the behavior of the app.

App Testing

Test Creation – Class-based tests can use the app testing framework by subclassing matlab.uitest.TestCase. Because matlab.uitest.TestCase is a subclass of matlab.unittest.TestCase, your test has access to the features of the unit testing framework, such as qualifications, fixtures, and plugins. To experiment with the app testing framework at the command prompt, create a test case instance using matlab.uitest.TestCase.forInteractiveUse.

Test Content – Typically, a test of an app programmatically interacts with app components using a gesture method of matlab.uitest.TestCase, such as press or type, and then performs a qualification on the result. For example, a test might press one check box and verify that the other check boxes are disabled. Or it might type a number into a text box and verify the app correctly computes a result. These types of tests require understanding of the properties of the app being tested. To verify a button press, you must know where in the app object MATLAB stores the status of a button. To verify the result of a computation, you must know how to access the result within the app.

Test Clean Up – It is a best practice to include a teardown action to delete the app after the test. Typically, the test method adds this action using the addTeardown method of matlab.unittest.TestCase.

App Locking – When an app test creates a figure, the framework locks the figure immediately to prevent external interactions with the components. The app testing framework does not lock UI components if you create an instance of matlab.uitest.TestCase.forInteractiveUse for experimentation at the command prompt.

To unlock a figure for debugging purposes, use the matlab.uitest.unlock function.

Gesture Support of UI Components

The gesture methods of matlab.uitest.TestCase support various UI components.

Component	Typical Creation Function	`matlab.uitest.TestCase` Gesture Method
Component	Typical Creation Function	`press`	`choose`	`drag`	`type`	`hover`	`chooseContextMenu`
Axes	`axes`	✔		✔		✔	✔
Button	`uibutton`	✔					✔
Button Group	`uibuttongroup`		✔
Check Box	`uicheckbox`	✔	✔				✔
Date Picker	`uidatepicker`				✔		✔
Discrete Knob	`uiknob`		✔				✔
Drop Down	`uidropdown`		✔		✔		✔
Edit Field (Numeric, Text)	`uieditfield`				✔		✔
Image	`uiimage`	✔					✔
Knob	`uiknob`		✔	✔			✔
List Box	`uilistbox`		✔				✔
Menu	`uimenu`	✔
Polar Axes	`polaraxes`	✔				✔	✔
Push Tool	`uipushtool`	✔
Radio Button	`uiradiobutton`	✔	✔				✔
Slider	`uislider`		✔	✔			✔
Spinner	`uispinner`	✔			✔		✔
State Button	`uibutton`	✔	✔				✔
Switch (Rocker, Slider, Toggle)	`uiswitch`	✔	✔				✔
Tab	`uitab`		✔
Tab Group	`uitabgroup`		✔
Text Area	`uitextarea`				✔		✔
Toggle Button	`uitogglebutton`	✔	✔				✔
Toggle Tool	`uitoggletool`	✔	✔
Tree Node	`uitreenode`		✔
UI Axes	`uiaxes`	✔		✔		✔	✔
UI Figure	`uifigure`	✔				✔	✔

Write a Test for an App

This example shows how to write a test for an app that provides options to change the sample size and colormap of a plot. To programmatically interact with the app and qualify the results, use the app testing framework combined with the unit testing framework.

At the command prompt, make the app accessible by adding the folder that includes the app to the MATLAB search path.

addpath(fullfile(matlabroot,'examples','matlab','main'))

To explore the properties of the app prior to testing, create an instance of the app at the command prompt.

app = ConfigurePlotAppExample;

This step is not necessary for the tests, but it is helpful to explore the properties used by the app tests. For example, use app.UpdatePlotButton to access the Update Plot button within the app object.

Create a test class that inherits from matlab.uitest.TestCase.

classdef testConfigurePlotAppExample < matlab.uitest.TestCase
    
    methods (Test)

    end
    
end

Create a test method test_SampleSize to test the sample size. The test method modifies the sample size, updates the plot, and verifies that the surface uses the specified sample size. The call to addTeardown deletes the app after the test is complete.

classdef testConfigurePlotAppExample < matlab.uitest.TestCase
    
    methods (Test)
        function test_SampleSize(testCase)
            app = ConfigurePlotAppExample;
            testCase.addTeardown(@delete,app);
            
            testCase.type(app.SampleSizeEditField,12);
            testCase.press(app.UpdatePlotButton);
            
            ax = app.UIAxes;
            surfaceObj = ax.Children;
            testCase.verifySize(surfaceObj.ZData,[12 12]);
        end
    end
    
end

Create a second test method test_Colormap to test the colormap. The test method selects a colormap, updates the plot, and verifies that the plot uses the specified colormap. The full code is now as follows.

classdef testConfigurePlotAppExample < matlab.uitest.TestCase
    
    methods (Test)
        function test_SampleSize(testCase)
            app = ConfigurePlotAppExample;
            testCase.addTeardown(@delete,app);
            
            testCase.type(app.SampleSizeEditField,12);
            testCase.press(app.UpdatePlotButton);
            
            ax = app.UIAxes;
            surfaceObj = ax.Children;
            testCase.verifySize(surfaceObj.ZData,[12 12]);
        end
        
        function test_Colormap(testCase)
            app = ConfigurePlotAppExample;
            testCase.addTeardown(@delete,app);
            
            testCase.choose(app.ColormapDropDown,'Winter');
            testCase.press(app.UpdatePlotButton);
            
            expectedMap = winter;
            ax = app.UIAxes;
            testCase.verifyEqual(ax.Colormap,expectedMap);
        end
    end
    
end

At the command prompt, run the tests.

results = runtests('testConfigurePlotAppExample')

Running testConfigurePlotAppExample
..
Done testConfigurePlotAppExample
__________


results = 

  1×2 TestResult array with properties:

    Name
    Passed
    Failed
    Incomplete
    Duration
    Details

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

Documentation