Timeouts & Waiting
- PDF for offline use:
- Related APIs:
Let us know how you feel about this.
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.
It is a poor practice to use
sleep to pause the execution of a test while waiting for the application being tested to finish some action.
Instead, 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'") end
wait_for takes a hash of options that allow developers some control over how
|The maximum number of seconds to wait before throwing a `WaitError`. Defaults to 30 seconds.|
|The number of seconds to wait between retries. Defaults to 0.3 seconds.|
|The number of seconds to wait after the condition is satisified. Defaults to 0.|
|The error message to display if the condition is not satisified.|
|If set to
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:
If no view appears on the screen within 30 seconds, then a
WaitError will be thrown.
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'") tap_mark("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: