AGENTS.md
+64 −43
https://raw.githubusercontent.com/aarwitz/tapp/HEAD/AGENTS.md
− npx -y @aarwitz/tapp@latest focus "SCREEN OR CONTROL" [target] # source-locate + shortest observed route + screenshot− npx -y @aarwitz/tapp@latest open [target] # launch + screen summary + screenshot saved to a file (≈ tapp_open_app)− npx -y @aarwitz/tapp@latest tree [target] # accessibility tree, --json for every element (≈ tapp_ui_tree)− npx -y @aarwitz/tapp@latest shot # screenshot the booted sim → file path (≈ tapp_screenshot)− npx -y @aarwitz/tapp@latest apps # what's installed on the simulator, with bundle ids− npx -y @aarwitz/tapp@latest build [dir] # build the app in an Xcode repo + install it (≈ tapp_build)− npx -y @aarwitz/tapp@latest flow run .tapp/flows/smoke.yml # committed, keyless E2E replay− On iOS, `tree` only uses an installed app: it never builds, uninstalls, or replaces it. With− run `tapp build` explicitly first.− wait: `tapp open https://example.com --tap "Not now" --wait-for "Dashboard"`. Tapp waits for the− | "Show me / screenshot a screen" | `tapp_open_app` (launch + screenshot + tree, ~15s) | `tapp_explore` (a full multi-minute exploration) |− | "Find/reach this named screen or control" | `tapp_session_start` with `focus`, or `tapp_focus`; plain CLI: `tapp focus` | screenshot-by-screenshot wandering |− | "Tap through / drive / fill a form / log in" | `tapp_session_start` → `session_act` loop | repeated `open_app` calls (cold relaunch each time) |− | "Is this live site / production / a prospect's site broken?" | `tapp_audit` (CLI `tapp audit <url> --pages N`) — read-only: dead controls, broken images/links/assets, failed requests, JS errors, mixed content, overflow; writes a capture with evidence | `tapp_explore` (it clicks, types and submits) |− | "Make this flow a repeatable test" | drive it in a session, then `tapp_flow_save`; replay with `tapp_flow_run` | re-driving it by hand every time |− | "What's on screen right now?" | `tapp_screenshot` / `tapp_ui_tree` | relaunching the app |− tapp_session_start { appBundleId: "com.acme.app", focus: "Save storefront settings visible above keyboard", projectDir: "." }− tapp_session_start { focus: "Storefront Settings", projectDir: "." } → managed web target from the workspace− tapp_focus { query: "Save storefront settings visible above keyboard" } → one-call shortest observed route− tapp_session_act { action: "login", email: "qa@x.com", password: "…" } → atomic fill + submit + verify− tapp_session_act { action: "tap", id: "Email" } → tap by a11y id OR visible label− tapp_session_act { action: "type", text: "qa@x.com" } → types into the focused field− tapp_session_act { action: "tap", id: "Sign In" }− tapp_session_act { action: "wait", text: "Home", timeoutMs: 10000 } → block until it appears− tapp_screenshot → see it− tapp_session_end− Android uses the same loop with `tapp_session_start { androidAppId: "com.acme.app", apkPath:− 6. One session at a time. `session_start` always begins from a fresh **cold** launch− wall, so plan `login` (or a bypass launch argument) as the first act. Plain `tapp tree` /− `tapp screenshot` warm-resume the currently foregrounded app instead, which is why they can− - `tapp audit <url>` / `tapp_audit` is the read-only pass: it renders the page and reads it but never− - **Record:** every successful `session_act` is recorded. After driving a flow, call− `tapp_flow_save { name: "checkout" }` → writes `.tapp/flows/checkout.yml` with waits and− - **Replay:** `tapp_flow_run { flowPath: ".tapp/flows/checkout.yml" }` — exact steps,− env-var **names** only — never values. `tapp actor set` refuses to overwrite an existing− - **Generate:** `tapp_flow_generate { goal: "log in and add the first item to cart" }` —− - **Discover the file format without MCP:** `npx -y @aarwitz/tapp@latest flow example` prints a− complete starter Flow; `tapp flow validate <file>` checks it without launching a target.− - First tool call builds the test harness once (~2 min, cached in `~/.tapp`). `tapp install`− - The app under test must be **installed on the booted simulator** (`tapp_install_app` builds+ npx -y @aarwitz/tapp@latest explore --goal "SCREEN OR CONTROL" [target] # source-locate + shortest observed route + screenshot+ npx -y @aarwitz/tapp@latest explore --read-only https://example.com --pages 5 # never clicks: production or a site you do not own+ npx -y @aarwitz/tapp@latest look [target] # launch + screen summary + screenshot saved to a file (≈ tapp_look)+ npx -y @aarwitz/tapp@latest look [target] --tree # + the accessibility tree, --json for every element+ npx -y @aarwitz/tapp@latest look # no target on iOS: the booted sim as it is → file path+ npx -y @aarwitz/tapp@latest run .tapp/flows/smoke.yml # committed, keyless replay of a Flow, Task, contract, or Scenario+ On iOS, `look` only uses an installed app: it never builds, uninstalls, or replaces it. With+ run `tapp_build` (MCP) or `init . --explore` explicitly first.+ wait: `tapp look https://example.com --tap "Not now" --wait-for "Dashboard"`. Tapp waits for the+ | "Show me / screenshot a screen" | `tapp_look` (launch + screenshot; `tree:true` for the tree, ~15s) | `tapp_explore` (a full multi-minute exploration) |+ | "Find/reach this named screen or control" | `tapp_session {action:"start", focus}` or `tapp_explore {goal}`; plain CLI: `tapp explore --goal` | screenshot-by-screenshot wandering |+ | "Tap through / drive / fill a form / log in" | `tapp_session` `start` → act loop | repeated `tapp_look` launches (cold relaunch each time) |+ | "Is this live site / production / a prospect's site broken?" | `tapp_explore {readOnly:true}` (CLI `tapp explore --read-only <url> --pages N`) — read-only: dead controls, broken images/links/assets, failed requests, JS errors, mixed content, overflow; writes a capture with evidence | `tapp_explore` (it clicks, types and submits) |+ | "Make this flow a repeatable test" | drive it in a session, then `tapp_session {action:"save_flow"}`; replay with `tapp_run` | re-driving it by hand every time |+ | "What's on screen right now?" | `tapp_look` | relaunching the app |+ tapp_session { action: "start", appBundleId: "com.acme.app", focus: "Save storefront settings visible above keyboard", projectDir: "." }+ tapp_session { action: "start", focus: "Storefront Settings", projectDir: "." } → managed web target from the workspace+ tapp_explore { goal: "Save storefront settings visible above keyboard" } → one-call shortest observed route+ tapp_session { action: "login", email: "qa@x.com", password: "…" } → atomic fill + submit + verify+ tapp_session { action: "tap", id: "Email" } → tap by a11y id OR visible label+ tapp_session { action: "type", text: "qa@x.com" } → types into the focused field+ tapp_session { action: "tap", id: "Sign In" }+ tapp_session { action: "wait", text: "Home", timeoutMs: 10000 } → block until it appears+ tapp_look → see it+ tapp_session { action: "end" }+ Android uses the same loop with `tapp_session { action: "start", androidAppId: "com.acme.app", apkPath:+ 6. One session at a time. `action:"start"` always begins from a fresh **cold** launch+ wall, so plan `login` (or a bypass launch argument) as the first act. Plain `tapp look`+ warm-resumes the currently foregrounded app instead, which is why they can+ - `tapp explore --read-only <url>` / `tapp_explore {readOnly:true}` is the read-only pass: it renders the page and reads it but never+ - **Record:** every successful session act is recorded. After driving a flow, call+ `tapp_session { action: "save_flow", name: "checkout" }` → writes `.tapp/flows/checkout.yml` with waits and+ - **Replay:** `tapp_run { path: ".tapp/flows/checkout.yml" }` — exact steps,+ env-var **names** only — never values. `tapp plan actor set` refuses to overwrite an existing+ - **Generate:** `tapp_session { action: "draft_flow", goal: "log in and add the first item to cart" }` —+ - **Discover the file format without MCP:** `npx -y @aarwitz/tapp@latest validate --example` prints a+ complete starter Flow; `tapp validate <file>` checks it without launching a target.+ - First tool call builds the test harness once (~2 min, cached in `~/.tapp`). `tapp doctor --install`+ - The app under test must be **installed on the booted simulator** (`tapp_build { action: "install" }` builds+ - A simulator must be booted (`tapp_build { action: "list_simulators" }` → `{ action: "boot" }`).
Showing the first 40 of each.
