mirror of
https://github.com/callstack/agent-device.git
synced 2026-09-14 20:06:34 +08:00
Michał Pierzchała
72cae2bc72
* refactor(apple): colocate the XCUITest runner client into packages/platform-apple (#2040) Moves src/platforms/apple/core/runner/ (34 modules + apple-runner-platform.ts and the 30 runner test suites) into packages/platform-apple/src/runner/ — Apple mechanics live in the Apple package. Host capabilities (exec, diagnostics, retry, process probes, locks, Apple tooling, physical-device control) enter through the package-owned AppleRunnerHost port; the root composition module src/platforms/apple/core/runner-client.ts constructs the client exactly once and re-exposes the bound operations under their historical names. R13 admits the transitional state deliberately: the family exports its root façade plus exactly the enumerated ./runner, ./runner/client, and ./runner/test-host subpaths; the ./runner façade subpath is the recorded #1983 seam for unmigrated root consumers; ./runner/client has one composition root and ./runner/test-host one vitest installer; the runner subtree may own its cache files and sockets while raw process primitives stay banned. When #1983 completes, the subpaths and every subtree exemption are deleted and the family returns to a single implementation-lazy façade export. * docs(adr): model the runner subtree as a durable platform-owned facet Review correction on #2050: the sunset story attributed the runner-consumer migration to #1983, which owns snapshot/presentation vocabulary — not the runner's daemon/root consumers — so that event cannot delete the ./runner subpaths or the subtree exemptions. Reword ADR-0019, R13, and the gate comments: the facet is the intended ownership model, its seam is enumerated and pinned (exact export list, one client composition root, one test-host installer, raw-process ban, eager-closure pins), and the seam narrows only if a real runner-consumer migration retires the direct consumers. The declaration mechanism stays apple-specific until another family needs a mechanics facet. No behavior change; identifiers and comments only.
57 lines
3.1 KiB
Markdown
57 lines
3.1 KiB
Markdown
# agent-device iOS Runner
|
|
|
|
This folder contains the lightweight XCUITest runner used to provide element-level automation for Apple-family targets.
|
|
|
|
## Intent
|
|
|
|
- Provide a minimal XCTest target that exposes UI automation over a small HTTP server.
|
|
- Allow local builds via `xcodebuild` and caching for faster subsequent runs.
|
|
- Support simulator prebuilds where compatible.
|
|
|
|
## Status
|
|
|
|
Current internal runner for iOS, tvOS, and macOS desktop automation.
|
|
|
|
Protocol and maintenance references:
|
|
|
|
- Protocol overview: [`RUNNER_PROTOCOL.md`](RUNNER_PROTOCOL.md)
|
|
- TypeScript client: [`../../packages/platform-apple/src/runner/runner-client.ts`](../../packages/platform-apple/src/runner/runner-client.ts)
|
|
- Swift wire models: [`AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift)
|
|
|
|
## UITest Runner File Map
|
|
|
|
`AgentDeviceRunnerUITests/RunnerTests` is split into focused files to reduce context size for contributors and LLM agents.
|
|
|
|
- `RunnerTests.swift`: shared state/constants, `setUp()`, and `testCommand()` entry flow.
|
|
- `RunnerTests+Models.swift`: wire protocol models (`Command`, `Response`, snapshot payload models).
|
|
- `RunnerTests+Environment.swift`: environment and CLI argument helpers (`RunnerEnv`).
|
|
- `RunnerTests+Transport.swift`: TCP request handling and HTTP parsing/encoding.
|
|
- `RunnerTests+CommandExecution.swift`: command dispatch (`execute*`) and command switch.
|
|
- `RunnerTests+Lifecycle.swift`: activation/retry/stabilization and recording lifecycle helpers.
|
|
- `RunnerTests+Interaction.swift`: tap/drag/swipe/type/home/rotate/app-switcher helpers.
|
|
- `RunnerTests+Navigation.swift`: back/navigation-control helpers.
|
|
- `RunnerTests+Snapshot.swift`: fast/raw snapshot builders and include/filter helpers.
|
|
- `RunnerTests+SystemModal.swift`: SpringBoard/system modal detection and modal snapshot shaping.
|
|
- `RunnerTests+ScreenRecorder.swift`: nested `ScreenRecorder` implementation.
|
|
|
|
## Snapshot Strategy
|
|
|
|
iOS snapshots have two explicit public capture modes:
|
|
|
|
- full/raw snapshots use recursive XCTest snapshots for rich hierarchy and diagnostics;
|
|
- interactive snapshots filter the same visible tree down to agent-facing refs.
|
|
|
|
Some iOS apps expose accessibility trees that lower-level AX services can inspect but XCTest cannot
|
|
serialize reliably. In those cases interactive snapshots may return a sparse root quickly, while
|
|
full snapshots preserve the XCTest error. A penalized simulator can recover through private AX;
|
|
physical devices use a short XCTest probe because no non-XCTest semantic backend is available
|
|
there. See
|
|
[`../../docs/adr/0004-ios-snapshot-backend-strategy.md`](../../docs/adr/0004-ios-snapshot-backend-strategy.md)
|
|
for the backend boundary and future simulator AX-service direction.
|
|
|
|
## Protocol Notes
|
|
|
|
- The daemon posts JSON commands to `POST /command` on the runner's local HTTP listener.
|
|
- The runner responds with a JSON envelope shaped as `{ ok, data?, error? }`.
|
|
- The protocol is internal to `agent-device`; when adding or renaming commands, update both wire models and the protocol tests/docs in the same change.
|