appium_gesture
Perform a touch gesture. Use 'action' to choose: tap, double_tap, long_press, scroll, swipe, pinch_zoom, scroll_to_element, back.
Instructions
Perform a touch gesture. Use 'action' to choose: tap, double_tap, long_press, scroll, swipe, pinch_zoom, scroll_to_element, back. Choose scroll vs swipe by intent: scroll to browse content in a list or feed; swipe to dismiss, switch screens, navigate carousels, or pull-to-refresh (speed=fast). For drag-and-drop use appium_drag_and_drop. For custom multi-touch use appium_perform_actions.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | X pixel coordinate, paired with y: tap location, pinch center, or scroll/swipe start (requires endX/endY). elementUUID overrides x/y for tap/double_tap/long_press/pinch_zoom. | |
| y | No | Y pixel coordinate, paired with x; same action meanings and elementUUID precedence as x. | |
| endX | No | Ending X coordinate in pixels for scroll/swipe; requires x, y, endY. | |
| endY | No | Ending Y coordinate in pixels for scroll/swipe; requires x, y, endX. | |
| scale | No | Required for pinch_zoom. Scale < 1 zooms out (fingers close); scale > 1 zooms in (fingers spread). Examples: 0.5 zooms out; 2.0 zooms in 2x. | |
| speed | No | Swipe only. slow: deliberate drag; normal: default navigation speed; fast: flick without an initial hold. Use fast for pull-to-refresh and other velocity-sensitive interfaces. | |
| action | Yes | Gesture to perform: - tap: tap an element or a coordinate. - double_tap: double-tap, for example to zoom an image or favorite a post. - long_press: press and hold to open a context menu or initiate a drag. For tap/double_tap/long_press, provide elementUUID or both x and y. - scroll: browse a list, feed, or page to reveal content. - swipe: dismiss a card, switch screens or tabs, navigate a carousel, or pull-to-refresh (use speed=fast). For scroll/swipe, provide direction or all four custom coordinates: x, y, endX, endY. - pinch_zoom: zoom in (scale > 1) or out (scale < 1) on maps, images, or other zoomable views. Requires scale. - scroll_to_element: scroll to find a target using strategy and selector. Direction is up/down, default down. Stops when the element is found, page source is unchanged after a scroll (likely end of content), or maxScrollAttempts is reached. Adjust distance with scrollDistance (0.05–1) or scrollDistancePreset (small/medium/large). - back: trigger system back navigation. | |
| duration | No | Duration in milliseconds. long_press defaults to 2000 (range 500–10000); scroll defaults to 800. For swipe, prefer speed unless a custom movement duration is needed. For W3C swipe, overrides movement time; speed still sets the initial hold. Ignored by iOS native mobile: swipe (direction, no elementUUID, speed != fast). | |
| selector | No | Locator selector value. Required for: scroll_to_element. | |
| strategy | No | Required for scroll_to_element. Prefer accessibility id > id > platform-native (iOS: -ios predicate string / -ios class chain; Android: -android uiautomator) > xpath (last resort: slow/brittle). name is legacy; class name may match multiple elements; css selector is webview-only. Same priorities as appium_find_element. | |
| velocity | No | Pinch velocity in scale factor per second. Default 2.2. Used by pinch_zoom. | |
| direction | No | Direction for scroll/swipe. Coordinates are calculated from the screen or element bounds. Provide either direction or custom coordinates (x, y, endX, endY); direction takes precedence if both are given. For scroll_to_element, use up/down; default down. | |
| sessionId | No | Session ID; defaults to the active session. | |
| elementUUID | No | Element UUID for tap, double_tap, long_press, or pinch_zoom; overrides x/y for these actions. For scroll/swipe with direction, coordinates are calculated relative to this element instead of the whole screen. | |
| scrollDistance | No | scroll_to_element only: vertical swipe distance fraction (0.05–1). Ignored when scrollDistancePreset is set. Default 0.45 when neither option is supplied. | |
| maxScrollAttempts | No | scroll_to_element only: maximum scroll attempts after the initial lookup fails. Default 10. | |
| scrollDistancePreset | No | scroll_to_element only: small is a light nudge (0.25), medium is 0.45, large is the full default swipe (1). Overrides scrollDistance when set. |