Writing XCUITests

Guide for writing robust, maintainable XCUITests for iOS and macOS applications. This skill focuses on practical patterns, element querying strategies, and techniques to reduce test flakiness.

Quick Start

Element Queries

Prefer accessibility identifiers for reliable element queries:

// Best: Accessibility identifier
app.buttons["loginButton"].tap()

// Good: Text matching (fragile to localization)
app.buttons["Log In"].tap()

// Avoid: Index-based queries (brittle to UI changes)
app.buttons.element(boundBy: 0).tap()

Set accessibility identifiers in your app code:

button.accessibilityIdentifier = "loginButton"

Query by element type and identifier:

let emailField = app.textFields["emailField"]
let passwordField = app.secureTextFields["passwordField"]
let submitButton = app.buttons["submitButton"]
let statusLabel = app.staticTexts["statusLabel"]

Common Interactions

Tap elements:

app.buttons["submitButton"].tap()

Type text:

app.textFields["emailField"].tap()
app.textFields["emailField"].typeText("user@example.com")

Clear and type (preferred for input fields):

let emailField = app.textFields["emailField"]
emailField.tap()
// Clear existing text by typing delete keys
if let value = emailField.value as? String, !value.isEmpty {
    let deleteString = String(repeating: XCUIKeyboardKey.delete.rawValue,
                              count: value.count)
    emailField.typeText(deleteString)
}
emailField.typeText("new@example.com")

Toggle switches:

let toggleSwitch = app.switches["notificationSwitch"]
if toggleSwitch.value as? String == "0" {
    toggleSwitch.tap()
}

Waiting for Elements

Always wait for elements before interacting:

let loginButton = app.buttons["loginButton"]
XCTAssertTrue(loginButton.waitForExistence(timeout: 5))
loginButton.tap()

Wait for element to disappear (loading indicators):

// Using expectation-based wait for disappearance
let spinner = app.activityIndicators["loadingSpinner"]
let predicate = NSPredicate(format: "exists == false")
let expectation = expectation(for: predicate, evaluatedWith: spinner)
wait(for: [expectation], timeout: 10)

Alternative simpler approach:

// Wait for element to disappear (simple polling approach)
let spinner = app.activityIndicators["loadingSpinner"]
let timeout: TimeInterval = 10
let startTime = Date()
while spinner.exists && Date().timeIntervalSince(startTime) < timeout {
    Thread.sleep(forTimeInterval: 0.1)
}
XCTAssertFalse(spinner.exists, "Spinner did not disappear within timeout")

Basic Assertions

Check element existence:

XCTAssertTrue(app.buttons["loginButton"].exists)

Check element properties:

let errorLabel = app.staticTexts["errorLabel"]
XCTAssertTrue(errorLabel.exists)
XCTAssertEqual(errorLabel.label, "Invalid credentials")

Check element state:

let submitButton = app.buttons["submitButton"]
XCTAssertTrue(submitButton.isEnabled)
XCTAssertTrue(submitButton.isHittable)

Test Structure

Basic XCTestCase Setup

import XCTest

class LoginTests: XCTestCase {
    var app: XCUIApplication!

    override func setUpWithError() throws {
        continueAfterFailure = false
        app = XCUIApplication()
        app.launch()
    }

    override func tearDownWithError() throws {
        app = nil
    }

    func testSuccessfulLogin() throws {
        // Arrange
        let emailField = app.textFields["emailField"]
        let passwordField = app.secureTextFields["passwordField"]
        let loginButton = app.buttons["loginButton"]

        // Act
        XCTAssertTrue(emailField.waitForExistence(timeout: 5))
        emailField.tap()
        emailField.typeText("user@example.com")

        passwordField.tap()
        passwordField.typeText("password123")

        loginButton.tap()

        // Assert
        let welcomeLabel = app.staticTexts["welcomeLabel"]
        XCTAssertTrue(welcomeLabel.waitForExistence(timeout: 5))
        XCTAssertEqual(welcomeLabel.label, "Welcome back!")
    }
}

Launch Arguments and Environment Variables

Configure app state for testing:

override func setUpWithError() throws {
    continueAfterFailure = false
    app = XCUIApplication()

    // Pass launch arguments
    app.launchArguments = ["--uitesting", "--reset-data"]

    // Set environment variables
    app.launchEnvironment = [
        "MOCK_API": "true",
        "ANIMATION_SPEED": "0"
    ]

    app.launch()
}

Reference Documentation

For detailed guidance on specific topics:

Key Principles

1. Use accessibility identifiers - Most reliable query method
2. Always wait for elements - Use waitForExistence(timeout:) before interactions
3. Test behavior, not implementation - Focus on user-visible outcomes
4. Keep tests independent - Each test should run in isolation
5. Use Page Objects - Encapsulate screen structure and reduce duplication
6. Minimize sleeps - Prefer explicit waits over sleep() calls
7. Handle animations - Disable or account for UI animations in tests
8. Verify preconditions - Assert element state before interactions

Common Patterns

Login flow:

func login(email: String, password: String) {
    let emailField = app.textFields["emailField"]
    let passwordField = app.secureTextFields["passwordField"]
    let loginButton = app.buttons["loginButton"]

    XCTAssertTrue(emailField.waitForExistence(timeout: 5))

    emailField.tap()
    emailField.typeText(email)

    passwordField.tap()
    passwordField.typeText(password)

    loginButton.tap()
}

Navigate and verify:

func testNavigationToSettings() {
    // Navigate
    app.tabBars.buttons["Settings"].tap()

    // Verify arrival
    let settingsTitle = app.navigationBars["Settings"]
    XCTAssertTrue(settingsTitle.waitForExistence(timeout: 3))
}

Form submission with validation:

func testFormValidation() {
    let nameField = app.textFields["nameField"]
    let submitButton = app.buttons["submitButton"]

    // Submit empty form
    submitButton.tap()

    // Verify validation message
    let errorLabel = app.staticTexts["nameErrorLabel"]
    XCTAssertTrue(errorLabel.waitForExistence(timeout: 2))
    XCTAssertEqual(errorLabel.label, "Name is required")

    // Fix and resubmit
    nameField.tap()
    nameField.typeText("John Doe")
    submitButton.tap()

    // Verify error cleared
    XCTAssertFalse(errorLabel.exists)
}

Next Steps

• Implement Page Objects for complex screens: reference/page-objects.md
• Learn advanced gestures (swipe, pinch, rotate): reference/gestures.md
• Debug flaky tests: reference/flaky-tests.md
• Review complete test examples: reference/examples.md