xcuitest-suite

Overview

XCUITest is Apple's first-party UI testing framework, integrated with Xcode and built on the XCTest framework (xcui-fundamentals).

"UI testing in Xcode is built on three fundamental classes: XCUIApplication, XCUIElement, XCUIElementQuery." (xcui-fundamentals)

The general pattern: Query → Synthesize → Assert.

"1. Query - Use XCUIElementQuery to find an XCUIElement 2. Synthesize - Synthesize an event and send it to the XCUIElement 3. Assert - Use an assertion to compare the element's state against expected reference state" (xcui-fundamentals)

When to use

• An iOS app needs UI tests using Apple's native framework.
• A team prefers no external runtime (Appium, Detox) and wants Xcode-native test integration.
• The app is iOS-only and there's no need for cross-platform reuse.

If the app is React Native, see detox-testing. For cross-platform Appium-style coverage, see appium-testing.

macOS desktop apps

The same framework tests macOS desktop apps (AppKit, SwiftUI, Catalyst) - every step below carries over. The macOS delta - -destination 'platform=macOS' flags, TCC privacy-permission resets (tccutil reset), per-device performance baselines, and headless-runner constraints - is in references/macos.md.

Step 1 - Add a UI test target

In Xcode: File → New → Target → UI Testing Bundle. The template generates a .swift test class with a default setUp:

import XCTest

final class CartUITests: XCTestCase {
    override func setUpWithError() throws {
        continueAfterFailure = false   // critical (default)
        XCUIApplication().launch()
    }
}

Per xcui-fundamentals:

"continueAfterFailure = NO is the default (recommended) because UI test steps are dependent on previous steps."

Step 2 - Set accessibility identifiers in production code

XCUITest finds elements via the accessibility tree. Hard-coded labels / text are brittle - set explicit identifiers in the SUT:

// Production code
let placeOrderButton = UIButton()
placeOrderButton.accessibilityIdentifier = "place-order-button"

Then in tests:

let app = XCUIApplication()
app.buttons["place-order-button"].tap()

accessibilityIdentifier (not accessibilityLabel) - labels are user-facing and translated; identifiers are dev-only and stable.

Step 3 - Query patterns

let app = XCUIApplication()

// By accessibility identifier (preferred)
app.buttons["place-order-button"].tap()
app.textFields["email-field"].typeText("user@example.com")

// By type + text
app.staticTexts["Welcome"].swipeUp()

// Predicate-based query
let cells = app.tables.cells.matching(
    NSPredicate(format: "label CONTAINS[c] 'BOOK-001'")
)
cells.element(boundBy: 0).tap()

// Wait for an element
XCTAssert(app.staticTexts["Order confirmed"].waitForExistence(timeout: 5))

Step 4 - Synthesize events

// Tap
app.buttons["submit"].tap()

// Type
app.textFields["email"].typeText("user@example.com")

// Swipe / drag
app.cells.element(boundBy: 0).swipeLeft()

// Pinch
app.images["map"].pinch(withScale: 2.0, velocity: 1.0)

// Press for duration (long-press)
app.buttons["context-menu"].press(forDuration: 1.0)

// System keyboard return
app.keyboards.buttons["return"].tap()

Step 5 - Assert state

let confirmation = app.staticTexts["Order confirmed"]
XCTAssertTrue(confirmation.exists)

XCTAssertEqual(app.staticTexts["order-id"].label, "ORD-12345")

XCTAssertTrue(app.buttons["submit"].isEnabled)

exists returns immediately; waitForExistence(timeout:) waits up to N seconds. Use waitForExistence for any post-tap state that depends on async work.

Step 6 - Run

# From the project directory:
xcodebuild test \
  -project MyApp.xcodeproj \
  -scheme MyApp \
  -destination 'platform=iOS Simulator,name=iPhone 15,OS=latest' \
  -resultBundlePath TestResults.xcresult

Per-destination patterns:

Use	Destination string
Latest sim	'platform=iOS Simulator,name=iPhone 15,OS=latest'
Specific OS	'platform=iOS Simulator,name=iPhone 14,OS=17.4'
Connected device	'platform=iOS,id=<UDID>'
Multi-device matrix	Pass -destination multiple times.

Step 7 - Parse .xcresult

The result bundle is binary. Extract via xcresulttool:

xcrun xcresulttool get test-results summary --path TestResults.xcresult --format json > results.json

Then use junit-xml-analysis (in the qa-test-reporting plugin) on the JUnit-equivalent shape (or directly on the JSON for richer data).

Step 8 - CI integration

# .github/workflows/ios-tests.yml
jobs:
  ui-tests:
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v5
      - run: xcodebuild test -project MyApp.xcodeproj -scheme MyApp \
              -destination 'platform=iOS Simulator,name=iPhone 15,OS=latest' \
              -resultBundlePath TestResults.xcresult
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: xcresult
          path: TestResults.xcresult

GitHub Actions provides macos-15 runners with Xcode pre-installed.

Anti-patterns

Anti-pattern	Why it fails	Fix
Querying by accessibilityLabel	Labels are translated; tests fail in non-English locales.	Use accessibilityIdentifier (Step 2-3).
Thread.sleep for async waits	Flaky on slow runners; slow on fast.	waitForExistence(timeout:) (Step 5).
continueAfterFailure = true	One failure cascades into N false positives.	Default false (Step 1).
Hard-coded text in queries	Copy changes break tests.	accessibility identifiers (Step 2).
Running against wrong destination ("latest" without pin)	Test passes on Xcode 16, fails on 15; reproducibility issues.	Pin OS version explicitly in CI.
Skipping xcresult upload	Failure debugging needs the screenshots / videos in the bundle.	Always upload (Step 8).

Limitations

• macOS only. Xcode + Simulator require macOS hosts.
• Slower than unit tests. Each test launches the app; expect 10-30s per test. Keep UI test count modest.
• Flaky on Simulator under load. CI runners under contention produce intermittent failures; use retries cautiously (don't mask real bugs).
• No first-party visual regression. Pair with percy-visual-regression-testing (in the qa-visual-regression plugin) or screenshot-comparison helpers.

References

• xcui - Apple's XCUITest fundamentals: three-class pattern (XCUIApplication / XCUIElement / XCUIElementQuery), Query→Synthesize→Assert, continueAfterFailure = NO default.
• references/macos.md - the macOS desktop delta (destination flags, TCC permissions, CI, per-device baselines).
• espresso-suite - Android sibling.
• appium-testing - cross-platform alternative when iOS + Android share tests.
• junit-xml-analysis - downstream parser for JUnit-converted xcresult.