matlab.uitest.TestCase Class

Namespace: matlab.uitest
Superclasses: matlab.unittest.TestCase

Class for writing tests with app testing framework

Description

The matlab.uitest.TestCase class lets you write tests that use the app testing framework. Because the matlab.uitest.TestCase class derives from the matlab.unittest.TestCase class, your tests have access to the features of the unit testing framework, such as qualifications, fixtures, and plugins. For more information about app testing, see Overview of App Testing Framework.

The matlab.uitest.TestCase class is a handle class.

Class Attributes

Abstract true

For information on class attributes, see Class Attributes.

Creation

In most cases, you are not required to create an instance of the matlab.uitest.TestCase class directly. The app testing framework automatically creates matlab.uitest.TestCase instances when running the tests.

To create a matlab.uitest.TestCase instance for interactive, command-line testing, use the forInteractiveUse static method.

Methods

expand all

Public Methods

In addition to these methods, the matlab.uitest.TestCase class inherits methods from the matlab.unittest.TestCase class and its superclasses.

`choose`	Perform choose gesture on UI component
`chooseContextMenu`	Perform choose gesture on context menu item
`chooseDialog`	Select option in frontmost dialog box in figure window
`dismissDialog`	Dismiss frontmost dialog box in figure window
`drag`	Perform drag gesture on UI component
`matlab.uitest.TestCase.forInteractiveUse`	Create test case for interactive use
`hover`	Perform hover gesture on UI component
`press`	Perform press gesture on UI component
`scroll`	Perform scroll gesture on UI component
`type`	Type in UI component

Examples

collapse all

Choose Value on Discrete Knob

Create a discrete knob.

knob = uiknob('discrete');

A figure with a discrete knob. The knob value is 'Off'.

Create an interactive test case and choose the 'High' knob value. An animated blue dot performs the programmatic choose gesture.

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.choose(knob,'High')

A figure with a discrete knob. The knob value is 'High'.

View the value of the Items property on the knob.

knob.Items

ans =

  1×4 cell array

    {'Off'}    {'Low'}    {'Medium'}    {'High'}

Choose the 'Low' knob value by index. The knob moves from 'High' to 'Low'.

tc.choose(knob,2)

A figure with a discrete knob. The knob value is 'Low'.

Press Button and Verify Value Change

Create a state button.

b = uibutton('state');

Create an interactive test case and verify that the value of the state button is false.

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.verifyFalse(b.Value)

Verification passed.

Press the button and verify the state changes to true. A blue dot representing the programmatic push gesture appears and then disappears on the button.

tc.press(b)
tc.verifyTrue(b.Value)

Verification passed.

Drag Slider and Verify Stop Value

Create a slider with a minimum value of -237, a maximum value of 237, and a starting value of 7.

slider = uislider("Limits",[-237 237],"Value",7);

Create an interactive test case and verify the initial value of the slider.

testCase = matlab.uitest.TestCase.forInteractiveUse;
testCase.verifyEqual(slider.Value,7)

Verification passed.

Drag the slider between two values and verify the final value. Since the framework mimics a user manipulating the component to an arbitrarily precisioned value, it is a best practice to use a tolerance to compare the actual and expected slider values.

val = 26.75;
testCase.drag(slider,-val,val)
testCase.verifyEqual(slider.Value,val,"AbsTol",0.1)

Verification passed.

Automatically Scroll to Component

Since R2023b

Perform a gesture on a component that is not in the viewable area of a figure by automatically scrolling to the component.

Create a scrollable figure with a state button that is outside the viewable area of the figure.

fig = uifigure("Scrollable","on");
b = uibutton(fig,"state","Position",[fig.Position(3)+100 100 100 22]);

Create a test case for interactive testing, and verify the initial state of the button.

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.verifyFalse(b.Value)

Verification passed.

Press the button and verify that its state changes. Because the figure is scrollable, the app testing framework automatically scrolls to the button before performing the gesture.

tc.press(b)
tc.verifyTrue(b.Value)

Verification passed.

Version History

Introduced in R2018a

expand all

R2024b: Programmatically interact with alert and confirmation dialog boxes

The matlab.uitest.TestCase class has two new methods named chooseDialog and dismissDialog that enable you to programmatically interact with a modal dialog box in front of a figure window.

R2024a: Perform scroll gestures on axes and UI axes

The matlab.uitest.TestCase class has a new method scroll that lets you test scroll gestures on axes and UI axes.

R2023b: Automatically scroll to components outside viewable area

To perform a gesture on a UI component that is not in the viewable area of an app, the app testing framework automatically scrolls to the specified component before performing the gesture. For the framework to bring the component into view, the component must be supported by the scroll function and all its ancestors must have their Scrollable property set to "on" or true.

R2021b: Use any unit of measurement in gestures at the center of components

When you perform a gesture at the center of a component, the component or its parent containers can use any unit of measurement. In previous releases, the app testing framework does not support containers that use nonpixel units.

For example, create a figure with its Units property set to "normalized". Then, create a panel in the figure and programmatically press at the center of the panel.

fig = uifigure("Units","normalized");
p = uipanel(fig);

testCase = matlab.uitest.TestCase.forInteractiveUse;
testCase.press(p)

If you perform a gesture at the center of a component using a syntax that accepts location as an input (for instance, press(testCase,comp,location)), then the figure or parent containers can use only "pixels" as their unit of measurement.

R2021a: Close alert dialog box in front of figure window

The matlab.uitest.TestCase class has a new method dismissAlertDialog that programmatically closes an alert dialog box in front of a figure window.

R2020b: Perform choose gestures on context menu items

The matlab.uitest.TestCase class has a new method chooseContextMenu that lets you test choose gestures on context menu items for UI components.

R2019a: Perform hover gestures on axes, UI axes, and UI figures

The matlab.uitest.TestCase class has a new method hover that lets you test hover gestures on axes, UI axes, and UI figures.