writing-xcuitests

This skill should be used when the user asks to "write XCUITest", "create UI tests", "fix flaky tests", "query XCUIElements", "implement Page Object pattern", or mentions XCUITest, UI testing for iOS/macOS apps. Targets experienced iOS developers who want best practices and efficiency improvements.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides expert guidance for iOS and macOS developers to build robust, maintainable XCUITests. It focuses on practical automation strategies, including efficient element querying, implementing the Page Object pattern, and advanced synchronization techniques to eliminate test flakiness and improve CI/CD reliability.

Use Cases

  • Automated UI Testing: Create comprehensive end-to-end test suites for iOS and macOS applications to ensure UI consistency and functional integrity.
  • Flakiness Mitigation: Implement advanced waiting strategies and explicit synchronization to resolve unstable tests and reduce false negatives in build pipelines.
  • Test Code Refactoring: Apply the Page Object pattern to encapsulate screen logic, making test code more readable, reusable, and easier to maintain.
  • Element Query Optimization: Utilize accessibility identifiers and predicates to build stable element queries that are resistant to UI layout changes.
  • Environment Mocking: Configure specific application states for testing by leveraging launch arguments and environment variables within the XCTest framework.
namewriting-xcuitests
descriptionThis skill should be used when the user asks to "write XCUITest", "create UI tests", "fix flaky tests", "query XCUIElements", "implement Page Object pattern", or mentions XCUITest, UI testing for iOS/macOS apps. Targets experienced iOS developers who want best practices and efficiency improvements.

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:

Topic Reference File
Element Query Strategies reference/element-queries.md
Interactions & Gestures reference/interactions.md
Waiting & Synchronization reference/waiting.md
Assertions & Validation reference/assertions.md
Page Object Pattern reference/page-objects.md
Advanced Gestures reference/gestures.md
Fixing Flaky Tests reference/flaky-tests.md
Complete Examples reference/examples.md

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