aarwitz Tapp
Use Tapp as the app's hands and eyes. Work on the real UI surface and show evidence; do not claim a screen or journey works from source inspection alone.
Choose the smallest operation
| Intent | Operation |
|---|---|
| See or screenshot one screen | open / tapp_open_app |
| Inspect controls on the current screen | tree / tapp_ui_tree |
| Reach a named screen/control | focus / tapp_focus (source + observed UI Map fast path) |
| Drive a specific journey | MCP session start → focus or act → end |
| Find bugs autonomously | explore / tapp_explore |
| Preserve a journey | record and save a Flow; replay it deterministically |
| Decide whether a merge passes policy | ci; exploration never decides this |
Prefer connected tapp_* MCP tools when available: they keep interactive sessions alive and return
screenshots inline. Otherwise run npx -y @aarwitz/tapp@latest from the app repository. Do not require MCP,
an account, an API key, or a global install for the core workflow.
Start source-connected
When the user asks for a general first test of a repository:
- If
.tapp/application-model.jsonexists, runnpx -y @aarwitz/tapp@latest explore. - Otherwise run
npx -y @aarwitz/tapp@latest init . --exploreor calltapp_initwith{operation:"explore", projectDir:"."}. - If Tapp returns
target-selection-required, present its actual choices and ask the user to pick. Never guess among multiple targets. Re-run with the selected platform/target exactly as Tapp instructs. - If a prerequisite is missing, call
tapp_healthwhen MCP is connected or runnpx -y @aarwitz/tapp@latest doctor, apply only the stated remediation that is in scope, and retry once.
For a focused request in an already-grounded repository, use the requested target directly rather
than starting another broad exploration. If .tapp/ui-map.json does not exist yet, ground it once
with init . --explore; source alone can locate a surface but cannot authorize unobserved taps.
Targets may be a repository path, Xcode container, .app, iOS bundle id, APK plus Android app id,
or owned HTTP(S) URL. Never explore a third-party web property without authorization: exploration
clicks and types.
Navigate like a source-connected expert
When the user names a screen, control, or UI condition, do not discover the app one screenshot at a time. Start from the repository source, then use Tapp's observed navigation evidence:
- In a source repository, run
npx -y @aarwitz/tapp@latest focus "<exact request>" [target]; it selects the reviewed model target and prepares web, iOS, or Android from source. In an active MCP session calltapp_focus; for managed web,tapp_session_startcan also takeprojectDirandfocuswithout retyping the URL. - Tapp searches owned source, reconciles the likely surface with
.tapp/ui-map.json, and executes the shortest runtime-observed route in one call. Read its final tree before visual assertions. - If Tapp returns source evidence but no replayable route, inspect the cited file/line and relevant router/navigation source. Do not wander blindly or invent a path; ground the map or drive only a route supported by that source evidence.
A fresh repository needs one grounding exploration before focus can replay a route. Source can
locate an unobserved surface, but it never authorizes unobserved taps.
Source establishes intent and location; the real UI establishes behavior. A URL-only target has no source advantage and correctly falls back to runtime observation.
Observe honestly
Exploration returns findings, coverage, evidence, and inconclusive; it does not return a score or
ship verdict. Report:
- target and platform;
- screens/actions and whether coverage was conclusive;
- deterministic versus advisory finding counts;
- each important finding and its evidence/report path;
- what Tapp explicitly did not check.
If inconclusive: true, explain the blocker. A login wall or missing test data is not a pass. Ask for
credentials or launch configuration instead of rerunning blindly. Do not infer content accuracy,
privacy, brand consistency, or business guarantees from a generic crawl; those require a reviewed
Flow, Scenario, contract, verifier, or human review.
When a screenshot path is printed, open it with the client's image-reading tool before describing
the screen. For web, use --watch when the human wants to follow Tapp's controlled browser. For iOS,
point the human to the report's exploration recording when available.
Drive safely
After the focused fast path, read returned elements[] before any remaining action, target accessibility
ids or visible labels, check hittable, tap a field before typing, and wait for navigation or async
content. Use coordinates only as a last resort. End the session when finished.
Do not edit the app merely because testing found a defect unless the user also asked for a fix. State what the evidence proves and what remains untested.
Read references/commands.md only for exact CLI/MCP syntax, Flow replay, credentials, or platform prerequisites.