Locator Strategies

The Mac2 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 elementType 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 elementType 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 identifier attribute.

When to Use

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

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
predicate string	⭐⭐⭐⭐⭐	(name == 'done' OR value == 'done') AND type IN {'XCUIElementTypeButton', 'XCUIElementTypeKey'}

This strategy is mapped to the native XCTest predicate locator. Refer to the XCUITest driver's Predicate Locator Strategy guide for more details on how to build effective predicate expressions. All supported element attributes can be used in these expressions. A few of them have no native XCTest equivalent that predicate expressions can reference directly, so they are only usable through their am-prefixed alias: amRect, amText, amType and amHasKeyboardInputFocus. Separately, amIdentifier is the only reliable way to match WKWebView web elements by their DOM id from this strategy - see useDomIdAsAccessibilityId - e.g. amIdentifier == 'done'.

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
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. As with predicate string, the am-prefixed attribute aliases can be used at any position in the chain, including amIdentifier to reliably match WKWebView web elements by their DOM id.

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 Mac2 driver's page source API. As a result, such locators can be much slower compared to all other ones - sometimes up to 10x slower.

XPath 2.0 is supported since Mac2 driver version 1.20.0. Older driver versions only support XPath 1.0 (based on xmllib2).

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.