Testing

Appium for Android Automation: A Practical Setup and Testing Guide

HelpMeTest

HelpMeTest

— 6 min read
Appium for Android Automation: A Practical Setup and Testing Guide

Appium is the de facto standard for cross-platform mobile automation, and for Android it sits on top of UIAutomator2 — Google's own UI testing framework. The architecture is layered: your test code talks to an Appium server over HTTP (WebDriver protocol), the server talks to UIAutomator2 running on the device, and UIAutomator2 manipulates the app. Understanding this chain saves you hours of debugging when something goes wrong.

This guide covers the full journey from a blank machine to a running Android test suite. No hand-waving, no skipping the hard parts.

Prerequisites and Environment Setup

You need the Android SDK, a JDK, Node.js, and Appium itself. The ordering matters.

Android SDK: Install Android Studio and use the SDK Manager to install:

  • Android SDK Platform-Tools (adb, fastboot)
  • Android SDK Build-Tools (target version for your app)
  • An AVD image if you're using emulators

Set ANDROID_HOME (or ANDROID_SDK_ROOT) in your shell profile:

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/emulator

JDK: Appium's UIAutomator2 driver is a Java server. Install JDK 11 or 17 and set JAVA_HOME:

export JAVA_HOME=$(/usr/libexec/java_home -v 17)

Node.js and Appium: Install Node 18+ and then Appium:

npm install -g appium
appium driver install uiautomator2

Verify the installation:

appium driver list --installed
# Should show uiautomator2 with version

Run appium-doctor (install with npm install -g appium-doctor) to check your environment. Fix everything it flags before writing a single test. Missing environment variables cause cryptic errors at runtime.

Desired Capabilities for Android

Desired capabilities tell Appium which device to target and how to launch your app. In Appium 2.x, these are structured as appium: prefixed options under the W3C alwaysMatch or firstMatch spec.

Here's a baseline capability set for a local emulator session:

Java (with Selenium/Appium Java client):

UiAutomator2Options options = new UiAutomator2Options();
options.setPlatformName("Android");
options.setDeviceName("emulator-5554");
options.setApp("/path/to/your/app.apk");
options.setAppPackage("com.example.myapp");
options.setAppActivity("com.example.myapp.MainActivity");
options.setAutomationName("UiAutomator2");
options.setNoReset(false);

AndroidDriver driver = new AndroidDriver(new URL("http://127.0.0.1:4723"), options);

Python (with Appium-Python-Client):

from appium import webdriver
from appium.options.android import UiAutomator2Options

options = UiAutomator2Options()
options.platform_name = "Android"
options.device_name = "emulator-5554"
options.app = "/path/to/your/app.apk"
options.app_package = "com.example.myapp"
options.app_activity = "com.example.myapp.MainActivity"
options.no_reset = False

driver = webdriver.Remote("http://127.0.0.1:4723", options=options)

JavaScript (WebdriverIO):

const capabilities = {
  platformName: 'Android',
  'appium:deviceName': 'emulator-5554',
  'appium:app': '/path/to/your/app.apk',
  'appium:appPackage': 'com.example.myapp',
  'appium:appActivity': 'com.example.myapp.MainActivity',
  'appium:automationName': 'UiAutomator2',
};

Key options that affect test reliability:

  • noReset: true — skip app uninstall/reinstall between sessions (faster, but dirty state)
  • fullReset: true — uninstall and reinstall (clean slate, slower)
  • newCommandTimeout — how long Appium waits before closing an idle session (default 60s; increase for slow CI)
  • uiautomator2ServerInstallTimeout — increase this on slow emulators or CI
  • autoGrantPermissions: true — automatically grant all manifest permissions at install time (useful in CI)

Finding Elements: UIAutomator2 Selectors

This is where most Appium tests either shine or fall apart. Bad selectors make flaky tests. UIAutomator2 gives you several strategies — know when to use each.

By resource ID (best option when available):

driver.findElement(By.id("com.example.myapp:id/login_button"));

Resource IDs are stable if developers don't rename them. Use uiautomatorviewer or Android Studio's Layout Inspector to find them.

By accessibility ID (second best):

driver.find_element(AppiumBy.ACCESSIBILITY_ID, "Login Button")

This matches the contentDescription attribute. Works across locales if the description is set in code rather than strings.xml. Coordinate with developers to add meaningful content descriptions on interactive elements.

By UIAutomator2 selector string (powerful, use for complex queries):

driver.findElement(AppiumBy.ANDROID_UIAUTOMATOR,
    "new UiSelector().text(\"Sign In\").className(\"android.widget.Button\")");

UIAutomator selectors support chaining and scrolling:

// Scroll to find an element not yet on screen
driver.findElement(AppiumBy.ANDROID_UIAUTOMATOR,
    "new UiScrollable(new UiSelector().scrollable(true))" +
    ".scrollIntoView(new UiSelector().text(\"Terms of Service\"))");

By XPath (last resort):

driver.find_element(By.XPATH, "//android.widget.Button[@text='Login']")

XPath on Android is slow — UIAutomator2 dumps the full XML hierarchy and then evaluates the expression. For a complex screen this can add 300-500ms per lookup. Use it only when no stable ID or accessibility ID exists.

Appium Inspector is your best friend for selector exploration. It connects to a live session and shows you the element tree with all attributes. Download it from the official Appium GitHub releases.

Handling Alerts and Permissions

Android permission dialogs are system-level dialogs that appear outside your app's context. UIAutomator2 handles them natively because it operates at the system level.

Grant permissions at session start (preferred for CI):

options.setAutoGrantPermissions(true);

Handle permission dialogs at runtime:

# Wait for and accept a permission dialog
try:
    allow_button = WebDriverWait(driver, 5).until(
        EC.presence_of_element_located(
            (AppiumBy.ID, "com.android.permissioncontroller:id/permission_allow_button")
        )
    )
    allow_button.click()
except TimeoutException:
    pass  # No permission dialog appeared

The resource ID for permission buttons varies by Android version:

  • Android 10 and below: com.android.packageinstaller:id/permission_allow_button
  • Android 11+: com.android.permissioncontroller:id/permission_allow_button

Write a helper that tries both:

def accept_permission_if_present(driver, timeout=3):
    ids = [
        "com.android.permissioncontroller:id/permission_allow_button",
        "com.android.packageinstaller:id/permission_allow_button",
        "com.android.permissioncontroller:id/permission_allow_foreground_only_button",
    ]
    for res_id in ids:
        try:
            btn = WebDriverWait(driver, timeout).until(
                EC.presence_of_element_located((AppiumBy.ID, res_id))
            )
            btn.click()
            return True
        except TimeoutException:
            continue
    return False

System alerts (ANR dialogs, crash reports): Handle them by checking for "Wait" or "Close App" buttons. A background thread polling for these can prevent test failures from unrelated crashes.

Emulator vs Real Device

Both have legitimate uses. Neither is universally better.

Emulators:

  • Free, easily reproducible, CI-friendly
  • Consistent performance (no battery, no thermal throttling, no notification noise)
  • Can set arbitrary Android API levels instantly
  • Snapshot support: save app state and restore it in under a second — powerful for test setup
  • Limitations: hardware sensors are simulated, Bluetooth/NFC unreliable, some apps check for emulator and behave differently (banking apps with root/emulator detection)

Real devices:

  • True hardware behavior — touch precision, GPU performance, sensors
  • Required for apps with device attestation, hardware-backed security, or Play Integrity API checks
  • Catch bugs that only manifest on specific hardware (Samsung's OneUI customizations, for instance, have broken countless apps)
  • More expensive and harder to maintain at scale (charging, updates, physical failure)

Practical approach: Run the bulk of your regression suite on emulators in CI. Reserve a small pool of real devices (or use a cloud service like Firebase Test Lab or BrowserStack) for smoke tests and hardware-dependent features.

Emulator setup for CI (GitHub Actions / local):

# Create an AVD
avdmanager create avd \
  --name "test_device" \
  --package "system-images;android-33;google_apis;x86_64" \
  --device "pixel_5"

# Start it headless
emulator -avd test_device -no-window -no-audio -no-boot-anim &

# Wait for boot
adb wait-for-device
adb shell while [[ -z $(getprop sys.boot_completed) ]]; do sleep 1; done

Writing Your First Test (Full Example)

Here's a complete login test in Python that ties everything together:

import pytest
from appium import webdriver
from appium.options.android import UiAutomator2Options
from appium.webdriver.common.appiumby import AppiumBy
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

@pytest.fixture(scope="session")
def driver():
    options = UiAutomator2Options()
    options.platform_name = "Android"
    options.device_name = "emulator-5554"
    options.app_package = "com.example.myapp"
    options.app_activity = ".MainActivity"
    options.auto_grant_permissions = True
    options.no_reset = True

    d = webdriver.Remote("http://127.0.0.1:4723", options=options)
    yield d
    d.quit()

def test_login_with_valid_credentials(driver):
    wait = WebDriverWait(driver, 10)

    email_field = wait.until(
        EC.presence_of_element_located((AppiumBy.ID, "com.example.myapp:id/email_input"))
    )
    email_field.clear()
    email_field.send_keys("test@example.com")

    password_field = driver.find_element(AppiumBy.ID, "com.example.myapp:id/password_input")
    password_field.send_keys("securepassword")

    # Dismiss keyboard before clicking
    driver.hide_keyboard()

    login_btn = driver.find_element(AppiumBy.ID, "com.example.myapp:id/login_button")
    login_btn.click()

    # Assert navigation to home screen
    home_header = wait.until(
        EC.presence_of_element_located((AppiumBy.ID, "com.example.myapp:id/home_title"))
    )
    assert home_header.text == "Dashboard"

Common Pitfalls

StaleElementReferenceException: The element was found before a screen transition and is no longer attached to the DOM. Always re-find elements after any navigation. Use explicit waits with EC.element_to_be_clickable rather than EC.presence_of_element_located when you need to interact.

Implicit vs explicit waits: Never mix them. Set driver.implicitly_wait(0) and use explicit WebDriverWait everywhere. Implicit waits interact badly with expected conditions and can cause double-wait timeouts.

App state between tests: If noReset is true, previous test state bleeds into the next test. Decide on a cleanup strategy: either use fullReset at session start, or add explicit teardown that returns the app to a known state.

Appium server logs are your debugging tool: Run Appium with --log-level debug during development. When a click fails, the server logs show you exactly what UIAutomator2 tried to do and why it failed.

Appium is not magic — it's a translation layer. When tests are unreliable, the answer is almost always in the selectors, the wait strategy, or the capabilities. Debug methodically: check the server logs, inspect the element tree with Appium Inspector, and isolate the flaky step before adding more sleep calls.

Read more

Start now free