Locator Strategies

The XCUITest driver supports several location strategies in the native context. The list below describes each strategy along with usage recommendations. For additional recommendations, consider checking the How To Achieve The Best Lookup Performance article.

Class Name

Name	Speed Ranking	Example
className	⭐⭐⭐⭐⭐	XCUIElementTypeButton

This strategy is mapped to the element's type attribute. The full list of supported XCUIElement type names can be found in the XCTest documentation on XCUIElementType.

When to Use

Use this strategy when you want to count the number of elements of a specific type. It is not recommended to use this approach for single element searches, since it may return a different result as soon as at least one other element with the same type value is present. Only use this in individual element searches when you are certain that exactly one such element will always be expected.

Name

Name	Speed Ranking	Example
name	⭐⭐⭐⭐⭐	my name

This strategy is mapped to the element's name attribute.

When to Use

Use this strategy for elements that can be identified using their name attribute value.

Note that the value of this attribute is commonly rendered in the application GUI, which means it is likely to change depending on the application language.

Id

Name	Speed Ranking	Example
id	⭐⭐⭐⭐⭐	my name

This strategy is an alias for the name strategy.

Accessibility Id

Name	Speed Ranking	Example
accessibility id	⭐⭐⭐⭐⭐	my name

This strategy is an alias for the name strategy.

Predicate String

Name	Speed Ranking	Example
-ios predicate string	⭐⭐⭐⭐⭐	(name == 'done' OR value == 'done') AND type IN {'XCUIElementTypeButton', 'XCUIElementTypeKey'}

This strategy is mapped to the native XCTest predicate locator. Check the Predicate Locator Strategy guide for more details on how to build effective predicate expressions. All supported element attributes can be used in these expressions.

When to Use

Use this strategy for elements that can be identified only using one or more of their own attributes - that is, without utilizing their parent, descendant, or sibling elements.

Class Chain

Name	Speed Ranking	Example
-ios class chain	⭐⭐⭐⭐	**/XCUIElementTypeCell[$name == 'done' OR value == 'done'$]/XCUIElementTypeButton[-1]

This strategy is mapped to the native XCTest predicate locator, but with respect to the actual element tree hierarchy. Such locators are basically a supertype of predicate string. Read Class Chain Queries Construction Rules for more details on how to build such locators.

When to Use

Use this strategy for elements that cannot be identified only using their own attributes, but can be identified upon additionally using their parent element(s) and/or their descendant element attribute(s).

XPath

Name	Speed Ranking	Example
xpath	⭐⭐	//XCUIElementTypeButton[@value="Regular"]/parent::*

This strategy is not natively supported by XCTest, and relies on the XML tree generated by the XCUITest driver's page source API. As a result, such locators can be much slower compared to all other ones - sometimes up to 10x slower.

Only XPath 1.0 is supported.

When to Use

Use this strategy for elements that can only be identified when using their siblings and/or specific descendants. It is strongly recommended to use more performant strategies if possible.