Working With Gestures

Gestures are an import part of user interaction in a mobile app. Taps, swipes, and flicks allow users multiple ways to interact with an application in creative and intuitive ways. This guide discusses the API's for calabash-android and calabash-ios.

UITest provides a very large number of API's to simulate gestures or physical interactions with the device. Some (but not all) of these API's are listed below:

  • IApp.DoubleTap – Performs two quick taps on the first matched view.
  • IApp.DragCoordinates – This method simulates a continous drag between two points.
  • IApp.PinchToZoomIn – This method will perform a pinch gesture on the matched view to zoom in.
  • IApp.PinchToZoomOut – This method will perform a pinch gesture on the matched view to zoom out.
  • IApp.ScrollUp / IApp.ScrollDown – Performs a touch gesture that scrolls down or up.
  • IApp.SwipeLeftToRight / IApp.RightToLeft – This will simulate a left-to-right or a right-to-left gesture swipe.
  • IApp.Tap – This will tap the first matched element.
  • IApp.TouchAndHold – This method will continuously touch view.

These APIs all take an AppQuery that is used to locate the view in question. If more than one view is located by the query, then the API will act on the first view found. For example, this code snippet will double tap:


Please see the AppQuery.Marked method for details about how Marked works.

Starting with UITest 0.8.0, it is possible to match elements using a string instead of an AppQuery. These overloaded methods will use the string as a Marked selector to locate the view. For example app.DoubleTap(c=>c.Marked("save_button")) can be written as:



Due to a bug in the iOS simulator, flick/swipe does not work in scroll views such as UITableView or UIScrollView.

Scrolling the Screen to Locate Views

UITest may only interact with views that are visible on the screen. It is possible to use IApp.ScrollUp or IApp.ScrollDown to programatically scroll the view onto the screen. This methods take an AppQuery or a Marked string to reference a specific view. UITest will then scroll until the view is visible on screen. The following snippet demostrates how to scroll down until a Save button is visible:


IApp.Scroll* accepts a second optional parameter that will describe how UITest should simulate scrolling. The possible choices are encapsulated in the ScrollStrategy enum:

Value Description
ScrollStrategy.Auto This is the default value. UITest will use either Programmatically or Gesture when trying to scroll. It is biased towards Programmatically.
ScrollStrategy.Programmatically UITest will scroll the screen as fast as possible until the view is displayed.
ScrollStrategy.Gesture UITest will try to mimic how a user would scroll the screen, using a series of gestures.