Skip to content

Latest commit

 

History

History
131 lines (105 loc) · 6.68 KB

RUNNER_PROTOCOL.md

File metadata and controls

131 lines (105 loc) · 6.68 KB

iOS Runner Protocol

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.

Transport

  • 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.

Request Shape

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 < candidates means 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 — truncated counts 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:

Response Shape

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.

Maintenance Rules

  • 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.

Recovery, Busy State, and Error Codes

These behaviors are owned by code. This section only says where each one is declared; read the declaration for the current rules.