XCUITest review: iOS UI testing tutorial and pitfalls

A UI test target builds a separate test runner. XCUIApplication is a proxy for the app under test: it launches, activates and terminates the target app and reports its state, while the test code runs in its own process. Apple described UI tests as running in a separate process and relying on accessibility from the start, and that model explains most of their behaviour. A test cannot call the app’s functions, read its view models or swap its dependencies. It can only see what the accessibility layer exposes and send synthesised taps, swipes and key presses. Anything the test needs to control inside the app goes through launch arguments and environment variables set before launch.

app.buttons["login.submit"] does not find anything when the line runs; it builds an XCUIElementQuery that is resolved against the current accessibility hierarchy when you tap it, read a property or check exists. That makes element references cheap and always fresh, so stale references are rare. It also means ambiguity surfaces late: a query that matches several elements fails at the moment of interaction, which is why unique accessibility identifiers matter more than in most frameworks. Actions such as tap need a hittable point, so an element covered by another view or off screen fails even though it exists.

Before synthesising each event, XCTest waits for the app to go idle, so simple sequences need no waits. It cannot know that a network response or an animation after that point will change the screen, so assertions about content that appears later need an explicit wait. waitForExistence(timeout:) returns false rather than failing when time runs out, so wrap it in XCTAssertTrue; waitForNonExistence(timeout:) covers spinners and dismissed sheets; and wait(for:toEqual:timeout:) waits for a property such as value or isEnabled to reach a given state. Fixed sleeps are never needed and always cost time.

Apple now documents the UI automation types, XCUIApplication, XCUIElement, XCUIElementQuery, XCUIDevice and the rest, in a framework called XCUIAutomation, available from Xcode 16.3, while XCTest provides the test cases, assertions and runner. Both XCUIApplication and XCUIElement are main-actor classes, which is why Xcode’s templates mark UI test methods @MainActor. Swift Testing, introduced with Xcode 16, is Apple’s recommended framework for new unit tests, but Apple’s documentation is explicit that UI tests and performance tests continue to use XCTest. One test target can contain both frameworks, but a single test should not mix their APIs.

Agree a naming scheme for accessibility identifiers, such as screen.element, and set them in the app: accessibilityIdentifier on UIKit views, the .accessibilityIdentifier modifier in SwiftUI. Identifiers are not spoken by VoiceOver, so they can be stable and technical without harming accessibility. In the test target, wrap each screen in a small type that holds its queries and exposes user-level actions, and return the next screen from actions that navigate. Tests then read as journeys, and an identifier change is fixed in one place. Mark these types @MainActor, because they hold XCUIElement values.

Because the test runs in another process, it cannot reset a database or swap a network client directly. The supported channel is launchArguments and launchEnvironment on XCUIApplication, read by the app at start-up through ProcessInfo. Use them to point the app at a stub server or local fixtures, start from a clean or seeded state, skip onboarding and switch off animations. Keep the test hooks behind a single check in the app so they cannot leak into release behaviour, and launch a fresh app in each test so no state carries over.

Split the job into build-for-testing and test-without-building, so the compile step is cached or reused and test retries do not rebuild. Name the destination exactly, including the simulator runtime, because hosted macOS images ship a fixed set of runtimes and devices. On GitHub’s macos-26 image, Xcode 26.6 is the default and Xcode 27 is offered as a preview image under a separate runner label, so pin the Xcode path. Write a result bundle and upload it when the job fails; it holds screenshots, logs and the timeline. Keep retries on for CI only, and review any test that needed one.

System alerts belong to the system, not your app, and a prompt that appears mid-test blocks the next tap. There are three ways to keep them under control. Put the app in a known authorisation state before launch with resetAuthorizationStatus(for:), so the prompt appears exactly when the test expects it, then tap the alert’s button through the system UI. Register addUIInterruptionMonitor handlers for prompts that may or may not appear; XCTest calls them when an unexpected alert blocks an interaction. And for journeys that leave the app, such as changing a setting, create an XCUIApplication with that app’s bundle identifier, act there, then activate your app again.

Use test plans to separate a fast smoke set from the full regression run and to repeat tests across configurations, for example English and Arabic, or a stubbed and a staging environment through environment variables. xcodebuild selects a plan with -testPlan and lists them with -showTestPlans. Xcode 27 adds a test plan setting for how a crash of the target app during UI testing is treated, from off to fatal failure, which is worth setting deliberately rather than leaving at the default failure. When a test fails, open the .xcresult bundle first: the timeline shows each query, the screenshot at failure and the hierarchy XCTest saw. For intermittent failures, rerun the single test with -test-iterations and -run-tests-until-failure before changing any waits.