mirror of
https://github.com/callstack/agent-device.git
synced 2026-09-14 20:06:34 +08:00
Michał Pierzchała
3df1e145b4
Post-#968 follow-up: the OS-agnostic Apple runner engine moved from
src/platforms/ios/ to src/platforms/apple/core/, but several docs/config still
pointed at the old locations, misleading agents that grep those paths.
- AGENTS.md: repoint the runner-seam map, the Apple-family sync rule, the
record/trace seam, the search-roots hint, and the platform-backends list at
src/platforms/apple/core/...; rename "iOS Runner Seams" -> "Apple Runner Seams".
- .fallowrc.json: drop the two stale ignoreExports entries for the removed
src/platforms/ios/apps.ts and src/platforms/ios/index.ts (the live
src/platforms/apple/core/apps.ts entry already covers those test-only exports).
- ios-runner/{README,RUNNER_PROTOCOL}.md: point the TypeScript-client links at
src/platforms/apple/core/runner/runner-client.ts.
Docs/config only; no behavior change. fallow audit + build/lint stay green, and a
live iOS simulator replay suite (6/6) confirms the consolidated runner works.
54 lines
2.8 KiB
Markdown
54 lines
2.8 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: [`../src/platforms/apple/core/runner/runner-client.ts`](../src/platforms/apple/core/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/back/home/rotate/app-switcher 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 simulator 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. 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.
|