The Apple runner speaks a small internal HTTP+JSON protocol between the TypeScript daemon and the XCUITest host. This protocol is a maintainer document, not part of the public user docs, but it should stay explicit so the TypeScript and Swift sides do not drift.
- Endpoint:
POST /command - Content type:
application/json - Request body: one JSON command object
- Response body: one JSON envelope
The daemon probes http://127.0.0.1:<port>/command for simulator and desktop flows, and can use a tunneled device address for physical iOS/tvOS devices before falling back to localhost.
Every request includes a command field. Additional fields depend on the command family.
Examples:
{ "command": "tap", "x": 120, "y": 240 }{
"command": "snapshot",
"interactiveOnly": true,
"depth": 2,
"scope": "app",
"raw": false,
"customActions": false
}customActions asks the capture to name each merged element's
UIAccessibilityCustomActions in a node's actions array. It pins the
private-AX backend (no other backend can read them) and costs one accessibility
round trip per merged element, so it is opt-in.
The pass is bounded on four axes, and every bound is disclosed through
snapshotQuality.customActions {read, candidates, truncated, blocked} rather
than silently applied:
- at most 12 elements per capture, on-screen first, stopping at the capture
deadline —
read < candidatesmeans the rest were not read; - 1s per element read, so one wedged element cannot consume the capture budget (a timed-out element counts as unread, never as "read, has no actions");
- at most 8 action names per element, each at most 80 characters —
truncatedcounts elements whose list was clipped; - one read in flight at a time. The AX call cannot be cancelled once issued, so
the deadline frees only the caller; the call itself keeps running. All reads
therefore share one serial queue, and while an abandoned read is still
outstanding the pass is skipped outright (
blocked) instead of queueing behind it — repeating the capture adds no work. Reads resume on their own once the hung call returns.
{ "command": "recordStart", "outPath": "/tmp/demo.mp4", "fps": 30 }{ "command": "rotate", "orientation": "landscape-left" }The current command names and per-command traits are defined in:
RunnerCommandin../../packages/platform-apple/src/runner/runner-contract.tsRUNNER_COMMAND_TRAITSin../../packages/platform-apple/src/runner/runner-command-traits.tsCommandTypeinAgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
Successful and failed responses use the same top-level envelope:
{
"ok": true,
"data": {
"message": "ok"
}
}{
"ok": false,
"error": {
"code": "UNSUPPORTED_OPERATION",
"message": "Unable to dismiss the iOS keyboard: the keyboard exposes no dismiss key (background taps are never attempted)"
}
}data is command-specific. Common fields include snapshot nodes, text lookup results, gesture timing, visibility metadata, and screenshot or recording output details.
- Treat the TypeScript and Swift wire models as a single contract.
- When adding, removing, or renaming a command, update the protocol fixtures/tests in the same change.
- Keep this file focused on the actual wire shape rather than implementation details of command execution.
These behaviors are owned by code. This section only says where each one is declared; read the declaration for the current rules.
- Command ids and
statusrecovery. The daemon attaches acommandIdwithwithRunnerCommandId(runner-contract.ts). The runner records commands inRunnerCommandJournal(RunnerTests+CommandJournal.swift) and answers thestatuscommand inexecuteStatus(RunnerTests+CommandDispatch.swift). The daemon's recovery decisions live inrunner-command-recovery.ts. runnerMainThreadBusy. The runner stamps successful responses withstampingCurrentMainThreadBusy(RunnerTests+Models.swift) fromcurrentMainThreadBusyState()(RunnerTests+MainThreadWork.swift), applied injsonResponse(RunnerTests+Transport.swift). The daemon reads the stamp inrunner-session.ts.runnerFatal. A field of the response data (runnerFatalinRunnerTests+Models.swift); for example, a sparse snapshot payload inRunnerTests+Snapshot.swiftsets it. The daemon reads it inresolveRunnerFatalReason(runner-session.ts).- Runner error codes (for example
RUNNER_BUSY,RUNNER_WEDGED,MAIN_THREAD_TIMEOUT). On the runner side, wire codes are declared inRunnerWireErrorCode(RunnerTests.swift);RUNNER_BUSYandRUNNER_WEDGEDcome from the busy gate inRunnerTests+CommandDispatch.swift, andMAIN_THREAD_TIMEOUTfrom the main-thread watchdog inRunnerTests+Transport.swift. The daemon classifies a runner-reported code inclassifyRunnerReportedError(runner-contract.ts): codes listed inDIAGNOSTIC_ONLY_RUNNER_ERROR_CODESarrive asCOMMAND_FAILEDwithdetails.runnerErrorCode, and other codes pass through as typed codes. How the daemon reacts to a failure (retry, resend, session-fatal) is declared inRUNNER_ERROR_RULESand the helpers beside it (runner-error-classification.ts).