press

Class: matlab.uitest.TestCase
Namespace: matlab.uitest

Perform press gesture on UI component

Syntax

press(testCase,comp)

press(testCase,comp,location)

press(___,SelectionType=type)

press(testCase,spn,direction)

press(testCase,uit,RowHeader=index)

press(testCase,uit,ColumnHeader=index)

press(testCase,uit,ColumnToSort=index)

Description

Components

press(testCase,comp) performs a press gesture on the UI component comp.

press(testCase,comp,location) specifies the location to press within the component. You can specify a location with only five of the available components: axes, UI axes, polar axes, panel, and UI figure. If you do not specify the location, MATLAB^® presses at the center of comp.

press(___,SelectionType=type) uses the specified mouse selection type to perform a press gesture on the component. You can specify a selection type with only three of the available components: axes, UI axes, and UI figure. Specify the selection type in addition to any of the input argument combinations in previous syntaxes. For example, press(testCase,fig,SelectionType="alt") tests a right-click at the center of the specified UI figure.

Spinners

press(testCase,spn,direction) specifies whether to press the up or down arrow in the spinner spn.

Table Headers

Since R2026a

press(testCase,uit,RowHeader=index) performs a press gesture on the specified row header of the table UI component uit.

press(testCase,uit,ColumnHeader=index) performs a press gesture on the specified table column header.

press(testCase,uit,ColumnToSort=index) performs a press gesture to sort the data in the specified table column.

Input Arguments

testCase — Test case

matlab.uitest.TestCase object

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

comp — Component to press

UI component object

Component to press during the test, specified as a UI component object that supports a press gesture. This table shows the components that support press gestures.

Supported Component	Typical Creation Function
Axes	axes
Button	uibutton
Check box	uicheckbox
Hyperlink	uihyperlink
Image	uiimage
Menu	uimenu
Panel	uipanel
Polar axes	polaraxes
Push tool	uipushtool
Radio button	uiradiobutton
State button	uibutton
Switch (rocker, slider, toggle)	uiswitch
Toggle button	uitogglebutton
Toggle tool	uitoggletool
UI axes	uiaxes
UI figure	uifigure

location — Location to press

1-by-2 or 1-by-3 numeric array

Location to press, specified as the coordinates of the point:

• Axes and UI axes — A 1-by-2 or 1-by-3 numeric array containing x-, y-, and optionally z-coordinates.

• Polar axes — A 1-by-2 numeric array containing θ- and r-coordinates.

• Panel — A 1-by-2 numeric array containing x- and y-coordinates. Specify the coordinates of the point measured in pixels from the lower-left corner of the component.

• UI figure — A 1-by-2 numeric array containing x- and y-coordinates. Specify the coordinates of the point from the lower-left corner of the component.

Example: [32.5 13 0.25] (UI axes)

Example: [pi/2 0.5] (Polar axes)

Example: [100 200] (UI figure)

type — Mouse selection type

"normal" (default) | "extend" | "alt" | "open"

Mouse selection type when clicking on an axes, UI axes, or UI figure, specified as one of the values in the following table. This argument provides information about how the mouse button is pressed in the component.

Value	Corresponding Action
"normal"	Click with the left mouse button.
"extend"	Shift+click with the left mouse button.
"alt"	Click with the right mouse button.
"open"	Double-click with any mouse button.

Data Types: string | char

spn — Spinner component to press

Spinner object

Spinner component to press during the test, specified as a Spinner object. Spinner components are typically created using the uispinner function.

direction — Direction of change for spinner

"up" | "down"

Direction of change for the spinner, specified as "up" or "down". To increment the value of the spinner, specify "up". To decrement the value, specify "down".

Data Types: string | char

uit — Table UI component

Table object

Since R2026a

Table UI component, specified as a Table object. Table UI components are created using the uitable function.

index — Index of table row or column

positive integer scalar

Since R2026a

Index of a table row or column, specified as a positive integer scalar.

• If you specify RowHeader=index, the method simulates a user clicking the specified row header, resulting in the selection of the entire row.

• If you specify ColumnHeader=index, the method simulates a user clicking the specified column header, resulting in the selection of the entire column.

• If you specify ColumnToSort=index, the method simulates a user clicking the sorting affordance in the header of the specified column, resulting in that column being sorted. To sort a column, the ColumnSortable property of that column must be true. If a column is sortable, arrows appear in its header when you hover your mouse over it.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Attributes

Sealed

true

To learn about attributes of methods, see Method Attributes.

Examples

Press Switch

Create a slider switch.

s = uiswitch("slider");

Create an interactive test case and press the switch. A blue dot representing the programmatic press gesture appears and then disappears at the center of the switch. The switch moves from Off to On.

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

Press Axes Location

Create UI axes and an interactive test case.

ax = uiaxes;
testCase = matlab.uitest.TestCase.forInteractiveUse;

Press the center of the axes. A blue dot representing the programmatic press gesture appears and then disappears at the center of the axes.

testCase.press(ax)

Press the axes at the coordinates (0.85, 0.2). A blue dot representing the programmatic press gesture appears and then disappears at the specified axes coordinates.

testCase.press(ax,[0.85 0.2])

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.

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

Verification passed.

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

testCase.press(b)
testCase.verifyTrue(b.Value)

Verification passed.

Modify Value of Spinner and Verify Change

Create a spinner with an initial value of 42.

s = uispinner(Value=42);
initVal = s.Value;

Create an interactive test case and increment the spinner. Verify that the new value of the spinner is the initial value plus the spinner step value.

testCase = matlab.uitest.TestCase.forInteractiveUse;
testCase.press(s,"up")
testCase.verifyEqual(s.Value,initVal+s.Step)

Verification passed.

Decrement the value of the spinner and verify that the value of the spinner is equal to the initial value again.

testCase.press(s,"down")
testCase.verifyEqual(s.Value,initVal)

Verification passed.

Press UI Figure with Specified Selection Type

Create a UI figure and an interactive test case.

fig = uifigure;
testCase = matlab.uitest.TestCase.forInteractiveUse;

Test a right-click at the center of the UI figure. A blue dot representing the programmatic press gesture appears and then disappears at the center of the figure.

testCase.press(fig,SelectionType="alt")

Test a double-click on the UI figure at the coordinates (100, 200). A blue dot representing the programmatic press gesture appears and then disappears at the specified location.

testCase.press(fig,[100 200],SelectionType="open")

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)[phone]]);

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

testCase = matlab.uitest.TestCase.forInteractiveUse;
testCase.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.

testCase.press(b)
testCase.verifyTrue(b.Value)

Verification passed.

Press Table Headers

Since R2026a

Create a table UI component with sortable columns.

fig = uifigure;
uit = uitable(fig,Data=magic(5),ColumnSortable=true);

Create a test case for interactive testing.

testCase = matlab.uitest.TestCase.forInteractiveUse;

Select the third row of the table. A blue dot representing the programmatic press gesture appears and then disappears at the center of the specified row header.

testCase.press(uit,RowHeader=3)

Now select the first column of the table.

testCase.press(uit,ColumnHeader=1)

Sort the table by the values in the second column. Then, verify that the displayed data in the specified column is sorted.

testCase.press(uit,ColumnToSort=2)
testCase.verifyTrue(issorted(uit.DisplayData(:,2),"monotonic"))

Verification passed.

Version History

Introduced in R2018a

R2026a: Perform gestures on table row and column headers

You can perform press gestures in tests on table row and column headers.

R2024b: Specify location of gesture on figures that use nonpixel units

You can specify the location of the gesture on a UI figure that uses any unit of measurement. In previous releases, the method lets you specify coordinates only for figures whose Units property is set to "pixels".

R2024b: Specifying location of gesture on axes or UI axes with active right y-axis is not supported

Specifying the location of the gesture on axes or UI axes with an active right y-axis is no longer supported. If your chart has two y-axes, activate the side associated with the left y-axis before performing the gesture. In previous releases, when you specify the location on axes or UI axes with an active right side, the app testing framework interprets that location with respect to the left y-axis, which can cause the gesture to occur at an unexpected location or fail.

R2024a: Perform gestures on hyperlinks

You can perform press gestures in tests on hyperlinks.

R2021b: Specify the mouse selection type in gestures on axes and UI axes

You can specify the mouse selection type in press gestures that are performed in tests on axes and UI axes. The compst argument now also supports objects of type Axes and UIAxes, and can be used in combination with the type input argument to specify the mouse selection type.

R2021a: Perform gestures on panels

You can perform press gestures in tests on panels.

R2020b: Perform gestures on push tools and toggle tools

You can perform press gestures in tests on push tools and toggle tools.

R2020a: Specify the mouse selection type in gestures on UI figures

You can specify the mouse selection type in press gestures that are performed in tests on UI figures. To specify the mouse selection type, use the type input argument.

R2019b: Perform gestures on polar axes and images

You can perform press gestures in tests on polar axes and images.

R2019a: Perform gestures on axes and UI figures

You can perform press gestures in tests on axes and UI figures.