development
claude/smbcloud-github-app-k9641p
development
feature/apps
feature/build-release
feature/ci-docs
feature/ci-ruby-gems
feature/cicd
feature/completion
feature/dist-nuget
feature/fix-ci-sdk-pypi-rubygem
feature/fix-clippy-on-stable-channel
feature/fix-deployment-script
feature/github-email
feature/gresiq-v1
feature/project-new-structure
feature/rsync-deploy
feature/ruby-runner
feature/sdk-npm
feature/sdk-workflows
feature/smbcloud-cli-release-npm
feature/smbcloud-deploy
feature/wasm
main
release/v0.7.4
| 1 | --- |
| 2 | title: End-to-End Testing for iOS, tvOS, watchOS, visionOS & macOS |
| 3 | description: xcrs is an open-source Rust MCP server that lets Claude Code, Cursor, and other AI coding agents drive real Xcode simulators and physical Apple devices for end-to-end testing — tap, type, swipe, screenshot, and read the accessibility tree, no cloud required. |
| 4 | --- |
| 5 | |
| 6 | # End-to-end testing for Apple platforms |
| 7 | |
| 8 | **xcrs** is an open-source Rust [MCP](https://modelcontextprotocol.io) server that |
| 9 | gives AI coding agents direct control over Xcode simulators and real Apple |
| 10 | hardware. An agent working in Claude Code, Cursor, or any MCP client can boot a |
| 11 | simulator, install a build, tap through your app, type into fields, read the |
| 12 | accessibility tree, and capture screenshots — the same steps a human QA |
| 13 | engineer would take — to write and run end-to-end tests for **iOS, iPadOS, |
| 14 | tvOS, watchOS, visionOS, and macOS** apps. |
| 15 | |
| 16 | It ships as a standalone binary (`xcrs --mcp`) and as part of the [smbCloud |
| 17 | CLI](/developer/cli) (`smb --mcp`), and it's free: `cargo install xcrs`. |
| 18 | |
| 19 | ## Why agent-driven UI testing needs real device control |
| 20 | |
| 21 | Coding agents can now write and refactor an app faster than a human can |
| 22 | click through it by hand. The gap is verification: most AI-assisted testing |
| 23 | either stops at unit tests, or hands UI verification to a separate cloud |
| 24 | service the agent has to context-switch into. xcrs closes that gap for Apple |
| 25 | platforms specifically — it's a tool call away, in the same MCP session the |
| 26 | agent is already using to write code. |
| 27 | |
| 28 | ## What you can do |
| 29 | |
| 30 | - Boot a simulator, install an `.app`, launch it by bundle ID, and confirm it |
| 31 | started — `smb_ios_app_test` does the whole install-and-launch cycle in |
| 32 | one call |
| 33 | - Drive the UI: tap, type text, swipe, press Home or a tvOS remote button, |
| 34 | and set device orientation |
| 35 | - Read the live accessibility hierarchy or list actionable elements with |
| 36 | their coordinates, so an agent can decide what to tap without guessing |
| 37 | from a screenshot |
| 38 | - Capture PNG screenshots from a simulator or a physical device |
| 39 | - Run the same automation against **real, physical hardware** — iPhone, |
| 40 | iPad, Apple TV, Apple Watch, Apple Vision Pro — not just simulators |
| 41 | - Query what a runner supports before acting, with |
| 42 | `smb_controlkit_capabilities` |
| 43 | |
| 44 | ## How it fits together |
| 45 | |
| 46 | xcrs is two pieces working together: |
| 47 | |
| 48 | | Piece | What it is | |
| 49 | | --- | --- | |
| 50 | | **xcrs** | The Rust CLI and MCP server. Exposes tools like `smb_simulator_tap` and `smb_ios_app_test` to any MCP client, and talks `simctl`/`xcodebuild` directly for simulator lifecycle and app installs. | |
| 51 | | **[ControlKit](https://swiftpackageindex.com/ondeinference/xcrs-controlkit)** | A native XCTest-based Swift runner that runs *on* the simulator or device. It exposes taps, text input, screenshots, and the accessibility tree over a local JSON-RPC server. | |
| 52 | |
| 53 | Because ControlKit drives the UI through Apple's own accessibility and |
| 54 | XCTest APIs — not by inferring taps from a screenshot — the same element the |
| 55 | agent reads back is the one it taps. There's no separate vision model in the |
| 56 | loop translating pixels into coordinates. |
| 57 | |
| 58 | xcrs runs entirely on your Mac. Nothing about the app under test, its |
| 59 | screenshots, or its UI hierarchy leaves your machine unless you choose to |
| 60 | send it somewhere. |
| 61 | |
| 62 | ## Tool reference |
| 63 | |
| 64 | A representative slice of the MCP tools xcrs exposes (`xcrs_` prefix |
| 65 | standalone, `smb_` prefix through the smbCloud CLI): |
| 66 | |
| 67 | | Tool | Purpose | |
| 68 | | --- | --- | |
| 69 | | `smb_ios_app_test` | Install and launch an `.app` on a simulator, and confirm it's running. | |
| 70 | | `smb_simulator_list` / `smb_simulator_find` | Enumerate or locate Apple simulators known to Xcode. | |
| 71 | | `smb_simulator_tap` / `smb_simulator_swipe` / `smb_simulator_type_text` | Drive touch and text input through ControlKit. | |
| 72 | | `smb_simulator_ui_dump` / `smb_simulator_list_elements` | Read the accessibility hierarchy or actionable elements. | |
| 73 | | `smb_simulator_screenshot` / `smb_device_screenshot` | Capture a PNG from a simulator or a physical device. | |
| 74 | | `smb_simulator_press_button` / `smb_simulator_press_home` | Press a Home or tvOS remote button. | |
| 75 | | `smb_simulator_orientation_get` / `smb_simulator_orientation_set` | Read or set device orientation. | |
| 76 | | `smb_macos_click` / `smb_visionos_spatial_tap` / `smb_watchos_tap` | Platform-specific input for macOS, visionOS, and watchOS runners. | |
| 77 | | `smb_controlkit_capabilities` | Read what a runner (simulator, device, or local Mac) supports. | |
| 78 | |
| 79 | The full reference, including physical-device setup, lives in |
| 80 | [Developer → CLI → MCP](/developer/cli/mcp) and |
| 81 | [Developer → CLI → ControlKit](/developer/cli/controlkit). |
| 82 | |
| 83 | ## xcrs compared to cloud-based AI QA platforms |
| 84 | |
| 85 | Most AI-driven testing tools on the market today, such as QA.tech, are |
| 86 | cloud SaaS products: a vision model watches screenshots of your app running |
| 87 | on a hosted device farm, and you connect to it over MCP from your coding |
| 88 | agent. That works, and it isn't limited to Apple platforms. xcrs takes a |
| 89 | narrower, different approach: |
| 90 | |
| 91 | | | xcrs | Typical cloud AI QA platform | |
| 92 | | --- | --- | --- | |
| 93 | | Where it runs | Locally, on your Mac | Hosted device farm | |
| 94 | | How it "sees" the UI | Apple's accessibility tree via XCTest | Vision model reading screenshots | |
| 95 | | Apple platform coverage | iOS, iPadOS, tvOS, watchOS, visionOS, macOS | Usually web and mobile web, sometimes iOS/Android | |
| 96 | | Physical device support | Yes, over the local network | Varies by vendor | |
| 97 | | Pricing | Open source, free | Seat-based / demo-gated | |
| 98 | | Setup | `cargo install xcrs` | Account, hosted environment, demo call | |
| 99 | |
| 100 | If you're already testing across web, Android, and iOS from one dashboard, |
| 101 | a cloud platform's breadth may be the better fit. If you're building for |
| 102 | Apple platforms and want your coding agent to drive a real simulator or |
| 103 | device without leaving your terminal or paying per seat, that's what xcrs |
| 104 | is for. |
| 105 | |
| 106 | ## Frequently asked questions |
| 107 | |
| 108 | **Is xcrs free and open source?** |
| 109 | Yes. xcrs is Apache-2.0 licensed, published on |
| 110 | [crates.io](https://crates.io/crates/xcrs), and its source lives in the |
| 111 | [smbcloud-cli repository](https://github.com/smbcloudXYZ/smbcloud-cli/tree/main/crates/xcrs). |
| 112 | |
| 113 | **Which Apple platforms does it support?** |
| 114 | iOS, iPadOS, tvOS, watchOS, visionOS, and macOS — on simulators and on |
| 115 | physical hardware paired with your Mac. |
| 116 | |
| 117 | **Does it work with Claude Code and Cursor?** |
| 118 | Yes. xcrs is a standard MCP server (`xcrs --mcp`, or `smb --mcp` if you're |
| 119 | using the smbCloud CLI), so it works with any MCP-compatible client, including |
| 120 | Claude Code and Cursor. |
| 121 | |
| 122 | **Can it test on a real iPhone or Apple TV, not just a simulator?** |
| 123 | Yes. The [ControlKit](https://swiftpackageindex.com/ondeinference/xcrs-controlkit) |
| 124 | runner builds and runs on physical devices; `smb_device_screenshot` and the |
| 125 | device-targeted tool calls work over your local network. See |
| 126 | [Developer → CLI → ControlKit](/developer/cli/controlkit) for the setup steps. |
| 127 | |
| 128 | **How is xcrs different from vision-based, cloud-hosted testing tools?** |
| 129 | xcrs drives the UI through Apple's own accessibility APIs and XCTest, run |
| 130 | locally, instead of a hosted vision model inferring taps from screenshots. |
| 131 | That means no screen recordings leave your machine, no per-seat pricing, and |
| 132 | native support for the Apple-only platforms (tvOS, watchOS, visionOS) that |
| 133 | general-purpose web/mobile QA platforms typically don't reach. |
| 134 | |
| 135 | ## Getting started |
| 136 | |
| 137 | 1. Install xcrs — `cargo install xcrs`, or use `smb --mcp` if you already |
| 138 | have the [smbCloud CLI](/developer/cli). |
| 139 | 2. Build and start a [ControlKit](https://swiftpackageindex.com/ondeinference/xcrs-controlkit) |
| 140 | runner for the platform you're testing — see |
| 141 | [Developer → CLI → ControlKit](/developer/cli/controlkit). |
| 142 | 3. Point your MCP client at `xcrs --mcp` (or `smb --mcp`) and start driving |
| 143 | the simulator or device from your agent's normal tool calls. |
| 144 | |
| 145 | Full tool schemas and CLI flags are in |
| 146 | [Developer → CLI → MCP](/developer/cli/mcp). |