mirror of
https://github.com/callstack/agent-device.git
synced 2026-09-14 20:06:34 +08:00
docs: clarify agent setup and text entry guidance (#1164)
This commit is contained in:
Michał Pierzchała
committed by
GitHub
GitHub
parent
cfef0a4bca
commit
0d2b0353ff
@@ -52,11 +52,15 @@ Install the CLI:
|
||||
|
||||
```bash
|
||||
npm install -g agent-device@latest
|
||||
agent-device doctor
|
||||
agent-device --version
|
||||
agent-device help workflow
|
||||
```
|
||||
|
||||
The installed CLI help is the source of truth for agents. Start with `agent-device help workflow`, then follow the topic-specific help when a task needs dogfooding, debugging, replay, or React Native profiling.
|
||||
Run `agent-device doctor` yourself after installation to check local setup before
|
||||
handing the CLI to an agent. The installed CLI help is the source of truth for
|
||||
agents. Start with `agent-device help workflow`, then follow the topic-specific
|
||||
help when a task needs dogfooding, debugging, replay, or React Native profiling.
|
||||
|
||||
Prerequisites depend on the target platform: Node.js 22+, Xcode for iOS/tvOS/macOS targets, Android SDK + ADB for Android, and macOS Accessibility permission for desktop automation. Web automation requires Node 24+. See [Installation](https://oss.callstack.com/agent-device/docs/installation) for platform setup.
|
||||
|
||||
|
||||
@@ -38,8 +38,6 @@ agent-device help dogfood
|
||||
|
||||
Default loop: `open -> snapshot/-i -> get/is/find or press/fill/scroll/wait -> verify -> close`.
|
||||
|
||||
On a fresh machine (first iOS run), start with `agent-device doctor --platform ios`: it preflights the environment and warms the iOS runner build cache in the background so the first `open` is fast.
|
||||
|
||||
Use this skill only to route into version-matched CLI help. Let the selected help topic provide exact command shapes, platform limits, and current workflow guidance; use `help workflow` as the full reference when a task-specific topic is too narrow.
|
||||
|
||||
For precise location workflows, read the installed `settings` help before planning so coordinate support and platform limits come from the active CLI version.
|
||||
|
||||
@@ -107,7 +107,8 @@ test('usage includes agent workflows, config, environment, and examples footers'
|
||||
assert.match(usageText, /open "Expo Go" <url> --platform ios/);
|
||||
assert.match(usageText, /Do not use plain snapshot or snapshot --diff for this recovery check/);
|
||||
assert.match(usageText, /Install flows: install\/install-from-source first/);
|
||||
assert.match(usageText, /fill 'id="field-email"' "qa@example\.com" replaces/);
|
||||
assert.match(usageText, /use fill <target> <text> --settle to replace a field value/);
|
||||
assert.match(usageText, /Use type <text> only to append after focusing a field with press/);
|
||||
assert.match(usageText, /do not use fill <target> ""/);
|
||||
assert.match(usageText, /Android IME capture: if fill says input was captured/);
|
||||
assert.match(usageText, /Implicit default sessions are scoped to the current worktree/);
|
||||
@@ -116,6 +117,8 @@ test('usage includes agent workflows, config, environment, and examples footers'
|
||||
assert.match(usageText, /After mutation: refs are stale/);
|
||||
assert.match(usageText, /use its selector directly; otherwise refresh with snapshot -i/);
|
||||
assert.match(usageText, /verify the action with diff snapshot -i or snapshot --diff/);
|
||||
assert.match(usageText, /fill <targetOrX> <yOrText> \[text\]\s+Replace text in/);
|
||||
assert.match(usageText, /type <text>\s+Append text to the focused field/);
|
||||
assert.match(usageText, /Sparse or AX-unavailable snapshot/);
|
||||
assert.match(usageText, /macOS context menus use click <ref> --button secondary/);
|
||||
assert.match(
|
||||
@@ -456,6 +459,8 @@ test('usageForCommand resolves manual QA help topic', async () => {
|
||||
assert.match(help, /Run snapshot -i to get current refs/);
|
||||
assert.match(help, /press\/fill\/click\/longpress <ref-or-selector> --settle/);
|
||||
assert.match(help, /A bare screenshot\/snapshot is not verification/);
|
||||
assert.match(help, /use fill <target> <text> --settle to replace/);
|
||||
assert.match(help, /use type only to append to an already-focused field/);
|
||||
assert.match(help, /Do not use placeholders such as @ref/);
|
||||
});
|
||||
|
||||
@@ -556,10 +561,8 @@ test('usageForCommand resolves react-native help topic', async () => {
|
||||
assert.match(help, /help react-devtools/);
|
||||
assert.match(help, /Help workflow owns the full Expo URL command shapes/);
|
||||
assert.match(help, /For app\/package launches, run metro prepare/);
|
||||
assert.match(help, /agent-device doctor --platform android/);
|
||||
assert.match(help, /agent-device doctor --platform android --app com\.example\.app/);
|
||||
assert.match(help, /agent-device doctor --platform ios/);
|
||||
assert.match(help, /agent-device doctor --remote --remote-config \.\/remote\.json/);
|
||||
assert.match(help, /Do not run doctor as routine QA\/dogfood prep/);
|
||||
assert.match(help, /Use doctor only when the user asks for setup diagnostics/);
|
||||
assert.match(help, /same host context that owns the dev server/);
|
||||
assert.match(help, /sandbox probe is not authoritative/);
|
||||
assert.match(help, /adb reverse only affects Android device-to-host traffic/);
|
||||
|
||||
@@ -93,7 +93,7 @@ const AGENT_QUICKSTART_LINES = [
|
||||
'Android RN/Expo/Re.Pack dev server: direct Android localhost URL opens with a port auto-configure host reachability.',
|
||||
'Expo Go/dev clients: use the provided URL when given; on iOS use open "Expo Go" <url> --platform ios, then snapshot -i --platform ios to verify project UI. Do not use plain snapshot or snapshot --diff for this recovery check. Android URL opens infer the foreground package for logs/perf when possible.',
|
||||
'Install flows: install/install-from-source first, then open the installed id with --relaunch.',
|
||||
'Text: fill \'id="field-email"\' "qa@example.com" replaces; type appends after press.',
|
||||
'Text fields: use fill <target> <text> --settle to replace a field value. Use type <text> only to append after focusing a field with press.',
|
||||
'Clearing text: do not use fill <target> ""; use a visible clear/reset control or report that clearing is unsupported.',
|
||||
'Android IME capture: if fill says input was captured by the keyboard/IME, inspect keyboard state and switch/disable handwriting before retrying; do not loop fill/type.',
|
||||
'Implicit default sessions are scoped to the current worktree; if a prompt names a Session, include --session <name> on every command in that flow.',
|
||||
@@ -168,6 +168,7 @@ Loop:
|
||||
|
||||
Targets:
|
||||
Prefer refs from the latest snapshot -i or settled diff. Use durable selectors when the label/id is known: label="Search", id="submit", role=button label="Follow".
|
||||
For text fields, use fill <target> <text> --settle to replace the field value; use type only to append to an already-focused field.
|
||||
Do not use placeholders such as @ref, @eN, <button>, or <selector> in a final command plan. If the ref is unknown, first run snapshot -i.
|
||||
Coordinates are fallback-only after refs/selectors fail or accessibility omits the target; use screenshot or snapshot -i --json to choose a visible center point.
|
||||
|
||||
@@ -187,9 +188,6 @@ Core loop:
|
||||
Start with the top-level Agent Starting Point for the default settle-first loop. This topic is the full reference for command shapes, refs, selectors, waits, recovery, and platform limits.
|
||||
If you intentionally skip --settle or use a command that does not support it, verify a mutation with diff snapshot (or diff snapshot -i) instead of a full snapshot: it diffs the rendered snapshot lines against the previous one in this session and prints only what changed.
|
||||
|
||||
Fresh machine or first iOS run:
|
||||
Run agent-device doctor --platform ios first. Besides preflight checks it warms the iOS XCTest runner build cache in the background, so the first open skips the runner build (~10s). To block until fully warm instead, run agent-device prepare ios-runner.
|
||||
|
||||
Command shape:
|
||||
Plans should use agent-device commands, not raw platform tools, pseudo commands, package-manager aliases, or helper prose.
|
||||
If the user asks for a command plan, final output should be command lines only: no intro sentence, numbered list, Markdown fence, shell pipe, grep/head/tail helper, or explanatory bullets.
|
||||
@@ -696,11 +694,7 @@ Choose the next help topic:
|
||||
Remote/cloud config, leases, and local service tunnels: help remote.
|
||||
|
||||
React Native dev loop:
|
||||
Before QA/dogfood runs, use doctor to separate environment setup from app failures (on iOS simulators doctor also warms the runner build cache in the background):
|
||||
agent-device doctor --platform android
|
||||
agent-device doctor --platform ios
|
||||
agent-device doctor --platform android --app com.example.app
|
||||
agent-device doctor --remote --remote-config ./remote.json
|
||||
Do not run doctor as routine QA/dogfood prep. Use doctor only when the user asks for setup diagnostics or a command failure points to an unhealthy device, runner, dev-server, or remote environment.
|
||||
For "start from screen X" flows, prefer open --relaunch before the first snapshot so the app does not reuse a prior in-progress navigation state.
|
||||
JS-only change with Metro or Re.Pack connected:
|
||||
agent-device metro reload
|
||||
|
||||
@@ -57,11 +57,11 @@ const FIND_ACTION_VALUES = [
|
||||
const interactionCommandDescriptions = {
|
||||
click: 'Click or tap a semantic UI target by ref, selector, or point.',
|
||||
press: 'Press a semantic UI target by ref, selector, or point.',
|
||||
fill: 'Fill text into a semantic UI target by ref, selector, or point.',
|
||||
fill: 'Replace text in a semantic UI target by ref, selector, or point.',
|
||||
longpress: 'Long press by ref, selector, or point.',
|
||||
swipe: 'Swipe between two points.',
|
||||
focus: 'Focus input at coordinates.',
|
||||
type: 'Type text in the focused field.',
|
||||
type: 'Append text to the focused field.',
|
||||
scroll: 'Scroll in a direction or to an edge.',
|
||||
get: 'Get element text or attributes.',
|
||||
is: 'Assert UI state.',
|
||||
|
||||
@@ -10,7 +10,7 @@ import { managementCliOutputFormatters } from './output.ts';
|
||||
|
||||
const doctorCommandMetadata = defineFieldCommandMetadata(
|
||||
'doctor',
|
||||
'Diagnose device, app, Metro, and React Native readiness before a run.',
|
||||
'Diagnose device, app, Metro, and React Native setup/readiness issues.',
|
||||
{
|
||||
targetApp: commandInput.stringField(
|
||||
'Installed app package/bundle id or app name to verify without opening a session.',
|
||||
@@ -29,8 +29,8 @@ const doctorCliSchema = {
|
||||
usageOverride:
|
||||
'doctor [--platform ios|android|macos|linux|web|apple] [--app <id-or-name>] [--remote]',
|
||||
helpDescription:
|
||||
'Preflight for QA and dogfood runs. Reports local device inventory, active sessions, optional app discovery, scoped toolchain info, and Metro reachability inferred from cwd/runtime. On iOS simulators it also warms the XCTest runner build cache in the background when missing, so the first open on a fresh machine skips the runner build — run doctor first on new setups. Pass --app to verify a target app on the one matching booted device without opening a session. Use --remote to check remote connection setup without probing local devices. Default output is compact; use --json for full checks and evidence.',
|
||||
summary: 'Preflight device, app, dev-server, and RN/Expo readiness',
|
||||
'Setup and recovery diagnostic for device, app, dev-server, and RN/Expo readiness issues. Reports local device inventory, active sessions, optional app discovery, scoped toolchain info, and Metro reachability inferred from cwd/runtime. On iOS simulators it also warms the XCTest runner build cache in the background when missing. Pass --app to verify a target app on the one matching booted device without opening a session. Use --remote to check remote connection setup without probing local devices. Default output is compact; use --json for full checks and evidence.',
|
||||
summary: 'Diagnose device, app, dev-server, and RN/Expo readiness',
|
||||
allowedFlags: ['targetApp', 'remote'],
|
||||
} as const satisfies CommandSchemaOverride;
|
||||
|
||||
|
||||
@@ -11,10 +11,14 @@ Install `agent-device` on the machine where the coding agent will run terminal c
|
||||
|
||||
```bash
|
||||
npm install -g agent-device@latest
|
||||
agent-device doctor
|
||||
agent-device --version
|
||||
agent-device help
|
||||
```
|
||||
|
||||
Run `agent-device doctor` yourself after installation to check local device,
|
||||
toolchain, and dev-server readiness before handing the CLI to an agent.
|
||||
|
||||
Use global install for normal agent workflows. It gives agents a stable `agent-device` command and version-matched help topics:
|
||||
|
||||
```bash
|
||||
@@ -32,6 +36,7 @@ Interactive CLI runs periodically check for a newer published `agent-device` pac
|
||||
|
||||
```bash
|
||||
npm install -g agent-device@latest
|
||||
agent-device doctor
|
||||
agent-device --version
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user