Skip to content

Latest commit

 

History

History
352 lines (276 loc) · 11.5 KB

android-mobile-gestures.md

File metadata and controls

352 lines (276 loc) · 11.5 KB
Raw

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.

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.

Usage examples

// Java
((JavascriptExecutor) driver).executeScript("mobile: longClickGesture", ImmutableMap.of(
    "elementId", ((RemoteWebElement) element).getId()
));
# Python
driver.execute_script('mobile: longClickGesture', {'x': 100, 'y': 100, 'duration': 1000})

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})

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})
// Javascript - @wdio
await driver.executeScript('mobile: clickGesture', [{x: 100, y: 100}]);

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
));

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
));
// Javascript - @wdio
await driver.executeScript('mobile: flingGesture', [{
    elementId: element.elementId,
    direction: 'right',
    speed: 500,
}]);

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
));

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
})

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
));
# Python
driver.execute_script('mobile: swipeGesture', {
    'left': 100,
    'top': 100,
    'width': 200,
    'height': 200,
    'direction': direction, 'percent': 0.75
})

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", 1.0
));
# Python
can_scroll_more = driver.execute_script('mobile: scrollGesture', {
    'left': 100, 'top': 100, 'width': 200, 'height': 200,
    'direction': 'down',
    'percent': 3.0
})