Locator Strategies in Appium Vega Driver

Locator strategies are methods used to find and identify user interface (UI) elements within an app during test automation. These strategies act as search patterns that tell Appium how to locate specific elements on the screen, such as buttons, text fields, or other UI components.

Supported strategies

Appium Vega Driver supports UiSelector and XML Path Language (XPath). This release doesn’t support other selector strategies.

UiSelector

A platform-specific locator strategy that uses the native automation framework to identify UI elements. Prefer UiSelector on Vega: in testing it resolved elements about 10 times faster than the equivalent XPath query, and it’s the only strategy that can scope a lookup to a subtree (see Find an element within a parent). Pass a JSON string with an args object whose keys match the element’s attributes in the UI Component Compositor (UCC) tree. Example usage:

element = driver.find_element("UiSelector", '{"args": {"test_id": "kitchen-sink-container"}}')

element = driver.findElement(AppiumBy.ByAndroidUIAutomator.androidUIAutomator("{\"args\": {\"test_id\": \"kitchen-sink-container\"} }"));

Accepted args keys

Key	Description
`test_id`	Matches the element’s test ID. This is usually the most reliable key.
`description`	Matches the accessibility description.
`role`	Matches the element role, such as `text` or `button`.
`focusable`	Matches whether the element can take focus (`true` or `false`).
`enabled`	Matches whether the element is enabled (`true` or `false`).

Find multiple elements

Use the multi-element form to return every match, then filter in your test code.

# Return all focusable elements, then keep the ones that are displayed
elements = driver.find_elements("UiSelector", '{"args": {"focusable": true}}')
visible = [element for element in elements if element.is_displayed()]

Find an element within a parent

To locate a child within a known parent, call the find method on the parent element. This runs a parent-scoped lookup (findElementFromElement). XPath doesn’t work in this position, so UiSelector is the only way to scope a search to a subtree.

parent = driver.find_element("UiSelector", '{"args": {"test_id": "kitchen-sink-container"}}')
child = parent.find_element("UiSelector", '{"args": {"test_id": "card169309"}}')

XPath

A query language that enables navigation and selection of elements in an XML-like structure. Example usage:

element = driver.find_element(by="xpath", value="//*[contains(@description, \"Music\")]")

element = driver.findElement(AppiumBy.xpath("//*[contains(@description, \"Music\")]"));

const element = await driver.$('//*[contains(@description, "Music")]');

element = @driver.wait { |d| d.find_element :xpath, '//*[contains(@description, "Music")]' }

Supported XPath forms

Appium Vega Driver evaluates a single node test with an optional predicate against the app’s element tree. The tree has a <root> element whose descendants are <child> nodes. The driver supports the following forms:

//child                                // All child nodes
//*                                    // Any element
//child[@test_id="card169309"]         // Attribute match
//child[contains(@test_id, "card")]    // Partial attribute match
(//child)[3]                           // Positional index
/root                                  // Root element

The driver doesn’t support compound or multi-step paths. Avoid the following forms:

//parent/child      // Direct-child step
//parent//child     // Descendant step after a node test
//parent/*[1]       // Indexed child of a step
//[contains(...)]   // Missing node test (use //* instead)

To scope a lookup to a subtree, use UiSelector instead of a compound XPath.

Comparison of selector strategies

Feature	UiSelector	XPath
Platform support	Platform-specific	Cross-platform
Performance	Faster (about 10x in testing)	Can be slower
Reliability	More reliable	Might break with UI changes
Complexity	Moderate	Can be complex
Maintenance	Easy for platform-specific tests	Better for cross-platform tests
Debug support	Native tools available	Standard XML tools
Memory usage	Lower	Higher for complex queries

Best practices

Choose the right strategy
- Use UiSelector for platform-specific tests
- Use XPath for cross-platform compatibility
- Prefer UiSelector when performance is critical
Element location
- Use unique identifiers when possible
- Avoid absolute paths
- Keep selectors as simple as possible
- Regularly validate selectors’ reliability
Performance considerations
- Complex XPath queries may impact test execution time
- Cache frequently used elements
- Use app-specific IDs when available
Maintenance tips
- Document locator strategies
- Review locators regularly
- Update with UI changes
- Maintain cross-platform compatibility
- Use meaningful names in test code

​Supported strategies

​UiSelector

​Accepted args keys

​Find multiple elements

​Find an element within a parent

​XPath

​Supported XPath forms

​Comparison of selector strategies

​Best practices