Run Agent Device

run-agent-device — iOS product testing

Drive the installed agent-device CLI as a serial REPL against an iOS simulator or device: run one command, read its full output, decide the next command from what it actually said. You are testing a product, not just a screen — most "UI bugs" you will find live in another layer (dev server, app code, backend, environment), and this skill's job is to keep you from fixing the wrong one.

Not this skill: Android-first device control (use mobilerun-control), web/browser automation (use run-agent-browser), authoring XCTest/unit tests, or App Store release operations. agent-device can drive Android and web, but this skill's guidance is iOS-product-testing shaped.

Authority order — the CLI's help wins

agent-device ships version-matched instructions. When syntax or behavior is uncertain, ask the tool, not your memory:

agent-device --help                # command list + agent quickstart
agent-device help workflow         # full operating reference (the big one)
agent-device <command> --help      # exact flags for one command
agent-device --version

Route by task before starting:

If this file ever conflicts with the installed CLI's current help, the CLI wins; fix this skill afterward.

Full annotated command surface (all 65 subcommands, grouped, with when-to-use): references/command-map.md. Read it once per session instead of running --help per command.

Session start

agent-device devices --platform ios          # pick target; --device "iPhone 17 Pro" only if several
agent-device open <AppName-or-bundle-id> --platform ios
agent-device snapshot -i                     # interactive refs for the first action

• open without --relaunch foregrounds an already-running app without restarting it. Use --relaunch when the test needs fresh process state ("start from the home screen").
• Unknown app id → agent-device apps, then open the discovered id. Never invent bundle ids or open artifact paths.
• Run doctor only when something fails or the user asks for setup diagnostics — it is not routine prep.
• Sessions: stateful commands run serially in one session. Parallelize only read-only commands or separate sessions/devices. If a prompt names a session, put --session <name> on every command in that flow.
• close when done. The iOS XCTest runner stays warm ~5 min after close, so consecutive opens are cheap.

Core interaction loop

1. snapshot -i → refs like @e12, plus [off-screen below] scroll hints.
2. Act with press / fill / click / longpress <@ref|selector|x y> --settle on every mutating action that supports it.
3. The settled diff is your next observation. Do not add wait stable or another snapshot when the diff already shows the next target. If it prints not settled, follow its hint before the next ref-based action.
4. Verify named expectations with wait text "…" / wait <selector> / is / get / find — a bare screenshot or snapshot is not verification of a named expectation.
5. Refs go stale after any mutation, and open/--relaunch invalidates all of them. After a mutation, prefer a known selector (press 'label="Send"') or refresh with snapshot -i (scope with -s "Container" when possible).

Targets: @e12 refs from the latest snapshot/settle output, or selectors — id="submit", label="Search", text="…", role=button label="Follow". Never CSS selectors, never placeholder refs like @eN in a plan. Ambiguous selectors auto-resolve (deepest node, then smallest area) — add id= or longer text to force a different match. Labels containing apostrophes are shell-quoting hazards; prefer the @ref.

Text entry: fill <target> <text> --settle replaces; type <text> appends to the focused field (autoFocused fields are already focused — fill there replaces the whole value, which is usually what you want). fill <target> "" is not a supported clear — use a visible clear control or report the gap. Keyboard on screen usually does not block taps: press the next target directly; only keyboard dismiss when hiding it is the actual goal.

Coordinates are last resort: after refs/selectors fail or accessibility omits the target, get rects with snapshot -i --json, press the center, verify with diff snapshot -i, and say why you used coordinates. Avoid screen edges, tab bars, and the home-indicator zone — they trigger system navigation.

Waits: wait text "…" [timeoutMs] polls every 300 ms (default timeout 10 s) and fails loudly on timeout — that failure is signal, not noise. Network-backed results can land after the settle window; follow the settled action with an explicit wait text/wait <selector> for server-loaded content.

The product-test loop

When the task is "test the app / features end to end, fix what breaks":

1. Tour one feature at a time against a coverage list you maintain (screens, flows, edge states). Capture baseline snapshot -i + screenshot <path> on entry.
2. Bug found → stop touring. Capture evidence now (screenshot, network dump, logs path, exact repro commands), then root-cause before writing any fix — see the triage table below and references/bug-triage.md.
3. Fix at the root layer, not the symptom layer.
4. Refresh the right runtime — the fix does nothing until the running code actually contains it (next section).
5. Retest from adequately fresh state (state matrix below), reproducing the original symptom path — not just re-reading the diff.
6. Resume the tour where you left off; re-run any flow your fix could have invalidated.

Rules that keep this loop honest:

• Every failure is new. After fixing cause #1, the next run may fail for a different root cause behind the same symptom. Re-read the actual error text every retry; never assume "same bug."
• Three failed fixes on one symptom → stop patching. Re-derive the root cause from fresh evidence (logs, network, backend state); the approach is dead, not the goal.
• Claim only the rung you reached. "Fix deployed" ≠ "bug gone." The bug is gone when the original repro path passes live, on-device, from fresh state.

Layer triage — where the bug actually lives

Empty screens, wrong data, and dead buttons are usually not screen bugs. Probe cheapest-first:

Full playbook with backend-probe patterns, current-user identification, and async-job polling: references/bug-triage.md.

Runtime freshness — the #1 false-negative source

"My fix didn't work" is, more often than not, "the running app never executed my fix." Before debugging logic, prove freshness:

• JS change (React Native/Expo): agent-device metro reload — but first confirm which Metro serves this app: which project root, which worktree, which port. A dev client happily loads JS from a different checkout than the one you edited. agent-device doctor reports dev-server reachability; lsof -iTCP:8081 -sTCP:LISTEN + the process cwd tells you whose Metro it is. Editing repo A while Metro serves repo B burns hours.
• Native change: Metro reload cannot deliver it. Rebuild/reinstall the binary, then open --relaunch.
• Backend change: the app talking to a deployed backend needs that backend redeployed (and env vars synced, if the platform snapshots them at deploy time) before on-device retesting means anything.
• Still unsure? Add a temporary visible marker (a log line or on-screen string) to the changed code and confirm it appears at runtime. One minute spent here saves a false "fix didn't hold."

RN/Expo specifics (Metro truth, Expo Go vs dev client opens, reload-vs-relaunch-vs-rebuild): references/dev-loop-react-native.md.

Fresh-state matrix

"Fresh" has independent levels — pick deliberately per retest; onboarding/auth flows usually need all of them:

Watch-out: repeated fresh-account runs create many server-side users. When probing the backend, identify the current run's user from evidence (newest created_at, device id, a value you just typed) — never assume the record you're looking at belongs to the run you're testing.

Evidence and reporting

• Screenshots to named paths per finding: screenshot ./out/issue-001.png; add --overlay-refs when showing the tappable target matters.
• Log windows small: logs clear --restart → logs mark "before X" → repro → logs path. Never cat a full stale log into context.
• Network: network dump --include headers (or body/all) — this is the request/response evidence, better than log spelunking.
• Video for interactive repros: record start ./out/issue.mp4 … record stop; --hide-touches for gesture-heavy captures.
• Perf: perf metrics --json first pass; perf frames --json for jank; artifacts (heap, traces, profiles) stay on disk — report path + size, never paste raw dumps.
• While exploring, do not pipe agent-device output through grep/jq/head or add 2>/dev/null — raw output carries refs, warnings, and hints your next step needs.
• Report per finding: severity, affected flow, exact repro commands (real refs/selectors, no placeholders), expected vs actual, evidence paths, and the layer of the root cause. If nothing was found, report coverage and residual risk — not "bug-free."

Hard-won rules (each of these cost real time once)

Guardrails

• Serial mutations per session — never parallel press/fill/open/close against one session.
• No placeholders in final command plans: if the ref is unknown, the plan starts with snapshot -i.
• Coordinates only after refs/selectors fail, with rects from snapshot -i --json and a stated reason.
• Never delete evidence artifacts mid-session.
• Do not "fix" a flow by weakening its verification (skipping the assert, widening the wait, accepting the wrong text).
• App auth needing a real OTP/2FA: ask the user for the code; do not fabricate entry.
• If info is not visible/exposed in the UI, report the gap — do not wander unrelated screens to force it.

Reference routing