Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 37 ยท Locators and Gestures

Scroll, Swipe and Long Press with Mobile Commands

Use the UiAutomator2 and XCUITest mobile: gesture commands for scrolling, swiping, long press, drag and pinch, and build a scroll-until-visible helper with a safe limit.

Raw W3C actions give you full control, but for everyday gestures each driver also offers ready-made mobile: commands. They run inside the platform's own gesture engine, take percentages instead of pixel paths and are usually more reliable than hand-built sequences. This lesson shows the main ones for Android and iOS, and a helper pattern for scrolling until an element appears.

These commands are sent with execute_script. They need a real driver and device, so code against a device is read-only here; the helpers are stand-ins that you can run.

Android: UiAutomator2 gestures

The UiAutomator2 driver provides these commands. Arguments are given as a dictionary:

Python
# Click or tap
driver.execute_script("mobile: clickGesture", {"elementId": el.id})
driver.execute_script("mobile: clickGesture", {"x": 540, "y": 1200})
driver.execute_script("mobile: doubleClickGesture", {"elementId": el.id})

# Long press for 1.5 seconds
driver.execute_script("mobile: longClickGesture", {"elementId": el.id, "duration": 1500})

# Swipe inside an area (direction: up, down, left, right; percent of the area to swipe)
driver.execute_script("mobile: swipeGesture", {
    "left": 100, "top": 400, "width": 800, "height": 1200,
    "direction": "up", "percent": 0.75,
})

# Scroll: returns True if more content remains to scroll
more = driver.execute_script("mobile: scrollGesture", {
    "left": 100, "top": 400, "width": 800, "height": 1200,
    "direction": "down", "percent": 1.0,
})

# Drag and pinch
driver.execute_script("mobile: dragGesture", {"elementId": el.id, "endX": 800, "endY": 1500})
driver.execute_script("mobile: pinchOpenGesture", {"elementId": el.id, "percent": 0.75})
driver.execute_script("mobile: pinchCloseGesture", {"elementId": el.id, "percent": 0.75})
driver.execute_script("mobile: flingGesture", {"elementId": el.id, "direction": "down", "speed": 2500})

Notes:

  • Specify either an element (elementId) or an area (left, top, width, height), not both.
  • swipeGesture moves content in the stated finger direction: "up" moves your finger upward, which reveals content below.
  • scrollGesture takes a content direction: "down" scrolls to reveal content lower on the page. Because the two commands use different meanings, always check their documentation and try them once.
  • scrollGesture returns whether the scroll could still move, so it works as the loop condition when scrolling to the end of a list.

iOS: XCUITest gestures

The XCUITest driver has its own commands:

Python
driver.execute_script("mobile: tap", {"x": 200, "y": 400})
driver.execute_script("mobile: doubleTap", {"elementId": el.id})
driver.execute_script("mobile: touchAndHold", {"elementId": el.id, "duration": 1.5})  # seconds
driver.execute_script("mobile: swipe", {"elementId": el.id, "direction": "up"})
driver.execute_script("mobile: scroll", {"elementId": table.id, "direction": "down"})
driver.execute_script("mobile: scroll", {"elementId": table.id, "name": "Terms of service"})  # scroll to a named child
driver.execute_script("mobile: pinch", {"elementId": el.id, "scale": 2.0, "velocity": 1.0})
driver.execute_script("mobile: dragFromToForDuration", {
    "duration": 1.0, "fromX": 100, "fromY": 400, "toX": 100, "toY": 900,
})
driver.execute_script("mobile: selectPickerWheelValue", {"elementId": picker.id, "order": "next", "offset": 0.15})

Differences from Android to remember: durations are in seconds for iOS commands that take a duration, while Android uses milliseconds; iOS offers mobile: scroll with a name, predicateString or toVisible argument to scroll until a child shows up; and a picker wheel needs its own command.

Cross-platform helper

Because the commands differ, write one helper that hides the platform:

Python
def long_press(driver, element, seconds=1.0):
    if driver.capabilities["platformName"].lower() == "android":
        driver.execute_script("mobile: longClickGesture", {"elementId": element.id, "duration": int(seconds * 1000)})
    else:
        driver.execute_script("mobile: touchAndHold", {"elementId": element.id, "duration": seconds})

This is the first brick of a page-object framework where tests never see the platform difference.

Scroll until an element is visible

A very common need: the item you want is below the fold. The robust pattern is a bounded loop:

  1. Check if the element is present (with find_elements, which returns a list).
  2. If yes, finish. If no, scroll one page.
  3. Stop after a maximum number of scrolls, or when the scroll reports that the end was reached, and fail with a clear message.

Without the limit the test could loop forever on a missing item.

Build the helper as a stand-in

The stand-in models a long list in a viewport and a scrollGesture-like command that reports whether more content remains. The helper from the pattern above runs against it, so you can test the loop logic, including the "not found" end case.

JS Stand-in: scroll until visible

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Compute the area to swipe

Android swipe commands take an area. Compute it from the screen size and keep a margin from the system gesture edges. The stand-in builds the argument object for both platforms, so you can compare the shapes.

JS Stand-in: build mobile: gesture arguments

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Note how the same intent produces different units: 1500 milliseconds on Android and 1.5 seconds on iOS.

Tips for reliable gestures

  • Prefer element-scoped gestures over screen-wide ones; they cannot wander into other widgets.
  • Wait after a gesture. Scrolling has momentum; wait for the target to be visible rather than assuming it is.
  • Do not swipe to find a button you can locate directly. With UiScrollable on Android or mobile: scroll with name on iOS, the platform does the searching for you.
  • Check device settings. Gesture navigation, display scaling and accessibility font size change what a 25 percent swipe does.
  • Log the gesture arguments in your helper so a failing run can be reproduced.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command sends an Android long press with an element id?

    longClickGesture is the UiAutomator2 command; touchAndHold is its iOS counterpart.
  2. 2. What unit does iOS mobile: touchAndHold use for duration?

    iOS commands take seconds, while Android's longClickGesture takes milliseconds.
  3. 3. Why must a scroll-until-visible loop have a maximum count?

    A bounded loop fails with a clear message when the element does not exist.
  4. 4. What does mobile: scrollGesture return on Android?

    A true result means the scroll moved and more may remain, which makes it a good loop condition.

Summary

  • mobile: commands run native gesture engines and are more reliable than hand-built actions for common gestures.
  • Android uses clickGesture, longClickGesture, swipeGesture, scrollGesture, dragGesture and pinch commands; iOS uses tap, touchAndHold, swipe, scroll, pinch and others.
  • Units differ: milliseconds on Android, seconds on iOS.
  • Scroll with a bounded loop, or use platform scroll-to-element features.
  • Hide platform differences behind small helpers; this prepares the ground for page objects.

Next: back to the Appium track overview