Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 37 ยท Locators and Gestures

Android and iOS Native Selectors

Use Android UiSelector and iOS predicate strings and class chains for fast, expressive locators, with syntax examples, scrolling selectors and a builder you can run.

Beyond accessibility id and XPath, each platform has its own selector language that the driver hands straight to the operating system's automation framework. They are faster than XPath (no giant XML document is built), and more expressive than plain attributes. The cost is that they are platform-specific, so use them where a cross-platform locator is not available.

This lesson covers Android's UiSelector, and iOS's predicate strings and class chains. Code that talks to a device is read-only; the builders below are stand-ins that let you practice the syntax.

Android UiSelector

The strategy is -android uiautomator (AppiumBy.ANDROID_UIAUTOMATOR). The value is a Java-like expression built from new UiSelector() calls, evaluated on the device:

Python
driver.find_element(AppiumBy.ANDROID_UIAUTOMATOR, 'new UiSelector().text("Log in")')
driver.find_element(AppiumBy.ANDROID_UIAUTOMATOR, 'new UiSelector().resourceId("com.example.shop:id/go")')
driver.find_element(AppiumBy.ANDROID_UIAUTOMATOR, 'new UiSelector().className("android.widget.Button").enabled(true)')
driver.find_element(AppiumBy.ANDROID_UIAUTOMATOR, 'new UiSelector().textContains("Forgot")')
driver.find_element(AppiumBy.ANDROID_UIAUTOMATOR, 'new UiSelector().descriptionStartsWith("row-")')
driver.find_element(AppiumBy.ANDROID_UIAUTOMATOR, 'new UiSelector().textMatches("^Order #\\\\d+$")')

Common methods:

Method Matches
text, textContains, textStartsWith, textMatches The visible text
description, descriptionContains, descriptionStartsWith content-desc
resourceId, resourceIdMatches resource-id
className, classNameMatches View class
enabled, checked, selected, clickable, focused, scrollable Boolean state
index, instance Position among matches
childSelector, fromParent Relationships

Chain several to combine conditions, all must match. Use .instance(n) to pick the nth match (zero-based).

Scrolling to an element

UiScrollable finds an element that is not on screen yet by scrolling a container:

Python
driver.find_element(
    AppiumBy.ANDROID_UIAUTOMATOR,
    'new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().text("Terms of service"))',
)

This is one of the quickest ways to reach a lower item on a long list on Android. Note that UiScrollable uses its own scrolling, separate from the gestures in Scroll, Swipe and Long Press.

iOS predicate strings

The strategy is -ios predicate string (AppiumBy.IOS_PREDICATE). The value is an NSPredicate expression over element attributes such as name, label, value, type, enabled, visible:

Python
driver.find_element(AppiumBy.IOS_PREDICATE, 'label == "Log in"')
driver.find_element(AppiumBy.IOS_PREDICATE, 'name BEGINSWITH "row-"')
driver.find_element(AppiumBy.IOS_PREDICATE, 'type == "XCUIElementTypeButton" AND enabled == 1')
driver.find_element(AppiumBy.IOS_PREDICATE, 'label CONTAINS[c] "forgot"')
driver.find_element(AppiumBy.IOS_PREDICATE, 'value MATCHES "^[0-9]+$"')

Operators: ==, !=, BEGINSWITH, ENDSWITH, CONTAINS, LIKE (with * and ?), MATCHES (regular expression), combined with AND, OR, NOT. Add [c] for case-insensitive and [d] to ignore diacritics. String values are in double quotes inside the expression, so use single quotes around the whole Python string.

iOS class chain

The strategy is -ios class chain (AppiumBy.IOS_CLASS_CHAIN). It is like a limited XPath: a path of element types with optional predicates in ` ` backticks inside **[...]**, and positional indexes in square brackets:

Python
driver.find_element(AppiumBy.IOS_CLASS_CHAIN, '**/XCUIElementTypeButton[`label == "Log in"`]')
driver.find_element(AppiumBy.IOS_CLASS_CHAIN, '**/XCUIElementTypeCell[2]/XCUIElementTypeStaticText')
driver.find_element(AppiumBy.IOS_CLASS_CHAIN, '**/XCUIElementTypeCell[`name BEGINSWITH "row-"`][-1]')

**/ means "anywhere in the tree". [2] is the second match (one-based), [-1] the last. Class chain is the right tool when you need a structural relationship like a cell and its child label, with better speed than XPath.

When to use which

  • Cross-platform page objects: accessibility id first.
  • Android needs: UiSelector for text matching, state filters and scrolling.
  • iOS needs: predicate strings for attribute patterns, class chain for structure.
  • Anything else: XPath, and keep it small.

Escaping pitfalls

Selector strings are nested inside code strings, so quotes and backslashes multiply. In textMatches, a regular expression digit \d needs doubling for the selector language and again for your programming language. When a selector with a regex fails, build it with a helper or print the final string. The builders below show how helper functions avoid mistakes.

Build selectors in a stand-in

This stand-in builds UiSelector strings from a small description, including quote escaping, so you can see the output form.

JS Stand-in: UiSelector builder

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

No output.

Predicate strings and class chains in a stand-in

This second stand-in evaluates a small subset of iOS predicates against sample elements, to show how the attribute operators behave. It supports only ==, BEGINSWITH, CONTAINS[c] and AND, a deliberately small model.

JS Stand-in: evaluating predicate strings

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

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which strategy runs a UiSelector expression?

    -android uiautomator (AppiumBy.ANDROID_UIAUTOMATOR) passes a UiSelector or UiScrollable expression to the Android driver.
  2. 2. Why are platform selectors usually faster than XPath?

    XPath needs the whole page source as XML; native selectors query the platform framework directly.
  3. 3. Which predicate matches elements whose name starts with row- on iOS?

    BEGINSWITH is the NSPredicate operator for prefix matching; string values are double quoted.
  4. 4. What does UiScrollable.scrollIntoView do?

    It scrolls the container and finds the element in one command, useful for long lists on Android.

Summary

  • Android: -android uiautomator with UiSelector for text, state, regex and UiScrollable for scrolling.
  • iOS: -ios predicate string for attribute rules, -ios class chain for structural paths.
  • Both are faster than XPath but are platform-specific; use them when accessibility id is not enough.
  • Quote and backslash escaping is the main source of errors; build strings with helpers.

Next: Waits and Synchronization