6 files changed
+155
-13
docs/controlkit.md
+5
@@ -143,3 +143,8 @@ instead:
143
Platform-specific operations intentionally reject unsupported input. For
144
example, visionOS rejects raw touch, watchOS rejects pointer and spatial input,
145
and macOS rejects touch and Home-button requests.
146
+
147
+## See also
148
+
149
+For the product-level overview of end-to-end testing with xcrs and
150
+ControlKit, see [smbcloud.xyz/xcrs-end-to-end-testing](https://smbcloud.xyz/xcrs-end-to-end-testing).
docs/interfaces.md
-5
@@ -50,13 +50,8 @@ dialog under `--tui`; in the headless interface they ask inline instead.
50
51
`smb --mcp` starts an MCP (Model Context Protocol) server that speaks
52
JSON-RPC over stdio. Instead of running a single command and exiting, it stays
53
-<<<<<<< HEAD
53
up and exposes 50 tools spanning accounts, projects, tenants, Mail, Auth,
54
simulators, and ControlKit runners as MCP **tools** that an MCP-capable client
56
-=======
57
-up and exposes smbCloud operations — 31 tools spanning accounts, projects,
58
-tenants, Mail, and Auth — as MCP **tools** that an MCP-capable client
59
->>>>>>> development
55
(Claude Desktop, Claude Code, Cursor, or any other assistant/agent) can call.
56
The subcommand is ignored in this mode.
57
docs/mcp.md
-8
@@ -2,19 +2,11 @@
2
3
The smbCloud CLI can run as a **Model Context Protocol (MCP) server**, so an AI
4
assistant or agent — Claude Desktop, Claude Code, Cursor, or any other
5
-<<<<<<< HEAD
5
MCP-capable client — can manage your smbCloud projects, tenants, Mail apps, and
6
Auth apps directly, without you leaving the chat to run `smb` commands by hand.
7
Start it with `smb --mcp`; it speaks standard MCP over stdio and exposes 50
8
tools covering the account, project, tenant, Mail, Auth, simulator, and
9
ControlKit runner surfaces.
11
-=======
12
-MCP-capable client — can send transactional email and manage your smbCloud
13
-projects, tenants, Mail apps, and Auth apps directly, without you leaving the
14
-chat to run `smb` commands by hand.
15
-Start it with `smb --mcp`; it speaks standard MCP over stdio and exposes 31
16
-tools covering the account, project, tenant, Mail, and Auth surfaces.
17
->>>>>>> development
10
11
This page is the setup guide and the full tool reference. For how `--mcp`
12
compares to the CLI's other two interfaces (headless and `--tui`), see
website/content/_meta.js
+1
@@ -13,6 +13,7 @@ export default {
13
title: 'Developer'
14
},
15
developer: 'Developer',
16
+ 'xcrs-end-to-end-testing': 'XCRS Testing',
17
_more: {
18
type: 'separator',
19
title: 'More'
website/content/developer/index.mdx
+3
@@ -17,6 +17,9 @@ import { Cards } from 'nextra/components'
17
<Cards.Card title="Contributing" href="/developer/contributing" arrow>
18
Build, debug, and release the CLI and its packages.
19
</Cards.Card>
20
+ <Cards.Card title="XCRS Testing" href="/xcrs-end-to-end-testing" arrow>
21
+ Drive Apple simulators and devices from your coding agent for end-to-end tests.
22
+ </Cards.Card>
23
</Cards>
24
25
## How these docs stay current
website/content/xcrs-end-to-end-testing.mdx
new
+146
@@ -0,0 +1,146 @@
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).