Appium Flaky Tests: Causes and Fixes for Android and iOS

Rerun the Suspect Appium Test With Retries Off

Run the test file ten times on the same build and keep a JUnit XML report from each run. pytest writes one with --junitxml, and most Java and JavaScript test runners can write the same format.

mkdir -p reports
for i in $(seq 1 10); do
  pytest tests/test_checkout.py --junitxml="reports/run-$i.xml" || true
done
python flaky_report.py reports/run-*.xml

The script below reads those reports, marks each test stable, flaky or broken, and labels every failure with the layer its error message points to. It needs only the Python standard library.

import re
import sys
from collections import Counter, defaultdict
from xml.etree import ElementTree as ET

# First match wins, so the specific patterns come first.
KINDS = [
    ("stale element", r"StaleElementReference"),
    ("session expired", r"InvalidSessionId"),
    ("driver start",
     r"instrumentation process|WebDriverAgent|xcodebuild"),
    ("wait timed out", r"TimeoutException"),
    ("element not found", r"NoSuchElement"),
]


def kind_of(text):
    for kind, pattern in KINDS:
        if re.search(pattern, text):
            return kind
    return "other"


results = defaultdict(list)
for path in sys.argv[1:]:
    for case in ET.parse(path).iter("testcase"):
        if case.find("skipped") is not None:
            continue
        bad = case.find("failure")
        if bad is None:
            bad = case.find("error")
        outcome = None
        if bad is not None:
            outcome = kind_of(bad.get("message", ""))
        key = (case.get("name"), case.get("classname"))
        results[key].append(outcome)

rows = []
for (name, cls), runs in results.items():
    fails = [r for r in runs if r is not None]
    passed = len(runs) - len(fails)
    if not fails:
        verdict = "stable"
    elif passed:
        verdict = "flaky"
    else:
        verdict = "broken"
    order = {"flaky": 0, "broken": 1, "stable": 2}[verdict]
    rows.append((order, -len(fails), name, cls, passed,
                 len(runs), verdict, Counter(fails)))

for _, _, name, _, passed, total, verdict, kinds in sorted(rows):
    detail = ", ".join(f"{k} x{n}" for k, n in kinds.items())
    print(f"{name:<21}{passed}/{total}  {verdict:<7}{detail}".rstrip())

Run against five sample JUnit reports that carry error messages from Appium 3.9.0 and the UiAutomator2 driver, the script prints:

test_deep_link       3/5  flaky  session expired x2
test_search_results  3/5  flaky  stale element x2
test_checkout_total  4/5  flaky  wait timed out x1
test_profile_photo   4/5  flaky  driver start x1
test_onboarding_skip 0/5  broken element not found x5
test_login_valid     5/5  stable

Treat the flaky rows as flakiness to debug. test_onboarding_skip failed all five runs with the same error, which makes it a broken test or a real bug to fix or report rather than a flake to rerun.

Match the Appium Error to the Layer It Points To

Start the Appium server with --log-timestamp so each failure in the report lines up with the server log. Then use the exception class and the message, as Appium 3.9.0 and its drivers send them, to pick the layer:

Explicit Waits Instead of Sleeps in Appium Tests

A time.sleep() call guesses how long the app needs, and an implicit wait applies one timeout to every element lookup. The Selenium documentation on waits says: "Do not mix implicit and explicit waits. Doing so can cause unpredictable wait times."

Leave the implicit wait at Selenium's default of 0 and wait explicitly for the state the next step needs. The Appium Python client uses Selenium's WebDriverWait for this:

import time

from appium.webdriver.common.appiumby import AppiumBy
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.ui import WebDriverWait

# Flaky: a fixed sleep plus an implicit wait on every lookup
driver.implicitly_wait(10)
time.sleep(3)
driver.find_element(AppiumBy.ACCESSIBILITY_ID, "checkout").click()

# Stable: no implicit wait, and an explicit wait for this step
driver.implicitly_wait(0)
wait = WebDriverWait(driver, 15)
wait.until(EC.element_to_be_clickable(
    (AppiumBy.ACCESSIBILITY_ID, "checkout"))).click()

Stale Element Errors in Appium After the Screen Redraws

Appium raises StaleElementReferenceException when an element the test found earlier is no longer in the current UI, for example after a list reloads. Find the element again right before each action instead of keeping the reference:

from appium.webdriver.common.appiumby import AppiumBy
from selenium.common.exceptions import StaleElementReferenceException
from selenium.webdriver.support.ui import WebDriverWait


def tap(driver, locator, timeout=15):
    def attempt(d):
        # Look the element up again on every try
        d.find_element(*locator).click()
        return True

    WebDriverWait(
        driver, timeout,
        ignored_exceptions=[StaleElementReferenceException],
    ).until(attempt)


tap(driver, (AppiumBy.ACCESSIBILITY_ID, "add-to-cart"))

WebDriverWait already ignores NoSuchElementException by default, so the helper retries a missing element and a redrawn one until the timeout.

Appium Locators That Survive New Builds and Languages

Both drivers publish speed rankings for their locator strategies. The UiAutomator2 driver 8.7.3 README rates id, accessibility id and class name at five stars, -android uiautomator at four and XPath at three, and the XCUITest locator reference rates XPath at two stars and says it can be up to 10 times slower than other strategies.

• Android ids - prefer id, which matches the resource-id, or accessibility id, which matches the content description. The README also warns that Google plans to remove UiSelector support from UiAutomator, which would make every -android uiautomator locator invalid.
• iOS names - accessibility id and id both match the element's name attribute, which comes from its identifier or its label, whichever is available first. Labels change with the app's language, so the XCUITest docs recommend accessibilityIdentifier for automation.
• React Native - accessibility id reads the accessibilityLabel prop on Android, while the iOS name attribute comes from testID, so one locator value can match on one platform and miss on the other.
• Jetpack Compose - Compose exposes a testTag as resource-id only when the app turns on testTagsAsResourceId. Since UiAutomator2 driver 8.4.0, the mapTestTagToResourceId setting maps testTag to resource-id from the test side.

from appium.webdriver.common.appiumby import AppiumBy

# Android: resource-id, rated five stars for speed
driver.find_element(AppiumBy.ID, "com.example.shop:id/checkout")

# Android, Jetpack Compose: map testTag to resource-id first
driver.update_settings({"mapTestTagToResourceId": True})
driver.find_element(AppiumBy.ID, "checkout")

# iOS: a predicate string instead of an XPath
driver.find_element(
    AppiumBy.IOS_PREDICATE,
    "type == 'XCUIElementTypeButton' AND name == 'checkout'",
)

Check the real attribute values in Appium Inspector before you write a locator, and see locators in Appium for every strategy with examples.

Expired Appium Sessions and newCommandTimeout

Appium deletes a session that receives no command for appium:newCommandTimeout seconds, which the UiAutomator2 README lists as 60 by default. The server then logs "Shutting down because we waited 60 seconds for a command", and the test's next call fails with InvalidSessionIdException.

Tests reach that limit when a step pauses the client, such as a slow API call to seed data, a long sleep or a breakpoint. Raise the capability for suites that pause on purpose, and keep it above 0: the README says 0 disables the timer, so a session whose client has died is never cleaned up.

UiAutomator2 Server and WebDriverAgent Startup Failures

Before the first command on Android, the UiAutomator2 driver installs its server on the device if needed and waits for it to listen. When the server does not come up in time, the UiAutomator2 driver reports "The instrumentation process cannot be initialized within 30000ms timeout. Make sure the application under test does not crash and investigate the logcat output." Read logcat before you raise the timeout, because an app that crashes on launch fails the same way as a slow emulator.

On iOS, the XCUITest driver builds WebDriverAgent with xcodebuild unless told otherwise, and its capability reference points to a prebuilt or preinstalled WebDriverAgent to reduce session startup time. Build it once, then start sessions with appium:usePrebuiltWDA and appium:derivedDataPath pointing at the build, or let appium:prebuildWDA build it before the launch.

On real devices, keep appium:useNewWDA at its default of false: the XCUITest capability reference says real devices need WebDriverAgent "to run for as long as possible without reinstall/restart". The same reference sets appium:wdaStartupRetries, the number of tries to build and launch WebDriverAgent, to 2 on simulators and 1 on real devices.

Default Timers in Appium 3.9.0 and Its Drivers

The table lists each timer between the test and the device with its default, from the UiAutomator2 8.7.3 README, the XCUITest 12.22.8 reference and the Selenium documentation. Capabilities take the appium: prefix, and settings change during a session through update_settings or at session start through the appium:settings capability.

Unique Ports for Parallel Appium Sessions

Sessions on one machine that share a port collide, and which one fails depends on timing. The UiAutomator2 README asks for a unique udid, systemPort, chromedriverPort (for webviews) and mjpegServerPort (for video) per parallel session, and the XCUITest parallel tests guide asks for a unique udid, wdaLocalPort (8100 by default), derivedDataPath and mjpegServerPort (9100 by default).

With pytest-xdist, the worker_id fixture returns gw0, gw1 and so on, or master when xdist is off, which gives each worker its own port offset:

import pytest


@pytest.fixture
def ports(worker_id):
    n = 0 if worker_id == "master" else int(worker_id[2:])
    android = {
        "systemPort": 8200 + n,
        "chromedriverPort": 9515 + n,
        "mjpegServerPort": 9200 + n,
    }
    ios = {
        "wdaLocalPort": 8100 + n,
        "mjpegServerPort": 9100 + n,
        "derivedDataPath": f"/tmp/wda-{worker_id}",
    }
    return {"android": android, "ios": ios}

For serial runs, both drivers' docs suggest starting the server with --session-override, which closes pending sessions before a new one opens. The guide to Appium parallel testing covers the rest of a parallel setup.

Android Emulators and iOS Simulators on Busy CI Runners

In a 2023 study of computational resources and flaky tests, Silva and colleagues assessed 52 Java, JavaScript and Python projects under 27 resource configurations and found that 46.5% of the flaky tests in their dataset were resource-affected flaky tests. Its abstract singles out continuous integration environments, where tests compete for CPUs and memory, the same resources an emulator on a shared CI runner needs.

• Android emulators - appium:avdLaunchTimeout and appium:avdReadyTimeout default to 60,000 ms each in the UiAutomator2 README. Raise them on slow runners instead of retrying a session that timed out while the emulator booted.
• iOS simulators - appium:simulatorStartupTimeout defaults to 120,000 ms, and the XCUITest capability reference notes that boot can take longer on weak hardware or when other processes use a lot of system resources.
• Hybrid apps - appium:webviewConnectTimeout defaults to 5,000 ms, and the same reference suggests a higher value when tests run on a simulator on a slow host, such as a CI runner.

Leftover App Data and System Dialogs on Test Devices

• App data - appium:noReset keeps the app's data between sessions and appium:fullReset uninstalls the app first, so a test that passes only after another test logged in depends on test order. On real iOS devices, the XCUITest troubleshooting guide says data from an offloaded, cached or failed install can survive fullReset, and only mobile: removeApp clears it.
• Permission prompts - on Android, appium:autoGrantPermissions grants the permissions the app requests at startup when its targetSdkVersion is 23 or higher on Android 6 or later. On iOS, the XCUITest driver leaves appium:autoAcceptAlerts and appium:autoDismissAlerts off by default, while TestMu AI's capability reference lists autoAcceptAlerts as true by default, so set the value explicitly in every environment. The troubleshooting guide also notes that iOS 18 and later can keep a permission choice after the app is reinstalled.
• Toasts - the UiAutomator2 README says toast text stays in the page source for no longer than 3,500 ms after the toast expires, so assert on it right after the action that shows it.
• On-screen keyboard - an open keyboard can cover the next field. In the Python client, driver.is_keyboard_shown() checks for it and driver.hide_keyboard() closes it before the next tap.
• Stuck real iOS devices - the XCUITest troubleshooting guide says a real device that stops responding most often needs a restart, and that a crash of the testmanagerd process can add about 60 seconds to a command.

Network Speed and Third-Party Content in Appium Runs

A test that asserts right after a tap races the network call behind it. Wait for the UI change the response produces, such as an order number appearing, and point tests that are not about the backend at a stub server or seeded test data. For seeded data in CI, Testcontainers can start the database in a throwaway container, and the Testcontainers CI guide lists what each CI runner needs.

To turn a network flake into a failure you can reproduce, pin a slow network. TestMu AI's network throttling for Appium tests sets a profile with the network and networkProfile capabilities, and its 3g-umts-poor profile runs at 200 Kbps down, 64 Kbps up and 400 ms of latency.

# Switch profiles mid-test; networkProfile must be set at session start
driver.execute_script("updateNetworkProfile=4g-lte-good")

On TestMu AI real devices, the blockDomains capability blocks the domains you list, which keeps a third-party domain such as an ad server out of the run.

Note: Reproduce network-timing flakes on real Android and iOS devices with TestMu AI network profiles. Try TestMu AI free

Appium Version Drift Between CI Agents

Two CI agents that installed drivers on different days can run different driver code against the same commit. Appium's extension CLI reference says appium driver update changes only minor and patch versions unless you add --unsafe, so an agent that runs it picks up new patch releases while an agent that does not keeps the old ones.

There is also a major-version trap right now: the newest UiAutomator2 and XCUITest drivers declare a peer dependency on the Appium 4 beta. The npm registry showed this on November 11, 2026:

$ npm view appium version
3.9.0
$ npm view appium-uiautomator2-driver@8.7.3 peerDependencies
{ appium: '^3.0.0-rc.2' }
$ npm view appium-uiautomator2-driver@9.0.2 peerDependencies
{ appium: '^4.0.0-beta.6' }
$ npm view appium-xcuitest-driver@12.22.8 peerDependencies
{ appium: '^3.0.0-rc.2' }
$ npm view appium-xcuitest-driver@13.0.8 peerDependencies
{ appium: '^4.0.0-beta.6' }

Pin the server, the drivers and the client in the CI image, and move them together on purpose. Appium 3.9.0's npm engines field accepts Node.js 20.19 and later 20.x releases, 22.12 and later 22.x releases, or 24 and newer, and the Python client 6.1.5 needs Python 3.10 or newer with Selenium 4.51 or later:

npm install -g appium@3.9.0
appium driver install uiautomator2@8.7.3
appium driver install xcuitest@12.22.8
pip install "Appium-Python-Client==6.1.5"

When you plan the move to the beta, the Appium 4 changes and upgrade checklist lists what changes for test authors.