Skip to content

Overview

✅ Implemented 🧪 Tested 📱 Simulator Only

See the Status Glossary for chip definitions.

AutoMobile iOS automation uses native XCTest APIs for both observations and touch injection. The XCTestService provides a WebSocket server that exposes XCUITest capabilities, while simctl handles simulator lifecycle management.

flowchart TB
    subgraph "MCP Client"
        Agent[AI Agent]
    end

    subgraph "TypeScript MCP Server (macOS)"
        MCP[MCP Server]
        WSClient[WebSocket Client]
        Simctl[simctl]
    end

    subgraph "iOS Simulator/Device"
        XCTestService[XCTestService]
        SimApp[YourAwesome.app]
    end

    Agent -->|MCP Protocol| MCP
    Xcode[AutoMobile Xcode Integration] -->|MCP Protocol + Unix socket| MCP
    MCP --> WSClient
    MCP --> Simctl
    WSClient -->|ws://localhost:8765| XCTestService
    Simctl -->|simulator lifecycle| SimApp
    XCTestService -->|XCUITest APIs| SimApp

Components

Component Description Status
XCTestService WebSocket server using native XCUITest APIs for element location and touch injection. ✅ Implemented 🧪 Tested 📱 Simulator Only
XCTestRunner Test execution framework (plan execution, test ordering, retries). ✅ Implemented 🧪 Tested
simctl integration Simulator lifecycle and app management. ✅ Implemented 🧪 Tested
Managed App Configuration MDM policies and app config payloads. 🚧 Design Only
Managed Apple IDs Account policies and device profiles. 🚧 Design Only
Xcode integration Companion macOS app + source editor extension. ⚠️ Partial
Screen Streaming AVFoundation/ScreenCaptureKit live mirroring. 🚧 Design Only

Status

  • XCTestService fully implemented: WebSocket server, XCUITest element location, gesture injection, hierarchy debouncing, FPS monitoring.
  • XCTestRunner fully implemented: AutoMobileTestCase base class, plan execution, retry, test ordering by timing, CI/local modes.
  • Xcode Companion app (macOS): scaffolded with all views; feature completeness ongoing.
  • Xcode Source Editor Extension: scaffolded with 5 registered commands; implementations are minimal stubs.
  • Physical device support tracked in GitHub issues #912, #913, #914.

Parity goal

The iOS toolset should reach feature parity with Android over time. The design prioritizes consistent behavior and comparable UX across platforms, even when the underlying system tooling differs.

System requirements

  • macOS 13.0+ (Ventura or newer).
  • Xcode 15.0+ and Command Line Tools.

Limitations

  • macOS required (Xcode and iOS Simulator).
  • Simulator-only currently; physical device support requires provisioning (see GitHub issues #912-914).
  • Docker is not supported for iOS automation.

See also