Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 37 ยท Locators and Gestures

Locator Strategies

Find elements reliably in Appium. Compare accessibility id, id, class name, XPath and platform selectors, learn which to prefer and how to ask developers for stable ids.

Every interaction starts with finding an element. A locator is a pair of a strategy (how to search) and a value (what to search for). Choosing good locators is the single biggest factor in how stable your suite is: a test with robust locators survives redesigns; a test full of positional XPath breaks every sprint.

This lesson covers the strategies Appium supports, how each maps to Android and iOS, how to rank them and how to work with developers to make the app testable.

The strategies

Strategy Android iOS Notes
accessibility id content-desc name (accessibility identifier or label) Best cross-platform choice
id resource-id name On Android, use the full package:id/name; the driver may also accept the short form
class name View class, e.g. android.widget.EditText Type, e.g. XCUIElementTypeTextField Matches many elements
xpath XPath over the XML source XPath over the XML source Powerful, slowest, most fragile
-android uiautomator UiSelector expression not available Android only
-ios predicate string not available NSPredicate expression iOS only, fast
-ios class chain not available Class chain expression iOS only, fast
css selector web view contexts only web view contexts only Used after switching to a web context

In the Python client these are constants on AppiumBy: AppiumBy.ACCESSIBILITY_ID, AppiumBy.ID, AppiumBy.CLASS_NAME, AppiumBy.XPATH, AppiumBy.ANDROID_UIAUTOMATOR, AppiumBy.IOS_PREDICATE, AppiumBy.IOS_CLASS_CHAIN. The Java client has AppiumBy.accessibilityId(...) and friends.

Python
from appium.webdriver.common.appiumby import AppiumBy

driver.find_element(AppiumBy.ACCESSIBILITY_ID, "login")
driver.find_element(AppiumBy.ID, "com.example.shop:id/search_field")
driver.find_elements(AppiumBy.CLASS_NAME, "android.widget.TextView")
driver.find_element(AppiumBy.XPATH, "//android.widget.Button[@text='Log in']")

find_element returns the first match or raises NoSuchElementException. find_elements returns a list, which is empty when nothing matches, so it is the right call for checking absence.

Accessibility id first

An accessibility id is a label meant for assistive technology. It is stable across redesigns, independent of the visible text (so it survives translations) and fast. It is also good for users: screen-reader users depend on the same labels.

  • Android: set contentDescription on a view (or testTag with semantics { testTagsAsResourceId = true } in Compose, which then shows up as a resource id).
  • iOS: set accessibilityIdentifier (UIKit or SwiftUI .accessibilityIdentifier("login")).
  • React Native: testID maps to the native identifier (on Android it becomes the resource-id, on iOS the accessibility identifier).
  • Flutter: Semantics with an identifier or label, depending on version.

Ask developers to add stable ids as part of every feature. It costs minutes during development and saves days of test maintenance.

id (resource-id)

On Android, resource-id such as com.example.shop:id/login_button is a good second choice. It is stable, unique within a screen and fast. Watch out for ids reused across list rows (every row of a list has the same id); combine with a parent locator in that case.

Class name

Useful to find all elements of a type, like every text field on a form, or the single XCUIElementTypeSwitch on a screen. Rarely unique, so it is typically a building block rather than the final locator.

XPath: the last resort

XPath searches the XML snapshot of the screen. It can express anything, which is the problem. Positional XPath like //android.widget.LinearLayout[2]/android.widget.Button[1] breaks when anything moves. XPath on Appium is also slow: the driver must build the whole XML tree first, which can take seconds on a complex screen.

If you must use XPath, anchor it to something stable and avoid long paths:

TEXT
//*[@content-desc='cart']/following-sibling::*[@resource-id='com.example.shop:id/badge']
//XCUIElementTypeCell[.//XCUIElementTypeStaticText[@name='Total']]

Ranking locators

Prefer, in order:

  1. accessibility id
  2. id (Android resource-id)
  3. Platform selectors: UiSelector (Android), predicate string or class chain (iOS), covered in Android and iOS Native Selectors
  4. class name combined with a parent
  5. XPath

A locator engine in a stand-in

To see exactly how strategies differ, the stand-in below builds a small element tree like the XML an Android driver returns and searches it with several strategies. It is a model, not the real driver.

JS Stand-in: searching a screen tree

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

No output.

Is my locator good?

A good locator is unique, stable and readable. The stand-in below scores candidate locators with a simple heuristic: it penalizes positional paths, visible text (breaks with translations) and long chains. The weights are a team convention, not a standard.

JS Stand-in: locator quality scorer

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

No output.

Lists and repeated elements

Lists reuse ids. To click "Remove" on the row for a particular product, find the row first, then search inside it. Elements have their own find_element method that searches only their subtree:

Python
row = driver.find_element(AppiumBy.XPATH, "//*[@content-desc='row-sneakers']")
row.find_element(AppiumBy.ACCESSIBILITY_ID, "remove").click()

Scoping a search to a parent is faster and more precise than a long global XPath.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which strategy is best for cross-platform tests?

    Accessibility id maps to content-desc on Android and the accessibility identifier on iOS and is stable and fast.
  2. 2. What does find_elements return when nothing matches?

    find_elements returns an empty list, which makes it ideal for checking that something is absent.
  3. 3. Why is a positional XPath such as //LinearLayout[2]/Button[1] fragile?

    It depends on the exact structure of the tree, which changes with every redesign.
  4. 4. How should you click a button inside one row of a list that reuses ids?

    Element-scoped search limits the subtree and avoids matching the wrong row.

Summary

  • A locator is a strategy plus a value; Appium supports accessibility id, id, class name, XPath and platform selectors.
  • Prefer accessibility id, then id, then platform selectors; use XPath last and anchor it to stable attributes.
  • find_element returns the first match or raises; find_elements returns a possibly empty list.
  • Work with developers to add stable test ids to every feature.
  • Scope searches to a parent element for lists and repeated structures.

Next: Android and iOS Native Selectors