kurko/axiom-ui-recording

Recording UI Automation (Xcode 26+)

Guide to Xcode 26's Recording UI Automation feature for creating UI tests through user interaction recording.

The Three-Phase Workflow

From WWDC 2025-344:

┌─────────────────────────────────────────────────────────────┐
│                   UI Automation Workflow                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. RECORD ──────► Interact with app in Simulator           │
│                    Xcode captures as Swift test code        │
│                                                             │
│  2. REPLAY ──────► Run across devices, languages, configs   │
│                    Using test plans for multi-config        │
│                                                             │
│  3. REVIEW ──────► Watch video recordings in test report    │
│                    Analyze failures with screenshots        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Phase 1: Recording

Starting a Recording

1. Open your UI test file in Xcode
2. Place cursor inside a test method
3. Debug → Record UI Automation (or use the record button)
4. App launches in Simulator
5. Perform interactions - Xcode generates code
6. Stop recording when done

What Gets Recorded

• Taps on buttons, cells, controls
• Text input into text fields
• Swipes and scrolling
• Gestures (pinch, rotate)
• Hardware button presses (Home, volume)

Generated Code Example

// Xcode generates this from your interactions
func testLoginFlow() {
    let app = XCUIApplication()
    app.launch()

    // Recorded: Tap email field, type email
    app.textFields["Email"].tap()
    app.textFields["Email"].typeText("[email protected]")

    // Recorded: Tap password field, type password
    app.secureTextFields["Password"].tap()
    app.secureTextFields["Password"].typeText("password123")

    // Recorded: Tap login button
    app.buttons["Login"].tap()
}

Enhancing Recorded Code

Critical: Recorded code is often fragile. Always enhance it for stability.

1. Add Accessibility Identifiers

Recorded code uses labels which break with localization:

// RECORDED (fragile - breaks with localization)
app.buttons["Login"].tap()

// ENHANCED (stable - uses identifier)
app.buttons["loginButton"].tap()

Add identifiers in your app code:

// SwiftUI
Button("Login") { ... }
    .accessibilityIdentifier("loginButton")

// UIKit
loginButton.accessibilityIdentifier = "loginButton"

2. Add waitForExistence

Recorded code assumes elements exist immediately:

// RECORDED (may fail if app is slow)
app.buttons["Login"].tap()

// ENHANCED (waits for element)
let loginButton = app.buttons["loginButton"]
XCTAssertTrue(loginButton.waitForExistence(timeout: 5))
loginButton.tap()

3. Add Assertions

Recorded code just performs actions without verification:

// RECORDED (no verification)
app.buttons["Login"].tap()

// ENHANCED (with assertion)
app.buttons["loginButton"].tap()
let welcomeLabel = app.staticTexts["welcomeLabel"]
XCTAssertTrue(welcomeLabel.waitForExistence(timeout: 10),
              "Welcome screen should appear after login")

4. Use Shorter Queries

Recorded code may have overly specific queries:

// RECORDED (too specific)
app.tables.cells.element(boundBy: 0).buttons["Action"].tap()

// ENHANCED (simpler)
app.buttons["actionButton"].tap()

Query Selection Guidelines

From WWDC 2025-344:

| Scenario | Problem | Solution | |----------|---------|----------| | Localized strings | "Login" changes by language | Use accessibilityIdentifier | | Deeply nested views | Long query chains break easily | Use shortest possible query | | Dynamic content | Cell content changes | Use identifier or generic query | | Multiple matches | Query returns many elements | Add unique identifier |

Best Practices

1. Prefer identifiers over labels
2. Use the shortest query that works
3. Avoid index-based queries (element(boundBy: 0))
4. Add identifiers to dynamic content

Phase 2: Replay with Test Plans

Test plans allow running the same tests across multiple configurations.

Creating a Test Plan

1. File → New → File → Test Plan
2. Add test targets
3. Configure configurations

Test Plan Structure

{
  "configurations": [
    {
      "name": "iPhone - English",
      "options": {
        "targetForVariableExpansion": {
          "containerPath": "container:MyApp.xcodeproj",
          "identifier": "MyApp"
        },
        "language": "en",
        "region": "US"
      }
    },
    {
      "name": "iPhone - Spanish",
      "options": {
        "language": "es",
        "region": "ES"
      }
    },
    {
      "name": "iPhone - Dark Mode",
      "options": {
        "userInterfaceStyle": "dark"
      }
    },
    {
      "name": "iPad - Landscape",
      "options": {
        "defaultTestExecutionTimeAllowance": 120,
        "testTimeoutsEnabled": true
      }
    }
  ],
  "defaultOptions": {
    "targetForVariableExpansion": {
      "containerPath": "container:MyApp.xcodeproj",
      "identifier": "MyApp"
    }
  },
  "testTargets": [
    {
      "target": {
        "containerPath": "container:MyApp.xcodeproj",
        "identifier": "MyAppUITests",
        "name": "MyAppUITests"
      }
    }
  ],
  "version": 1
}

Configuration Options

| Option | Purpose | |--------|---------| | language | Test localization | | region | Test regional formatting | | userInterfaceStyle | Test dark/light mode | | targetForVariableExpansion | App target for configuration | | testTimeoutsEnabled | Enable timeout enforcement | | defaultTestExecutionTimeAllowance | Timeout in seconds |

Running with Test Plan

# Command line
xcodebuild test \
  -scheme "MyApp" \
  -testPlan "MyTestPlan" \
  -destination "platform=iOS Simulator,name=iPhone 16" \
  -resultBundlePath /tmp/results.xcresult

# In Xcode
# Product → Test Plan → Select your plan
# Then Cmd+U to run tests

Phase 3: Review

Test Report Features

After tests complete:

1. View test results in Report Navigator
2. Watch video recordings of each test
3. See screenshots at failure points
4. Analyze timeline of actions

Enabling Attachments

In test plan or scheme:

"options": {
  "systemAttachmentLifetime": "keepAlways",
  "userAttachmentLifetime": "keepAlways"
}

Capturing Custom Screenshots

func testCheckout() {
    // ... actions ...

    // Manual screenshot at specific point
    let screenshot = app.screenshot()
    let attachment = XCTAttachment(screenshot: screenshot)
    attachment.name = "Checkout Confirmation"
    attachment.lifetime = .keepAlways
    add(attachment)
}

Common Patterns

Login Flow Template

func testLoginWithValidCredentials() throws {
    let app = XCUIApplication()
    app.launch()

    // Navigate to login
    let showLoginButton = app.buttons["showLoginButton"]
    XCTAssertTrue(showLoginButton.waitForExistence(timeout: 5))
    showLoginButton.tap()

    // Enter credentials
    let emailField = app.textFields["emailTextField"]
    XCTAssertTrue(emailField.waitForExistence(timeout: 5))
    emailField.tap()
    emailField.typeText("[email protected]")

    let passwordField = app.secureTextFields["passwordTextField"]
    passwordField.tap()
    passwordField.typeText("password123")

    // Submit
    app.buttons["loginButton"].tap()

    // Verify success
    let welcomeScreen = app.staticTexts["welcomeLabel"]
    XCTAssertTrue(welcomeScreen.waitForExistence(timeout: 10))
}

Navigation Flow Template

func testNavigateToSettings() throws {
    let app = XCUIApplication()
    app.launch()

    // Open tab bar item
    app.tabBars.buttons["Settings"].tap()

    // Verify navigation
    let settingsTitle = app.navigationBars["Settings"]
    XCTAssertTrue(settingsTitle.waitForExistence(timeout: 5))

    // Navigate deeper
    app.tables.cells["Account"].tap()
    XCTAssertTrue(app.navigationBars["Account"].exists)
}

Form Validation Template

func testFormValidation() throws {
    let app = XCUIApplication()
    app.launch()

    // Submit empty form
    app.buttons["submitButton"].tap()

    // Verify error appears
    let errorAlert = app.alerts["Error"]
    XCTAssertTrue(errorAlert.waitForExistence(timeout: 5))
    XCTAssertTrue(errorAlert.staticTexts["Please fill all fields"].exists)

    // Dismiss alert
    errorAlert.buttons["OK"].tap()
}

Troubleshooting

Recording Doesn't Start

1. Ensure you're in a test method
2. Check simulator is available
3. Verify app builds and runs
4. Try restarting Xcode

Recorded Code Doesn't Work

1. Add waitForExistence before interactions
2. Check accessibility identifiers are set
3. Simplify queries to shortest form
4. Run app manually to verify flow works

Tests Pass Locally, Fail in CI

1. Increase timeouts for slower CI machines
2. Add explicit waits for animations
3. Check simulator configuration matches
4. Disable animations in test setup:

   app.launchArguments = ["--disable-animations"]
   

Anti-Patterns

Don't Use Raw Recorded Code in CI

// BAD - Raw recorded code
app.buttons["Login"].tap()
app.textFields["Email"].typeText("[email protected]")

// GOOD - Enhanced for CI
let loginButton = app.buttons["loginButton"]
XCTAssertTrue(loginButton.waitForExistence(timeout: 10))
loginButton.tap()

Don't Hardcode Coordinates

// BAD - Coordinates from recording
app.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5)).tap()

// GOOD - Use element queries
app.buttons["centerButton"].tap()

Don't Skip Assertions

// BAD - Actions only
app.buttons["Login"].tap()
sleep(2)  // Hope it works

// GOOD - Verify outcomes
app.buttons["loginButton"].tap()
XCTAssertTrue(app.staticTexts["Welcome"].waitForExistence(timeout: 10))

Resources

WWDC: 2025-344, 2024-10206, 2019-413

Docs: /xcode/testing/recording-ui-tests, /xctest/xcuiapplication

Skills: axiom-xctest-automation, axiom-ui-testing