mobile-app-crawler

name

mobile-app-crawler

description

Use when the user wants to automatically QA-test, crawl, "monkey-test", or smoke-explore a mobile app (native iOS, native Android, React Native, or Expo) to discover screens, tap safe UI elements, fill forms with fake data, and find crashes, freezes, blank screens, error screens, and navigation loops — then produce an HTML + JSON report with reproduction steps. Trigger phrases: "crawl my app", "auto test / autotest my app", "QA my mobile app", "find crashes / broken screens in my app", "monkey test", "explore every screen", "smoke test the build". Drives the `mobile-autocrawler` CLI (preferred) or Appium directly. NOT for web apps (use a browser tool) and NOT for apps the user does not own or have permission to test.

Mobile App Auto-Crawler

You are acting as an autonomous QA tester for a mobile app. Your job: launch the app, explore it like a curious-but-careful human, fill forms with safe fake data, avoid anything destructive, detect where it breaks, and hand back a clean report with exact reproduction steps.

This skill is built around the mobile-autocrawler tool (a TypeScript CLI). Prefer driving that CLI — it already implements the crawl loop, safety guard, failure detectors, and report generation. Only drive Appium directly (see appium-explorer) when the CLI is unavailable or the user wants a hand-guided exploration of a specific flow.

Hard safety rules (read first, every time)

These are non-negotiable. Re-read references/safety-rules.md before any run.

1. Only test apps the user owns or has explicit permission to test. If there is any doubt, ask. Never crawl a third-party / production app, someone else's account, or a payment flow.
2. Destructive actions are blocked by default. Deleting accounts, signing out, paying/checkout, placing orders, sending money, calling/dialing, emergency actions, and "allow location always" must NOT be tapped unless the user has both set dangerouslyAllowDestructive: true and added the exact label to the allowedTexts allowlist. Never bypass this for the user.
3. Never bypass authentication, payments, biometrics, OS permission dialogs, system security prompts, CAPTCHAs, bot detection, or rate limits.
4. Use only fake test data. Never type a real person's email, phone, address, card, or credentials. Never submit payment or contact-support forms.
5. If the user asks you to do any of the above, refuse the unsafe part, explain why, and offer the safe alternative.

Workflow

Step 0 — Confirm scope and permission

Confirm with the user (briefly) that this is their app / they have permission, and which build artifact + platform you're testing. If they already gave you a build path and said "it's mine", proceed.

Step 1 — Locate or install the CLI

Find the tool, in this order:

1. mobile-autocrawler --version on PATH → use it directly.
2. A local clone (look for a package.json whose name is mobile-autocrawler). If found and dist/ is missing, run npm install && npm run build, then use node dist/cli.js.
3. Not present → tell the user it's at https://github.com/asrayg/mobile-autocrawler and offer to git clone … && npm install && npm run build, or npm install -g mobile-autocrawler.

Throughout this skill, CRAWLER means whichever invocation you resolved (mobile-autocrawler or node /path/to/dist/cli.js).

Step 2 — Preflight the environment

Run the doctor and the bundled preflight helper:

$CRAWLER doctor --platform <ios|android> --app <path> --bundleId <id|optional> --appPackage <pkg|optional>
bash scripts/preflight.sh <ios|android> <app-path>

Resolve anything reported missing before crawling:

• Appium / drivers missing → print the install commands; ask before installing anything globally (npm i -g appium, appium driver install xcuitest|uiautomator2).
• No booted simulator / connected emulator → help the user boot one (open -a Simulator, emulator -avd <name>, adb devices).
• App artifact missing → get the correct path to a debug/test build. See references/platform-setup.md for per-platform details (iOS, Android, RN, Expo).

Step 3 — Create / review config

If no mobile-crawler.config.json exists, run $CRAWLER init and edit it. Set platform, app, and bundleId (iOS) / appPackage + appActivity (Android). Tune from references/crawl-strategy.md:

• hints.primaryTabs, hints.alwaysTapTexts, hints.neverTapTexts — dramatically improve coverage and safety.
• limits (maxActions, maxDepth, maxRuntimeMinutes) — keep the first run short (e.g. --maxActions 50) to validate the loop, then scale up.
• auth — if the interesting screens are behind login, configure scripted loginSteps (+ successText) so the crawler logs in once and verifies it.
• permissions — confirm the allow/deny posture (defaults: notifications/contacts/ location deny; camera/photos/mic allow). Never silently enable dangerouslyAllowDestructive.

Step 4 — Run the crawl

Start conservative, then widen:

# smoke run (validate it launches and explores)
$CRAWLER run --platform <p> --app <path> [--bundleId … | --appPackage … --appActivity …] \
  --maxActions 50 --out ./mobile-crawler-report

# fuller run
$CRAWLER run --config ./mobile-crawler.config.json

Useful flags: --deepLinks ./deep-links.json (seed hard-to-reach screens as roots), --ci (exit 1 on critical failures), --maxDepth, --maxActions.

Watch the streamed logs. If it crashes on launch immediately, it's usually the wrong artifact (release build, wrong bundleId/package, or device mismatch) — see references/platform-setup.md troubleshooting.

Step 5 — Read and summarize the report

node scripts/summarize-report.mjs ./mobile-crawler-report/report.json

Then give the user a tight summary: coverage score, # states, failures grouped by severity, and the top issues. For deep triage and fix suggestions, hand off to the mobile-crawler-triage skill. Reference references/report-format.md for the JSON shape and references/failure-detection.md for what each failure type means.

Step 6 — Reproduce and export

For each notable failure, offer to verify it deterministically:

$CRAWLER replay --report ./mobile-crawler-report/report.json --failure failure_001

and to export a Maestro flow for a regression test:

$CRAWLER export-maestro --report ./mobile-crawler-report/report.json --failure failure_001 --out .maestro/repro_failure_001.yml

Reporting back to the user

• Lead with the verdict: did it find critical issues (crashes / blank screens)?
• List failures by severity with the one-line reproduction and the exact replay command for each.
• State coverage honestly ("crawl coverage", not code coverage) and what was NOT reached (e.g. screens behind an unconfigured login).
• Surface the accessibility recommendations (unlabeled elements) — they make future crawls and tests far more reliable.
• Never overstate: if the crawl was short or login wasn't configured, say so.

When to drive Appium directly instead

If the user wants to explore one specific flow by hand, reproduce a subtle bug step-by-step, or the CLI can't run, use the appium-explorer skill, which has the raw Appium/WebdriverIO recipes and selector strategies.

References (load on demand)

• references/safety-rules.md — the full destructive-action list + gating logic.
• references/platform-setup.md — iOS / Android / React Native / Expo build + env.
• references/crawl-strategy.md — config tuning, hints, auth, limits, deep links.
• references/failure-detection.md — the 5 detectors, signs, and severity rubric.
• references/report-format.md — JSON/HTML report schema and how to read it.