logo logo

Targeting iOS-Specific Gestures With The iOS Gesture Toolkit Addon

iOS Gesture Toolkit Addon

I recently finished up work on a TestProject addon that I’m pretty excited about, which gives you access to certain iOS-specific gestures. What do I mean by “iOS-specific gestures”? Well, with Appium, the standard way to perform gestures is to use the Actions API. This is a nice cross-platform API for specifying arbitrary pointer movements. Sometimes, however, this API does not do exactly what we want on a given platform. The reasons for this are various, but the bottom line is that the Actions API is implemented by the Appium developers on top of whatever low-level commands we have access to for iOS or for Android.

Meanwhile, each of those platforms makes certain common gestures available as their own high-level commands. So, for example, if you use XCUITest driver, you get a method on the XCUIElement class called swipeUp. This takes no parameters and simply performs a “swipe up” action within the element. In a way, this is much less general than Appium’s Actions API, and in the long run much less powerful. But, it is guaranteed to send the appropriate message to the actual UI element. When you develop iOS apps, you handle swipe gestures using UISwipeGestureRecognizer. You don’t teach your app to recognize a series of pixel movements! So, if you’re using XCUIElement’s ‘swipeUp’ method, you’re essentially guaranteeing that any code listening for a swipe up action will know about it.

Because Appium’s developers want Appium’s users to have access to as much functionality as possible, we’ve created aliases for these XCUITest-specific (and therefore iOS-specific) gesture actions, through a series of “mobile:” commands. In Java, calling these commands might look like the following (see Appium Pro #30 for the full usage):

driver.executeScript("mobile: swipe", args);
driver.executeScript("mobile: scroll", args);
driver.executeScript("mobile: pinch", args);

In other words, Appium overloads the executeScript command, and allows you access to these three iOS-specific gesture methods (“swipe”, “scroll”, and “pinch”). Each of them takes an appropriate argument object.

This functionality is now available as a TestProject addon! The iOS Gesture Toolkit Addon makes three new actions available:

  • Swipe – takes a “direction” parameter (can be “up”, “down”, “left”, or “right”).
  • Scroll – takes the same parameters as swipe (but remember that an “up” swipe will move content down, whereas a “down” scroll will move content down, and they vary in speed).
  • PinchZoom – takes two parameters, “scale” and “velocity”.
    • Scale determines how much the view will be pinched or zoomed. For a pinch, use a value between 0 and 1. For a zoom, use a value greater than 1.
    • Velocity determines how quick the pinch/zoom will occur, in arbitrary units defaulting to 1.0 (try higher or lower to experiment with other behaviors)

In many cases, using TestProject‘s standard point-and-click swipe helper will probably get you what you need. But if you run into a situation on iOS where for some reason it’s not triggering your view’s event handlers, give this toolkit a try. I expect it to be especially useful for pinch/zoom! Thanks for checking out the addon and let me know what you think 😉

About the author

Jonathan Lipps

Jonathan has been making things out of code as long as he can remember. Jonathan is the architect and project lead for Appium, the popular open source automation framework. He is also the founding Principal of Cloud Grey, a consulting firm devoted to helping clients leverage the power of Appium successfully. He has worked as a programmer in tech startups for over 15 years, but is also passionate about academic discussion. Jonathan has master’s degrees in philosophy and linguistics, from Stanford and Oxford respectively. Living in Vancouver, he’s an avid musician, and also writes on the philosophy of technology.

Jonathan also writes the weekly newsletter and blog Appium Pro, which delivers fantastic Appium-related tips and tutorials straight to your inbox every Wednesday.

Leave a Reply