Automating Mobile Gestures For iOS With WebDriverAgent/XCTest Backend

Unfortunately Apple's XCTest framework does not natively support W3C standards for TouchAction interface implementation. Although, it provides rich set of gestures, inluding these, that are unique for iOS platform. It is possible to directly invoke these gestures in Appium starting from version 1.6.4-beta.

It is important to rememeber that XCTest and WDA are being constantly changed. This means all "mobile: *" commands can be also subject of change in Appium without any preliminary notice.

mobile: swipe

This gesture performs a simple "swipe" gesture on the particular screen element or on the application element, which is usually the whole screen. This method does not accept coordnates and siply emulates single swipe with one finger. It might be useful for such cases like album pagination, switching views, etc. More advanced cases may require to call "mobile: dragFromToForDuration", where one can supply coordinates and duration.

Supported arguments

Usage examples

// Java
JavascriptExecutor js = (JavascriptExecutor) driver;
Map<String, Object> params = new HashMap<>();
params.put("direction", "down");
params.put("element", ((RemoteWebElement) element).getId());
js.executeScript("mobile: swipe", params);

mobile: scroll

Scrolls the element or the whole screen. Different scrolling strategies are supported. Arguments define the choosen strategy: either 'name', 'direction', 'predicateString' or 'toVisible' in that order. All strategies are exclusive and only one strategy can be applied at a single moment of time. Use "mobile: scroll" to emulate precise scrolling in tables or collection views, where it is already known to which element the scrolling should be performed. Although, there is one known limitation there: in case it is necessary to perform too many scroll gestures on parent container to reach the necessary child element (tens of them) then the method call may fail.

Supported arguments

Usage examples

# Python
driver.execute_script('mobile: scroll', {'direction': 'down'});

mobile: pinch

Performs pinch gesture on the given element or on the application element.

Supported arguments

Usage examples

# Ruby
execute_script 'mobile: pinch', scale: 0.5, velocity: 1.1, element: element.ref

mobile: doubleTap

Performs double tap gesture on the given element or on the screen.

Supported arguments

Usage examples

// javascript
driver.execute('mobile: doubleTap', {element: element.value.ELEMENT});

mobile: touchAndHold

Performs long press gesture on the given element or on the screen.

Supported arguments

Usage examples

// c#
Dictionary<string, object> tfLongTap = new Dictionary<string, object>();
tfLongTap.Add("element", element.Id);
tfLongTap.Add("duration", 2.0);
((IJavaScriptExecutor)driver).ExecuteScript("mobile: touchAndHold", tfLongTap);

mobile: twoFingerTap

Performs two finger tap gesture on the given element or on the application element.

Supported arguments

Usage examples

// c#
Dictionary<string, object> tfTap = new Dictionary<string, object>();
tfTap.Add("element", element.Id);
((IJavaScriptExecutor)driver).ExecuteScript("mobile: twoFingerTap", tfTap);

mobile: tap

Performs tap gesture by coordinates on the given element or on the screen.

Supported arguments

Usage examples

// PHP
$params = array(array('x' => 100.0, 'y' => 50.0, 'element' => element.GetAttribute("id")));
$driver->executeScript("mobile: tap", $params);

mobile: dragFromToForDuration

Performs drag and drop gesture by coordinates. This can be done either on an element or on the screen

Supported arguments

Usage examples

// Java
JavascriptExecutor js = (JavascriptExecutor) driver;
Map<String, Object> params = new HashMap<>();
params.put("duration", 1.0);
params.put("fromX", 100);
params.put("fromY", 100);
params.put("toX", 200);
params.put("toY", 200);
params.put("element", ((RemoteWebElement) element).getId());
js.executeScript("mobile: dragFromToForDuration", params);

mobile: selectPickerWheelValue

Performs selection of the next or previous picker wheel value. This might be useful if these values are populated dynamically, so you don't know which one to select or value selection does not work because of XCTest bug.

Supported arguments

Usage examples

// Java
JavascriptExecutor js = (JavascriptExecutor) driver;
Map<String, Object> params = new HashMap<>();
params.put("order", "next");
params.put("offset", 0.15);
params.put("element", ((RemoteWebElement) element).getId());
js.executeScript("mobile: selectPickerWheelValue", params);

mobile: alert

Performs operations on NSAlert instance.

Supported arguments

Usage examples

# Python
driver.execute_script('mobile: alert', {'action': 'accept', 'buttonLabel': 'My Cool Alert Button'});

Advanced Topics

Check WDA Element Commands API to get the information about the gestures implemented in Facebook WebDriverAgent. Check Apple XCTest documentation on XCUIElement and XCUICoordinate methods list to get the information about all gestures available there.