appium-explorer

name

appium-explorer

description

Use when the user wants to drive a mobile app via Appium directly — to explore a specific flow by hand, reproduce a subtle bug step-by-step, inspect the UI element tree, build selectors, or prototype automation — rather than running a full automated crawl. Also the fallback when the mobile-autocrawler CLI can't run. Trigger phrases: "open the app and tap X", "what's on this screen", "inspect the element tree", "drive Appium", "reproduce these exact steps", "find a selector for this button". Same safety rules as mobile-app-crawler: apps the user owns, no destructive taps, no auth/payment/biometric bypass.

Appium Explorer

Hands-on, step-by-step control of a mobile app through Appium + WebdriverIO. Use this when a full automated crawl is overkill or unavailable: reproducing a precise bug, exploring one flow, inspecting the UI tree, or building reliable selectors.

For a full automated QA sweep, use the mobile-app-crawler skill instead.

Safety

The same hard rules apply: only apps the user owns/permits; never tap destructive controls (delete, sign out, pay, checkout, place order, call, "allow location always", …) without explicit user confirmation; never bypass auth, payments, biometrics, OS permission/security dialogs, CAPTCHAs, or rate limits; only fake test data. See mobile-app-crawler/references/safety-rules.md.

Setup

1. Appium 2 + driver installed (appium driver install xcuitest|uiautomator2).
2. A booted simulator / connected emulator-or-device.
3. Start a server (or let your script point at one): appium (default http://127.0.0.1:4723).
4. A debug/test build artifact path + bundleId (iOS) / appPackage+appActivity (Android).

See mobile-app-crawler/references/platform-setup.md for build/env details.

Two ways to drive

A. Quick one-off snapshot/inspection (recommended first move)

Use the helper to create a session, dump the current screen's page source + window size + a screenshot, and tear down — no code to write:

node scripts/appium-snapshot.mjs \
  --platform ios --app ./MyApp.app --bundleId com.company.myapp \
  --out ./snapshot
# Android:
node scripts/appium-snapshot.mjs \
  --platform android --app ./app-debug.apk \
  --appPackage com.company.myapp --appActivity .MainActivity --out ./snapshot

It writes snapshot/source.xml (the UI tree) and snapshot/screen.png. Read the XML to understand what's on screen and to build selectors (see references/element-selectors.md).

B. Scripted interaction (WebdriverIO)

When you need to perform steps, write a small WebdriverIO script. The cheatsheet in references/appium-cheatsheet.md has copy-paste recipes for: creating a session, finding elements (accessibility id / resource-id / xpath / iOS predicate), tapping, typing, swiping/scrolling, handling alerts, querying app state, getting the page source, and taking screenshots. Reuse the project's own helpers where useful (mobile-autocrawler's getScreenSnapshot, parsePageSource).

Workflow for "reproduce these exact steps"

1. Snapshot the launch screen (option A) so you can see element identities.
2. For each step, find the target element by the most stable selector available (accessibility id > resource-id > text > xpath), perform the action, then re-snapshot to confirm the screen changed as expected.
3. Stop at the failing step; capture source.xml + screen.png + (if it crashed) device logs (adb logcat -d / iOS syslog).
4. Report exactly which step diverged and what you observed.

Workflow for "find a good selector for this button"

1. Snapshot the screen; open source.xml.
2. Locate the node by its visible text/label. Prefer, in order:
   • iOS: ~accessibilityIdentifier (the name attr) → -ios predicate string → -ios class chain → xpath.
   • Android: id=<resource-id> → ~content-desc → text xpath → xpath.
3. If the element has no stable identifier, recommend the dev add a testID / accessibilityIdentifier / resource-id — coordinate taps are brittle.

References

• references/appium-cheatsheet.md — WebdriverIO + Appium recipes.
• references/element-selectors.md — selector strategies per platform, with the reliability ranking and how to read the page source XML.