DEV Community

Cover image for XCUITest Locators: IDs, Labels, Text and Element Queries
QAPulse by SK
QAPulse by SK

Posted on Originally published at skakarh.com

XCUITest Locators: IDs, Labels, Text and Element Queries

#iostesting #iosuiautomation #mobiletestautomation #sdet

XCUITest Locators are the foundation of reliable iOS UI automation because they determine how tests find buttons, text fields, labels, cells, images, and other elements. A strong locator strategy reduces flaky tests, survives UI changes, and makes XCUITest suites easier to maintain as applications grow.

What are XCUITest Locators?

XCUITest locators are query mechanisms used by XCUITest to identify UI elements exposed through the application’s accessibility hierarchy.

Apple’s XCUIAutomation framework provides XCUIElementQuery specifically for defining search criteria used to identify UI elements in tests. (Apple Developer)

A typical flow is:

XCTestCase
    ↓
XCUIApplication
    ↓
XCUIElementQuery
    ↓
Locator Strategy
    ↓
XCUIElement
    ↓
Interaction / Assertion
Enter fullscreen mode Exit fullscreen mode

For example:

let app = XCUIApplication()

let loginButton = app.buttons["login.submitButton"]

loginButton.tap()
Enter fullscreen mode Exit fullscreen mode

Here:

  • app.buttons identifies the element type.
  • "login.submitButton" identifies the target.
  • The resulting object is an XCUIElement.
  • tap() performs the interaction.

Apple’s documentation describes XCUIElement as a UI element in an application and XCUIElementQuery as the object defining the search criteria used to identify elements. (Apple Developer)

Definition

XCUITest locators are element-query strategies used to identify iOS UI elements through properties such as accessibility identifiers, labels, titles, values, placeholders, predicates, element types, and hierarchy.

A locator should ideally be:

  • Stable
  • Unique
  • Readable
  • Semantic
  • Fast to resolve
  • Resistant to UI changes

Key Points

  • Accessibility identifiers are usually the preferred automation contract.
  • Element type makes a selector more precise.
  • Labels can be useful for stable user-facing elements.
  • Text-based selectors can become fragile with localization.
  • Predicates handle more advanced matching requirements.
  • Hierarchy queries can scope searches to a specific container.
  • Index-based queries should be used only when position is intentional.
  • Coordinates should be a last resort.
  • XCUIElementQuery produces the elements used by the test.
  • Good locator design is part of test architecture.

How XCUITest Locators Work

The application exposes an accessibility hierarchy.

XCUITest queries that hierarchy to identify elements.

iOS Application
      ↓
Accessibility Hierarchy
      ↓
Element Type
      ↓
Identifier / Label / Text / Value
      ↓
XCUIElementQuery
      ↓
XCUIElement
Enter fullscreen mode Exit fullscreen mode

The important point is that XCUITest does not simply search the rendered pixels on the screen.

It works with UI elements and their exposed attributes.

Apple’s XCUIElementAttributes protocol exposes attributes including identifier, elementType, label, title, value, and placeholderValue, which can participate in element identification and state inspection. (Apple Developer)

1. ID-Based Locators

Accessibility identifiers are generally the strongest choice for application-owned UI elements.

SwiftUI:

Button("Log In") {
    login()
}
.accessibilityIdentifier("login.submitButton")
Enter fullscreen mode Exit fullscreen mode

XCUITest:

let loginButton =
    app.buttons["login.submitButton"]

loginButton.tap()
Enter fullscreen mode Exit fullscreen mode

UIKit:

loginButton.accessibilityIdentifier =
    "login.submitButton"
Enter fullscreen mode Exit fullscreen mode

Test:

let loginButton =
    app.buttons["login.submitButton"]

XCTAssertTrue(
    loginButton.waitForExistence(timeout: 10)
)

loginButton.tap()
Enter fullscreen mode Exit fullscreen mode

Why IDs Are Strong

The visible text might change:

Log In
Enter fullscreen mode Exit fullscreen mode

to:

Sign In
Enter fullscreen mode Exit fullscreen mode

The identifier can remain:

login.submitButton
Enter fullscreen mode Exit fullscreen mode

This separates automation identity from presentation text.

For long-term automation, this is an important architectural decision.

2. Label-Based Locators

XCUITest can identify elements using their labels.

For example:

let loginButton =
    app.buttons["Log In"]
Enter fullscreen mode Exit fullscreen mode

A label-based selector can be convenient when the label is stable and meaningful.

It can also be useful for validating accessibility behavior.

However, labels are often affected by:

  • Localization
  • Product terminology
  • Content changes
  • Accessibility configuration
  • Dynamic data

Therefore, do not automatically assume that every visible label is a good permanent automation selector.

Apple exposes label as one of the attributes available from XCUIElement. (Apple Developer)

3. Text-Based Locators

Text is frequently used when testing static UI content.

For example:

let heading =
    app.staticTexts["Welcome Back"]
Enter fullscreen mode Exit fullscreen mode

Or:

XCTAssertTrue(
    app.staticTexts["Dashboard"]
        .waitForExistence(timeout: 10)
)
Enter fullscreen mode Exit fullscreen mode

Text-based queries are useful when the text itself is what the test needs to validate.

For example:

func testSuccessfulLogin() {

    let loginButton =
        app.buttons["login.submitButton"]

    loginButton.tap()

    XCTAssertTrue(
        app.staticTexts["Dashboard"]
            .waitForExistence(timeout: 10)
    )
}
Enter fullscreen mode Exit fullscreen mode

Here the button uses a stable identifier while the dashboard text validates the user-visible outcome.

👉 Continue reading the full article on skakarh.com →

Originally published at skakarh.com/xcuitest-locators.
Subscribe to QA Pulse by SK —
weekly signal for QA, Test Automation and AI in Software Engineering.

Top comments (0)