Timeouts & Waiting

PDF for offline use
Related APIs:

Let us know how you feel about this


last updated: 2016-10

It may be necessary for a test to pause execution to allow the user interface to update or for a long running action to complete. For example, a test needs to pause until some task, which it displaying a progress bar, is finished (and therefore dismissing the progress bar).

It is also a good practice for a test to check that a view exists before trying to interact with it. Many of the Calabash API's will fail if a view is animating or not visible.

Calabash provides the wait_for function which will help developers write tests that gracefully pause for some condition to be met. The condition is expressed in the form of a code block that will return true. The code block will be given a number of seconds to return true before a WaitError will be thrown. wait_for has the following signature:

- (nil) wait_for(options_or_timeout = DEFAULT_OPTS, &block)

The following snippet is an example of how to use wait_for to detect the presence of a button on the screen:

wait_for(timeout: 60, timeout_message: "Could not find 'Sign in' button") do
    element_exists("button marked:'Sign in'")

wait_for takes a hash of options that allow developers some control over how wait_for works.

:timeoutThe maximum number of seconds to wait before throwing a `WaitError`. Defaults to 30 seconds.
:retry_frequencyThe number of seconds to wait between retries. Defaults to 0.3 seconds.
:post_timeoutThe number of seconds to wait after the condition is satisified. Defaults to 0.
:timeout_messageThe error message to display if the condition is not satisified.
:screenshot_on_errorIf set to true, then generate a screenshot on error.

Helper Methods

wait_for is intended to be a low level function that forms the basis for a number of WaitHelper methods available that are based on this method. As an example of one of these helpers, the wait_for_element_exists wait until a view, identified by a Calabash query, appears on the screen. This snippet demonstrates how to use the helper:

wait_for_element_exists("button marked:'foo'")

If no view appears on the screen within 30 seconds, then a WaitError will be thrown.

There are differences between the WaitHelpers for Android and the WaitHelpers for iOS. You are strong encouraged to read the API document for each platform

Calabash-iOS and wait_tap

A very common practice is to use wait_for_element_exists to verify that a view has appear (or has stopped animating), and then touch it. For example:

wait_for_element_exists("button marked:'foo'")

Calabash iOS provides the wait_tap method reduces this boilerplate code. It will wait for a view to appear/stop animating before tapping it:

wait_tap("button marked:'foo'")

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.