Automating Mobile Gestures With UiAutomator2 Backend
Touch actions are the most advanced and the most complicated way to
implement any Android gesture. Although, there is a couple of basic
gestures, like swipe, fling or pinch, which are commonly used in Android
applications and for which it makes sense to have shortcuts, where only
high-level options are configurable.
[1] mobile: longClickGesture
This gesture performs long click action on the given element/coordinates.
Available since Appium v1.19
Supported arguments
elementId: The id of the element to be clicked. If the element is missing
then both click offset coordinates must be provided. If both the element
id and offset are provided then the coordinates are parsed as relative
offsets from the top left corner of the element.
x: The x-offset coordinate
y: The y-offset coordinate
duration: Click duration in milliseconds. 500 by default. The value must
not be negative
locator: The map containing strategy and selector items to make it
possible to click dynamic elements.
# Java
((JavascriptExecutor) driver).executeScript("mobile: longClickGesture",
ImmutableMap.of(
"elementId", ((RemoteWebElement) element).getId()
));
# Python
driver.execute_script('mobile: longClickGesture', {'x': 100, 'y': 100,
'duration': 1000})
[2] mobile: doubleClickGesture
This gesture performs double click action on the given
element/coordinates. Available since Appium v1.21
Supported arguments
elementId: The id of the element to be clicked. If the element is missing
then both click offset coordinates must be provided. If both the element
id and offset are provided then the coordinates are parsed as relative
offsets from the top left corner of the element.
x: The x-offset coordinate
y: The y-offset coordinate
locator: The map containing strategy and selector items to make it
possible to click dynamic elements.
Usage examples
# Java
((JavascriptExecutor) driver).executeScript("mobile: doubleClickGesture",
ImmutableMap.of(
"elementId", ((RemoteWebElement) element).getId()
));
# Python
driver.execute_script('mobile: doubleClickGesture', {'x': 100, 'y': 100})
[3]mobile: clickGesture
This gesture performs click action on the given element/coordinates.
Available since Appium UiAutomator2 driver 1.71.0. Usage of this gesture
is recommended as a possible workaround for cases where the "native" tap
call fails, even though tap coordinates seem correct. This issue is
related to the fact these calls use the legacy UIAutomator-based calls
while this extension is based on the same foundation as W3C does.
Supported arguments
elementId: The id of the element to be clicked. If the element is missing
then both click offset coordinates must be provided. If both the element
id and offset are provided then the coordinates are parsed as relative
offsets from the top left corner of the element.
x: The x-offset coordinate
y: The y-offset coordinate
locator: The map containing strategy and selector items to make it
possible to click dynamic elements.
Usage examples
# Java
driver.executeScript("mobile: clickGesture", ImmutableMap.of(
"elementId", ((RemoteWebElement) element).getId()
));
# Python
driver.execute_script('mobile: clickGesture', {'x': 100, 'y': 100})
[4]mobile: dragGesture
This gesture performs drag action from the given element/coordinates to
the given point. Available since Appium v1.19
Supported arguments
elementId: The id of the element to be dragged. If the element id is
missing then both start coordinates must be provided. If both the element
id and the start coordinates are provided then these coordinates are
considered as offsets from the top left element corner.
startX: The x-start coordinate
startY: The y-start coordinate
endX: The x-end coordinate. Mandatory argument
endY: The y-end coordinate. Mandatory argument
speed: The speed at which to perform this gesture in pixels per second.
The value must not be negative. The default value is 2500 *
displayDensity
Usage examples
# Java
((JavascriptExecutor) driver).executeScript("mobile: dragGesture",
ImmutableMap.of(
"elementId", ((RemoteWebElement) element).getId(),
"endX", 100,
"endY", 100
));
[5]mobile: flingGesture
This gesture performs fling gesture on the given element/area. Available
since Appium v1.19
Supported arguments
elementId: The id of the element to be flinged. If the element id is
missing then fling bounding area must be provided. If both the element id
and the fling bounding area are provided then this area is effectively
ignored.
left: The left coordinate of the fling bounding area
top: The top coordinate of the fling bounding area
width: The width of the fling bounding area
height: The height of the fling bounding area
direction: Direction of the fling. Mandatory value. Acceptable values
are: up, down, left and right (case insensitive)
speed: The speed at which to perform this gesture in pixels per second.
The value must be greater than the minimum fling velocity for the given
view (50 by default). The default value is 7500 * displayDensity
Returned value
The returned value is a boolean one and equals to true if the object can
still scroll in the given direction
Usage examples
# Java
boolean canScrollMore = (Boolean) ((JavascriptExecutor)
driver).executeScript("mobile: flingGesture", ImmutableMap.of(
"elementId", ((RemoteWebElement) element).getId(),
"direction", "down",
"speed", 500
));
[6]mobile: pinchOpenGesture
This gesture performs pinch-open gesture on the given element/area.
Available since Appium v1.19
Supported arguments
elementId: The id of the element to be pinched. If the element id is
missing then pinch bounding area must be provided. If both the element id
and the pinch bounding area are provided then the area is effectively
ignored.
left: The left coordinate of the pinch bounding area
top: The top coordinate of the pinch bounding area
width: The width of the pinch bounding area
height: The height of the pinch bounding area
percent: The size of the pinch as a percentage of the pinch area size.
Valid values must be float numbers in range 0..1, where 1.0 is 100%.
Mandatory value.
speed: The speed at which to perform this gesture in pixels per second.
The value must not be negative. The default value is 2500 *
displayDensity
Usage examples
# Java
((JavascriptExecutor) driver).executeScript("mobile: pinchOpenGesture",
ImmutableMap.of(
"elementId", ((RemoteWebElement) element).getId(),
"percent", 0.75
));
[7]mobile: pinchCloseGesture
This gesture performs pinch-close gesture on the given element/area.
Available since Appium v1.19
Supported arguments
elementId: The id of the element to be pinched. If the element id is
missing then pinch bounding area must be provided. If both the element id
and the pinch bounding area are provided then the area is effectively
ignored.
left: The left coordinate of the pinch bounding area
top: The top coordinate of the pinch bounding area
width: The width of the pinch bounding area
height: The height of the pinch bounding area
percent: The size of the pinch as a percentage of the pinch area size.
Valid values must be float numbers in range 0..1, where 1.0 is 100%.
Mandatory value.
speed: The speed at which to perform this gesture in pixels per second.
The value must not be negative. The default value is 2500 *
displayDensity
Usage examples
# Java
((JavascriptExecutor) driver).executeScript("mobile: pinchCloseGesture",
ImmutableMap.of(
"elementId", ((RemoteWebElement) element).getId(),
"percent", 0.75
));
# Python
can_scroll_more = driver.execute_script('mobile: pinchCloseGesture', {
'elementId': element.id,
'percent': 0.75
})
[8]mobile: swipeGesture
This gesture performs swipe gesture on the given element/area. Available
since Appium v1.19
Supported arguments
elementId: The id of the element to be swiped. If the element id is
missing then swipe bounding area must be provided. If both the element id
and the swipe bounding area are provided then the area is effectively
ignored.
left: The left coordinate of the swipe bounding area
top: The top coordinate of the swipe bounding area
width: The width of the swipe bounding area
height: The height of the swipe bounding area
direction: Swipe direction. Mandatory value. Acceptable values are: up,
down, left and right (case insensitive)
percent: The size of the swipe as a percentage of the swipe area size.
Valid values must be float numbers in range 0..1, where 1.0 is 100%.
Mandatory value.
speed: The speed at which to perform this gesture in pixels per second.
The value must not be negative. The default value is 5000 *
displayDensity
Usage examples
# Java
((JavascriptExecutor) driver).executeScript("mobile: swipeGesture",
ImmutableMap.of(
"left", 100, "top", 100, "width", 200, "height", 200,
"direction", "left",
"percent", 0.75
));
[9]mobile: scrollGesture
This gesture performs scroll gesture on the given element/area. Available
since Appium v1.19
Supported arguments
elementId: The id of the element to be scrolled. If the element id is
missing then scroll bounding area must be provided. If both the element
id and the scroll bounding area are provided then this area is
effectively ignored.
left: The left coordinate of the scroll bounding area
top: The top coordinate of the scroll bounding area
width: The width of the scroll bounding area
height: The height of the scroll bounding area
direction: Scrolling direction. Mandatory value. Acceptable values are:
up, down, left and right (case insensitive)
percent: The size of the scroll as a percentage of the scrolling area
size. Valid values must be float numbers greater than zero, where 1.0 is
100%. Mandatory value.
speed: The speed at which to perform this gesture in pixels per second.
The value must not be negative. The default value is 5000 *
displayDensity
Returned value
The returned value is a boolean one and equals to true if the object can
still scroll in the given direction
Usage examples
# Java
boolean canScrollMore = (Boolean) ((JavascriptExecutor)
driver).executeScript("mobile: scrollGesture", ImmutableMap.of(
"left", 100, "top", 100, "width", 200, "height", 200,
"direction", "down",
"percent", 3.0
));
# Python
can_scroll_more = driver.execute_script('mobile: scrollGesture', {
'left': 100, 'top': 100, 'width': 200, 'height': 200,
'direction': 'down',
'percent': 3.0
})
