Element Addressing

Map the fact, not the attribute: hold one pair per platform - checked with true on Android's UiAutomator2 driver, value with 1 on iOS's XCUITest driver - normalise the reply to a boolean at the read, and assert on that.

Because the two vocabularies have different resolution. An Android class string such as android.widget.EditText is often narrow enough to hit one control, while the iOS equivalent XCUIElementTypeTextField is a coarse role shared by many, so the find returns the first of several.

Because only the strategy name is shared. On Android the driver compares against resource-id and a Java widget class; on iOS against the name attribute and an XCUIElementType. One locator constant therefore exercises two unrelated app-side contracts.

Capture GET /session/:sessionId/source at the moment of failure and search it for the term. If the node is absent, no XCUITest locator can match it: widen snapshotMaxDepth or snapshotMaxChildren, or fix the app. If present, the locator is wrong.

Android publishes one description field, so content-desc is both what an accessibility id locator matches and what the platform announces, and rewriting the copy rewrites the locator. iOS splits the two: accessibilityIdentifier holds the machine id and the label holds the text.

The selector is an ordinary string that nothing in your build compiles. A misspelt matcher or a bad argument only surfaces when the UiAutomator2 server on the Android device parses the text during the find.

Work three layers in order: the Android list may not be an AdapterView, so onData never applies; the matcher JSON may name a method or class the on-device Espresso server cannot resolve; or the matcher may match no data item.

It decides what an element-scoped xpath find is matched against: by default only that element's subtree, and when switched off the whole page source. Both the UiAutomator2 driver on Android and the XCUITest driver on iOS expose it.

Each xpath find serialises the hierarchy again, so 40 single finds cost 40 documents on both platforms. The iOS document is built from an XCTest element snapshot across the app boundary, so its unit cost is far higher than Android's.

Only Appium's XCUITest driver accepts a class chain, so no path can be shared. Keep one method per element, resolve its locator per platform behind that method, and let the divergence live at a single named seam.

Pin the smallest set of attributes that makes the iOS match unambiguous — usually type plus one identifier. Every extra clause buys precision but costs a rewrite when that attribute changes, and makes a failure harder to read.

Pick one field pair for the whole app, then make every stack fill it: Android resource-id or content-desc, and the iOS accessibilityIdentifier. Put the Android driver settings in the session profile, and verify per screen that the value reached the page source.

Reach, paid for in coupling. Matcher JSON is code as a string, resolved reflectively on the device, so it fails at run time; it pins that part of the suite to Android's Espresso driver; and onData ties tests to the app's data model.

Budget by measured serialisations per platform, not a blanket rule. One xpath find on a shallow screen is affordable on both lanes; the same find inside a loop is wasteful on Android and a stall on iOS.

Both settings control how much of an element comes back with a find. In compact mode the reply carries only the element identifier, so every attribute costs its own request; turning it off makes the driver inline the attributes named in elementResponseAttributes.

It is a pass-through to Google's UiAutomator framework, which exists only on Android; Apple platforms have no equivalent, and Appium's XCUITest driver ships its own dialects. The driver's own documentation warns that Google intends to retire the underlying UiSelector API.

Android's UiAutomator2 driver evaluates XPath 2 by default and can be pushed back to XPath 1 with its enforceXPath1 setting. On iOS, WebDriverAgent evaluates XPath 1.0 only, and the XCUITest settings reference carries no equivalent switch.