skip to content

In SwiftUI, what does accessibilityIdentifier(_:) add to a login screen's Sign In button, and why do UI tests prefer it to the button's label?

level: juniorimportance: should knowfreq 50%

answer

  1. for tests, not for people
  2. labels get localized and reworded
  3. put it on the element the test taps
  4. unique ids for repeated rows

basics

~20 s

accessibilityIdentifier(_:) attaches a string to the view's accessibility element for tests; users never see or hear it. UI tests prefer it because the label is localized and reworded, while an identifier like login.signIn stays stable.

solid answer

~40 s

`accessibilityIdentifier(_:)` sets an identifier on the view's accessibility element. Apple's documentation says to use it for testing and that it is not visible to the user: VoiceOver reads the label, never the identifier. UI tests find elements through the accessibility tree, so they can query by label, but a label changes when copy is reworded or the app runs in another language, and the same label can appear twice. An identifier such as `"login.signIn"` stays fixed through all of that. Put it on the control the test interacts with, not on a surrounding stack, give repeated rows unique values built from the model's id, and remember that hiding a view from accessibility hides it from UI tests too. iOS 18 added `accessibilityIdentifier(_:isEnabled:)` to apply one conditionally.

code

swift · 22 lines
swift
import SwiftUI

struct LoginForm: View {
    @Bindable var model: LoginModel

    var body: some View {
        Form {
            TextField("Email", text: $model.email)
                .accessibilityIdentifier("login.email")
            SecureField("Password", text: $model.password)
                .accessibilityIdentifier("login.password")
            Button("Sign In") {
                Task { await model.signIn() }
            }
            .accessibilityIdentifier("login.signIn")
            if let message = model.errorMessage {
                Text(message)
                    .accessibilityIdentifier("login.error")
            }
        }
    }
}

go deeper

for a junior

Recall that the identifier is for tests and invisible to users, and that labels change with copy and language while identifiers do not.

for a middle

Explain where the identifier must sit: on the control or a combined element, unique per row, and how accessibilityHidden removes it from tests too.

for a senior

Set a naming convention and catch, in review, identifiers on layout containers or shared by repeated rows before they become flaky UI tests.

for a principal

Decouple UI tests from copy and accessibility wording so neither localization nor VoiceOver improvements break the suite.

## What the modifier does `accessibilityIdentifier(_:)` is a SwiftUI view modifier, available since iOS 14, that attaches a string to the **accessibility element** the view produces. Apple's documentation is short and clear: use this value for testing; it is not visible to the user. That means: - **VoiceOver does not speak it.** VoiceOver reads the element's label, value and hint. The identifier is invisible to people using the app. - **It changes nothing on screen.** No layout, hit-testing or appearance change. - **UI tests can see it.** UI test frameworks find elements through the accessibility tree, and the identifier is one of the attributes they match on. The UI-test side (queries, launch arguments, waiting for elements) belongs to the lessons on UI automation; this question is about what you put on the SwiftUI side. ## Why not find the button by its label A `Button("Sign In")` gets the accessibility label "Sign In" for free, and a UI test can find it that way. It works until it does not: | Change | Label-based query | Identifier-based query | |---|---|---| | Copy changes to "Log In" | breaks | keeps working | | App runs in German | breaks | keeps working | | A second "Sign In" appears (a sheet, a banner) | ambiguous | unique if ids are unique | | VoiceOver wording improved with `accessibilityLabel` | breaks | keeps working | The last row matters: if tests depend on labels, every accessibility improvement risks breaking a test, which discourages the improvement. Identifiers decouple the two. ## Where to put it 1. **On the control the test interacts with.** Attach it to the `Button`, `TextField` or `SecureField`, not to the `Form` or a `VStack` around them. A plain stack is a layout container, and where an identifier on it ends up is easy to get wrong. 2. **On the element as the accessibility tree sees it.** If you merge a row's icon and text with `accessibilityElement(children: .combine)`, the row is now one element; put the identifier on the combined view so the test finds that one element. 3. **Unique within the screen.** In a `ForEach`, build the id from the model: `"account.\(account.id)"`. Ten rows sharing `"accountRow"` make every query ambiguous. 4. **Named by convention.** A scheme such as `screen.element` (`login.email`, `login.password`, `login.signIn`, `login.error`) keeps ids readable in test failures. ## Ways a UI test can find an element | Match on | Stable across copy edits | Stable across languages | Notes | |---|---|---|---| | Identifier | yes | yes | set by the developer for tests only | | Label | no | no | also what VoiceOver says | | Element type and position | yes | yes | breaks when the layout gains or loses an element | An identifier is the only option that is both stable and independent of what users hear. It also documents intent: reading `.accessibilityIdentifier("login.signIn")` in a pull request tells the reviewer a test depends on that control, so renaming or removing it needs a matching test change. ## Interactions with other accessibility modifiers - `accessibilityHidden(true)` removes the element from the accessibility tree. That hides it from VoiceOver **and** from UI tests, so do not hide something a test must find. - `accessibilityLabel(_:)` changes what VoiceOver says; it does not touch the identifier. - From iOS 18, `accessibilityIdentifier(_:isEnabled:)` applies the identifier only when `isEnabled` is `true`; otherwise the identifier is left unchanged. Projects still deploying to iOS 17 apply the identifier unconditionally or branch on availability. ## Identifiers in shared components A reusable component, such as a primary button style or a text field with a validation message, often appears several times on one screen. Let the caller pass the identifier in, or derive it from a value the caller supplies, rather than hard-coding one inside the component; a constant baked into a component repeats on every use and makes queries ambiguous. ## Review checklist - Every control a UI test drives has an identifier. - No identifier is a user-facing string or a localized key. - Identifiers are unique per screen, and repeated rows include a stable model id. - Identifiers sit on controls or on deliberately combined elements, not on layout containers.

  • How do you give identifiers to rows in a ForEach of saved accounts?
    Build each identifier from a stable model property, for example `.accessibilityIdentifier("account.\(account.id)")`. Using the row index breaks when rows are inserted or reordered, and a shared constant makes every query ambiguous.
  • When is the iOS 18 accessibilityIdentifier(_:isEnabled:) overload useful?
    When an identifier should apply only in some states, without wrapping the view in an `if` that changes its structure. Passing `isEnabled: false` leaves the identifier unchanged. An app that still supports iOS 17 needs an availability check or the plain `accessibilityIdentifier(_:)`.

  • VoiceOver reads the accessibility identifier to the user
  • Querying UI tests by the visible button title is just as stable
  • Put one identifier on the Form and the tests will find every field
  • accessibilityHidden(true) keeps the element available to UI tests
  • Reusing one identifier for every row in a list is fine

Assumes the iOS 27 SDK; accessibilityIdentifier(_:) exists since iOS 14, and the isEnabled: overload was added in iOS 18.