Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 37 ยท Locators and Gestures

Waits and Synchronization

Stop flaky Appium tests with proper waits. Compare sleep, implicit and explicit waits, expected conditions, polling and driver settings, and build a wait helper.

Apps are not instant. A screen may need a network response, an animation, or a database read before an element appears. Your test, however, runs commands as fast as it can. If it looks for the "Welcome" label one millisecond before the app draws it, the test fails even though the app is correct. This mismatch is called a synchronization problem, and it causes most flaky Appium tests.

Native frameworks such as Espresso hide this by knowing when the app is idle. Appium cannot, so you must wait explicitly. This lesson covers the tools and, more importantly, the habits.

Why sleep is the wrong answer

The tempting fix is time.sleep(5). It is wrong for two reasons:

  • Too slow. If the element appears in 400 ms you still pay five seconds, for every step, in every test.
  • Still flaky. On a slow CI machine the screen might need six seconds, and the test fails anyway.

A good wait returns as soon as the condition is true and fails only after a limit.

Implicit wait

An implicit wait is a session-wide setting: every find_element keeps retrying for up to N seconds before raising NoSuchElementException.

Python
driver.implicitly_wait(5)
driver.find_element(AppiumBy.ACCESSIBILITY_ID, "greeting")   # retries for up to 5 s

It is easy, but it has drawbacks. It applies to every lookup, so checks for absence also wait the full time. It cannot wait for conditions other than presence (clickable, text equal, gone). And mixing it with explicit waits can produce surprising total delays. Many teams set it to 0 and use only explicit waits.

Explicit wait

An explicit wait polls a condition you choose, for a limit you choose. In the Python client it comes from Selenium's WebDriverWait:

Python
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

wait = WebDriverWait(driver, timeout=10, poll_frequency=0.5)

button = wait.until(EC.element_to_be_clickable((AppiumBy.ACCESSIBILITY_ID, "login")))
button.click()

wait.until(EC.visibility_of_element_located((AppiumBy.ACCESSIBILITY_ID, "greeting")))
wait.until(EC.invisibility_of_element_located((AppiumBy.ACCESSIBILITY_ID, "spinner")))
wait.until(lambda d: d.find_element(AppiumBy.ACCESSIBILITY_ID, "count").text == "3")

Useful conditions: presence, visibility, clickable, invisibility (spinner gone), text equals or contains, and any custom function that returns something truthy. Failures raise TimeoutException with the condition in the message, which is far more helpful than a plain "no such element".

Java has WebDriverWait with ExpectedConditions (and FluentWait for custom polling and ignored exceptions); JavaScript's WebdriverIO and Node clients have waitUntil and waitForDisplayed.

Wrap waits in your own helpers

Repeating wait.until(EC...) everywhere hides the intent. Provide small helpers: tap(locator) that waits until clickable then clicks, type(locator, text), text_of(locator). All page objects (see the page-object chapter later) then use waits automatically, so test bodies read like plain steps.

What to wait for

Wait for an observable state, not for time:

  • Before tapping: the element is displayed and enabled.
  • After navigation: an element unique to the next screen is visible.
  • After submitting: the progress indicator is gone.
  • After data loads: the list has at least one row.

Waiting for the next screen's marker element also acts as an assertion: if the app navigates wrongly, the test fails with a clear timeout.

Driver-level synchronization

Drivers have their own settings that interact with your waits:

  • UiAutomator2 settings such as waitForIdleTimeout (how long to wait for the UI to settle before an action) and waitForSelectorTimeout.
  • XCUITest settings such as waitForIdleTimeout and animationCoolOffTimeout, and the snapshotMaxDepth setting for complex screens.
  • Disabling animations on the device (system settings or the disableWindowAnimation capability on Android) removes a major source of timing noise.

Do not tune these first. Add explicit waits for conditions and only then adjust driver settings for specific slow screens.

Handling slow and flaky first loads

Cold starts are slowest: the first screen after install can take much longer than later ones. Give the first wait of a test a larger timeout, or add a "wait for app ready" helper that waits for a known home-screen element with a generous limit.

Build a wait helper in a stand-in

The stand-in below implements a polling waitUntil with a simulated clock, so the output is exact and repeatable. The fake app draws a greeting after 1.3 seconds.

JS Stand-in: polling wait with a fake clock

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that the first wait finished after 1500 ms, the first poll after the element appeared, not after a fixed five seconds. That is the whole point.

Compare strategies in a stand-in

This second stand-in measures the total time of three strategies over twenty steps whose delays vary. The delays come from a fixed list, not from random numbers, so the numbers are reproducible.

JS Stand-in: sleep versus polling

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Common mistakes

  • Using find_element and then checking is_displayed() immediately, with no wait.
  • Adding a global long implicit wait and then wondering why negative checks are slow.
  • Waiting for an element that exists in the tree but is not yet usable (disabled button): wait for clickable, not present.
  • Catching TimeoutException and continuing, which hides real failures.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is time.sleep(5) a poor synchronization strategy?

    A fixed delay cannot adapt to the real time the app needs.
  2. 2. What does an explicit wait do?

    Explicit waits retry a condition you specify and return as soon as it holds.
  3. 3. Which is a disadvantage of a large implicit wait?

    Because it applies to all lookups, checking that something is NOT present takes the whole timeout.
  4. 4. After tapping Submit, what is a good thing to wait for?

    Waiting for an observable state is both a synchronization and an implicit assertion.

Summary

  • Synchronization problems cause most flaky UI tests; Appium cannot see when the app is idle.
  • Never use fixed sleeps; poll for a condition with a timeout.
  • Prefer explicit waits (visible, clickable, invisible, text) and keep implicit waits at 0 or small.
  • Wrap waits in helpers so page objects and tests stay readable.
  • Disable animations and tune driver idle settings only after adding the right waits.

Next: W3C Actions and Gestures