Mobile Automation with Appium

Appium's pitch is one API for native Android, native iOS, hybrid apps with webviews, and mobile browsers — and the reason that pitch is credible, rather than marketing, is architectural: Appium is a WebDriver server, and every client speaks the same W3C WebDriver protocol to it. Your test never touches the device directly; it sends HTTP commands to Appium, which translates them for a platform driver, which drives the operating system's own automation framework. Which platforms, app types, and devices are worth automating in the first place was decided in Mobile Testing Approaches; this topic is the mechanism for driving them.

your test (webdriverio / Selenium client / Java client)
      │  W3C WebDriver over HTTP  (POST /session, /element, /click)
      ▼
Appium server (default 127.0.0.1:4723)
      │  driver-specific commands
      ▼
UiAutomator2 (Android)  ·  XCUITest (iOS)  ·  geckodriver-ish web context
      │
      ▼
real app under test — unmodified, no test code compiled in

That last line is the practical advantage over instrumented frameworks (Espresso, XCUITest): the app under test ships unchanged, so the same suite works against a debug build on a simulator and a release-signed build on a physical device. Drivers are installed per server — appium driver install uiautomator2 and appium driver install xcuitest on an Appium 2.x server — and the session capabilities tell the server which one to boot:

const { remote } = require("webdriverio");

const driver = await remote({
  hostname: "127.0.0.1",
  port: 4723,
  capabilities: {
    platformName: "Android",
    "appium:automationName": "UiAutomator2",   // required — selects the driver
    "appium:app": "/builds/app-debug.apk",       // or appium:bundleId for iOS
    "appium:autoGrantPermissions": true,         // never see the install-time dialog
    "appium:noReset": false,                     // fresh state per session
    "appium:newCommandTimeout": 120,
  },
});

Two capability rules settle most "session fails to start" tickets: namespaced capabilities (appium:) are mandatory under the W3C spec, and automationName must match the platform — omit it and Appium guesses, sometimes wrongly on mixed device farms. Hybrid apps add one concept: contexts. The native UI and each webview are separate "pages"; you switch between them like switching browser tabs:

await driver.switchContext("NATIVE_APP");
const cart = await driver.$("~cart-icon");           // native tab bar
await driver.switchContext("WEBVIEW_com.acme.shop"); // requires android WebView debugging enabled
await driver.$("css container").click();               // now CSS selectors work

The webview only appears if the build allows debugging (WebView.setWebContentsDebuggingEnabled(true) on Android, and webview inspection on for iOS builds) — a release build that turns it off will simply not list the context, which is a build configuration problem, not a flaky test.

Two more app types ride the same protocol. Mobile browser sessions drop app: in favor of appium:browserName: Chrome (or Safari) and start a browser context where selectors behave like plain Selenium — so a team covering web and mobile gets one style of wait, one style of assertion, one client library. Session lifetime explains most first-hour failures: creating a session boots and installs the driver app on the device and waits for the UI to settle, which can take 20–40 seconds on a cold farm slot — budget it with a generous start timeout, and set newCommandTimeout so an idle session is reaped instead of holding a device. When a session dies, read the driver log before editing the test: appium --log-level debug (or loglevel: "debug" in the client) prints the exact HTTP command and the device-side stack, and the difference between those two lines tells you whether to fix a locator or a signing/provisioning problem that no test rewrite will touch. The protocol gives you reach; the next chapter is about what to grab.

Two locators for the same button: ~sign-in-button and //android.widget.FrameLayout[1]/android.widget.LinearLayout[2]/android.view.ViewGroup/android.widget.Button[3]. Both work today. When the designer nudges the layout by one container, only the first survives — and across thousands of interactions, that difference decides whether your suite is an asset or a weekly chore. Pick locators by stability first, speed second, convenience never.

Why xpath ranks last, concretely: it walks the whole view hierarchy, so on a list of 200 rows a structural xpath is O(n) per lookup where an accessibility-id lookup is closer to O(1); and a path-encoded xpath (/FrameLayout[1]/LinearLayout[2]/...) rewrites itself into a failure the moment a wrapper view is added — in both apps, on both platforms, for every test that used it. Attribute-based xpath (//android.widget.Button[@content-desc="Sign in"]) is the survivable form, but it is still the fallback, not the default.

The uncomfortable truth behind this table: locator stability is mostly an application-design property. An app that sets content-desc / accessibilityIdentifier on every interactive element (which it should anyway, for screen-reader users) is testable with stable locators; an app with three generic Button elements and no labels forces xpath onto every team that automates it. The highest-leverage contribution a mobile QA engineer makes is a short accessibility audit handed to the devs — testability and screen-reader usability are literally the same attribute. That is why the ranking starts with accessibility ids rather than with whatever the inspector copied first.

Inspect and iterate with Appium Inspector (it speaks to the same server, so what you see is what your test gets), pin a locator the moment it proves stable, and wrap each screen's locators in one object so a label change is a one-file edit — the same encapsulation argument as web page objects, which you may already know from Page Object Basics.

One mechanics rule that saves hours later: re-query, don't hold. A reference captured as const row = await driver.$('~row-3') can go stale after a list refresh — mobile UIs recycle view holders constantly — so resolve the element at the moment of each interaction (a page object that re-queries on every call does this for you) instead of caching across awaits. Lists add a second rule: scrolling is itself an action (mobile: scroll on iOS, UiAutomator's scrollIntoView on Android), and the target must be located after the scroll completes, not before it — locating first and scrolling second guarantees you are holding an element the UI has just discarded.

Then wait correctly: never bare sleeps, always condition waits like await el.waitForDisplayed({ timeout: 5000 }), because a fixed sleep(3000) is both a flake generator on slow devices and three seconds you pay on every one of 400 tests. With locators chosen, the remaining work is the messy part: dialogs, keyboards, and state.

The flow works in the inspector and fails in the suite — almost always because the environment differs between the two: a permission dialog the inspector never triggered, a keyboard covering the submit button, or last run's login token still sitting in shared storage. Each of the four problems below has a scripted answer, and all four belong in your base test setup rather than inside individual tests.

Permission dialogs. The blunt instrument is a capability: "appium:autoGrantPermissions": true makes the driver answer "allow" at install time, which is right for permissions the flow simply needs. It is wrong for the tests that verify denial — those must exercise the dialog or the system setting:

// Android: drive the system dialog itself (it is a different package)
const allow = await driver.$("android:id/button1");       // "While using the app"
if (await allow.isExisting()) await allow.click();
// iOS: the alert belongs to the app's process, matched as a wildcard button
if (await driver.$("**/*").isExisting()) await driver.$("**/*").click();

Keyboard entry. el.setValue("buyer@shop.com") types and triggers listeners; addValue() appends. On iOS, replaceValue() sets the native field directly — the reliable fix when typing into a secure field is slow or filtered. And when the keyboard covers the button you need, await driver.hideKeyboard() (or hideKeyboard({ strategy: "tap outside" })) beats scrolling a view that will not scroll.

Lifecycle events. Move the app the way the OS does, without leaving the test:

await driver.execute("mobile: backgroundApp", { seconds: 5 });     // pause like the user switched away
await driver.execute("mobile: terminateApp", { bundleId: BUNDLE });
await driver.execute("mobile: activateApp",  { bundleId: BUNDLE }); // cold relaunch
await driver.execute("mobile: deepLink", { url: "acme://orders/6f1c" });

Background-for-five-seconds is the cheapest test of "state survives a context switch"; terminate-and-activate is how you prove cold-start restoration; the deep-link call is how push-notification navigation gets tested without a real push (which Gestures, Network, and Offline Testing covers properly).

State reset — the one that actually causes suite-wide flakiness. Without it, run one logs in and seeds a cart; run two starts "already logged in", skips onboarding, and fails an assertion that expected the login screen — an order-dependent failure that reproduces only when you run the full suite. Reset by capability and by command, knowing the difference:

Pick fresh state per test as the default and prove it: run the suite twice in one session and diff the results. If green-then-red appears, something is shared — a file, an account, a database, a server-side fixture — and the fix is isolation, not retries. Interviews on mobile automation come back to exactly three questions: which locator and why, how you synchronize (condition waits, never sleep), and how you keep test N independent of test N−1.