Gestures

Simulating Gestures in Calabash Tests

PDF for offline use
Related APIs:
Related Links:

Let us know how you feel about this


0/250

Overview

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.

Calabash provides these API's:

  • double_tap – Simulates the user tapping on a view twice in rapid succession.
  • flick – This method will simulate a flick, a straight line swipe that lifts the finger while the gesture is still in motion. A flick may also be referred to as a swipe.
  • long_press – A long press simulates the user touching a view for a period of time longer than a tap.
  • pan – This method will simulate a pan, a straight line swipe that pauses before the finger is lifted.
  • swipe – This method simulates a straight line swipe that lifts the finger while the gesture is still in motion. A swipe is also referred to as a flick.
  • tap – A tap is a single, brief touch on a view.

All of these methods will take a Calabash query to help them locate the view to perform the gesture upon. If the query cannot resolve the view, then a ViewNotFoundError will be raised. If the query is invalid, then a ArgumentError will be raised.

The touch API's assume that the view is visible and it is not animating. If the view is not visibile an error will be thrown. If the view is animating then the method will silenlty fail.

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

Calabash Gesture APIs

This section will discuss the gestures APIs available in calabash-android and calabash-ios.

double_tap

This gesture is used to simulate a double tap in the screen. It takes a query to identify the view that will be a target of the gesture. For example:

double_tap "Button marked:'save_button'"

double_tap will touch the centre of the view. It is possible to specify what part of the view to touch by providing an optional offset. The offset is relative to the centre of the view.

double_tap "Button marked:'save_button'", offset:{x:-50,y:-10}

flick, pan, and swipe

flick and pan are very similar methods that differ only in one detail – in a flick the finger will lift from the screen while the gesture is in motion, while in a pan the finger is not lifted until after the gesture is complete.

swipe is an older API that is conceptually similar to flick, but takes different parameters and in a different order. The API's are different between Android and iOS, which are covered in their own sections below.

Android

The following snippets demonstrate how to flick to the right on a view in calabash-android, first by using flick and then by using swipe:

flick "view marked:'table_row'", :right

flick will start in the centre of the view and proceed in the specified direction, stopping at the edge of the screen.

swipe :right, :query:"view marked:'table_row'"

Android also provides some helper methods for flicking in a specific direction:

iOS

In calabash-ios, the swipe function is the simplest way to simulate a flick:

swipe :left, query:"view marked:'table_row'"

The query parameter is optional and is used to locate a view that will be the recipient of the flick. If query is omitted, then the swip will occur in the centre of the screen.

In contrast, flick requires a query to identify a view and a delta. The delta is a point on the screen that calabash-ios will flick towards, from the center of the view. The following diagram demonstrates the concepts of a flick:

Likewise the following code snippet is an example of how to use flick:

flick "view marked:'table_row'", {x:100, y:50}

long_press

This function is only available in calabash-android, there is no corresponding method in calabash-ios. It is used to simulate a long press or a long click on an Android widget. long_press takes a query that is used to identify a specific view on the screen. The following snippet is an example of how to long press on TextView that is inside a ListView:

long_press "ListView TextView index:1"

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.