mobile-testing
/mobile-testing
Test a native mobile app (Android/iOS) by driving it through Appium. Use whenever the user wants to test a mobile app for defects — happy paths, edge cases, and negative cases — either sequentially (human-in-the-loop, the default) or in parallel (autonomous, one session per available device/emulator). Produces per-scenario screenshots and logs plus a consolidated defect report. Read this before starting any mobile testing run.
- Author
- mhmdelgazzar ↗
- Repository
- agentex ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 13
- Scripts
- 8
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 8 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/appium_client.js, scripts/appium_client.test.js, scripts/init_run.js, scripts/init_run.test.js, scripts/merge_run.js, scripts/merge_run.test.js, scripts/preflight.js, scripts/preflight.test.js
What it does and when to use it
Test a native mobile app (Android/iOS) by driving it through Appium. Use whenever the user wants to test a mobile app for defects — happy paths, edge cases, and negative cases — either sequentially (human-in-the-loop, the default) or in parallel (autonomous, one session per available device/emulator). Produces per-scenario screenshots and logs plus a consolidated defect report. Read this before starting any mobile testing run.
Original author description
Test a native mobile app (Android/iOS) by driving it through Appium. Use whenever the user wants to test a mobile app for defects — happy paths, edge cases, and negative cases — either sequentially (human-in-the-loop, the default) or in parallel (autonomous, one session per available device/emulator). Produces per-scenario screenshots and logs plus a consolidated defect report. Read this before starting any mobile testing run.
How it works
- Role
- Target & environment resolution
- Tools
- Execution output layout
- Modes
- Defect reporting format
- Rules
SKILL.md preview
---
name: mobile-testing
description: Test a native mobile app (Android/iOS) by driving it through Appium. Use whenever the user wants to test a mobile app for defects — happy paths, edge cases, and negative cases — either sequentially (human-in-the-loop, the default) or in parallel (autonomous, one session per available device/emulator). Produces per-scenario screenshots and logs plus a consolidated defect report. Read this before starting any mobile testing run.
---
# Mobile Testing Agent
## Role
You are a QA test engineer. You test native mobile apps (Android/iOS) by driving a real
Appium session (run via Bash, either raw WebDriver REST calls or the bundled wrapper script —
see Tools below). You do **not** modify application code. Your job is to find defects, verify
behavior against expectations, and report findings clearly.
## Target & environment resolution
Resolve once, before any device action, in this order:
1. **Explicit environment** — the user said "run on uat" / the spec has `env: uat`
→ read `environments/uat.json`.
2. **Default** — `defaultEnvironment` in `config/project.json` → that file.
3. **Legacy project** (no such files) — there is no legacy mobile equivalent of
`QA_TARGET_URL`; ask the user for the app path/package and device capabilities instead of
guessing.
From the environment file's `mobile` block (see `docs/configuration.md`): `platformName`
(`Android`/`iOS`), `automationName` (`UiAutomator2`/`XCUITest`), `app` (path to a local
`.apk`/`.ipa`) **or** `appPackage`+`appActivity` (Android, already installed) / `bundleId`
(iOS, already installed), `deviceName`, `platformVersion`, optional `udid` (a specific real
device). `defaults` and `users` from the same environment file are the test data for the run,
same convention as test-execution: a spec step like "login as expired_user" means
`users.expired_user`; a user without `password` uses `defaults.password`. A
`{ "envSecret": "NAME" }` value is typed only with the wrapper's `send-keys --text-env NAME`
(see Tools), which reads `NAME` itself — never read `.env` and never print it.
Naming an environment that has no file is an **error**: stop and list the files in
`environments/`. Never silently fall back to another environment, and never invent capability
values that aren't in the file. A spec naming a user that is not defined for the active
environment is **BLOCKED** (report the missing handle), never improvised. Record the active
environment name and the resolved `platformName`/`deviceName` in `report.md`.
**Capabilities file.** Build each session's W3C caps from the `mobile` block, starting from
`templates/sample-android-caps.json` or `templates/sample-ios-caps.json` in this skill. Every
caps file you write sets `"appium:noReset": true`. Appium's default (`noReset: false`) clears
the app's data on session start, with no prompt. Never set `"appium:fullReset": true` or
`"appium:noReset": false` without the user's explicit approval for that run; `appium_client.js`
refuses such caps unless given `--allow-reset`, and adds `noReset: true` when it is missing. In parallel mode
no one can approve, so a spec or `mobile` block that asks for a reset is BLOCKED.
## Tools
Per-tool setup, install, and usage details live in this skill's `references/` folder. **Read
the relevant file BEFORE the first use of that tool in a session**, and again whenever a
command behaves unexpectedly. There are two ways to drive a session — pick whichever the
project already uses (or the simpler one, raw REST, when neither is established):
- **`${CLAUDE_PLUGIN_ROOT}/skills/mobile-testing/references/appium-server-cli.md`** — start the
Appium server, install platform drivers, and drive a session with raw `curl` calls against
the W3C WebDriver REST API (create session, find element, tap, type, screenshot, swipe,
back, close). No extra project dependency beyond `appium` itself.
- **`${CLAUDE_PLUGIN_ROOT}/skills/mobile-testing/references/appium-client-wrapper.md`** — drive
a session through the bundled `scripts/appium_client.js` wrapper (simple flag-driven
subcommands, one JSON line per call). Requires the project to have `webdriverio` installed
(`npm install -D webdriverio`).
Type every secret (password, OTP, token) with the wrapper's `send-keys --text-env <NAME>`,
which reads `NAME` from the environment or `.env`. Never put a secret value on a command line:
not in `--text`, and not in a `curl` body.
Always-on rules (full details in the files above):
- **Parallel runs MUST each target their own device/emulator** (own `udid`/AVD/simulator) —
sessions on the same physical device collide. Unlike headless browser sessions, mobile
concurrency is bounded by **available emulators/devices on the machine**, not just CPU/RAM —
expect far fewer concurrent sessions than test-execution's ~6-8; often just 1-2 unless
multiple emulators/devices are actually provisioned.
- App/device errors surfaced in the Appium server log or in `adb logcat` count as defects even
if the UI looks fine.
- Specs may include **`api:` / `db:` steps** (verify via API, check a DB row, seed data) —
execute them via the **api-integration** / **db-integration** skills' runner scripts, from
the project's `integration/` catalog (read the relevant SKILL.md before the first such
step). Only cataloged entries may run; undefined names are BLOCKED, never improvised. Pass
the resolved environment name via `--env <name>` — sequential mode included, not just
parallel. Specs may also include **`kb:`** steps (advisory only, never PASS/FAIL) — execute
via the **ask-kb** skill's runner script.
- Helper scripts (all in `${CLAUDE_PLUGIN_ROOT}/skills/mobile-testing/scripts/`, each prints
one JSON line): `preflight.js` — check all tools in one call at session start; `init_run.js
--sessions a,b` — create the whole execution tree (use instead of mkdir chains); `merge_run.js
--run-dir <dir> <evidence paths...>` — copy bug-evidence screenshots into
`bugs/screenshots/` during MERGE.
## Execution output layout
Every run writes ALL its data under one timestamped folder (created in the current project) —
nothing scattered elsewhere.
```
executions/
└── execu_<YYYY-MM-DD_HH-MM-SS>/ # one folder per execution
├── report.md # final report [orchestrator]
├── mobile-sessions/
│ └── <session>/ # one per device session [subagent owns its own]
│ ├── logs/ # Appium server / adb logcat captures
│ └── screenshots/ # every scenario screenshot
└── bugs/
├── bug-list.md # consolidated defects [orchestrator]
└── screenshots/ # copies of bug-evidence shots
```
Ownership:
- **Orchestrator (you, the main agent):** create `execu_<ts>/` + the `mobile-sessions/` and
`bugs/` skeleton, pick the timestamp, assign each subagent its `SESSION_DIR` and target
device, write `report.md`, and build `bugs/` (merge `bug-list.md` + copy the bug-evidence
screenshots each subagent flagged).
- **Subagent (per session):** writes ONLY into its own
`mobile-sessions/<session>/{logs,screenshots}` and returns the screenshot paths that prove
each defect. Dispatch the bundled **`mobile-qa-executor`** agent for this.
- Sequential mode uses one session: run `init_run.js` with no `--sessions` and it is named
`run` (`mobile-sessions/run/`). The label `default` is refused.
## Modes
Pick the mode from how the user invokes the run. **Sequential is the default.** Switch to
**Parallel** only when they explicitly ask for a parallel / fast / regression / autonomous run
**and** confirm more than one device/emulator is actually available.
### Sequential mode (default) — human-in-the-loop
Follow this loop and STOP for approval at each checkpoint. Do not skip ahead.
1. **UNDERSTAND** — Restate what we're testing (app, platform, device) and the acceptance
criteria in your own words.
→ Checkpoint: wait for the user to confirm scope.
2. **PLAN** — List the test scenarios (happy path, edge cases, negative cases) as a numbered
plan. Do NOT open a session yet.
→ Checkpoint: wait for the user to approve the plan.
3. **EXECUTE** — Run scenarios one at a time. After each scenario, report PASS/FAIL with
evidence (screenshot + observed vs. expected).
→ Checkpoint: pause after each scenario before moving to the next.
4. **REPORT** — Create `executions/execu_<timestamp>/` with `init_run.js` (single session
`run`), save screenshots/logs under `mobile-sessions/run/`, then write `report.md` +
`bugs/` there.
Summarize results as a defect list (format below). Optionally generate an interactive
`extent-report.html` next to `report.md` via the **extent-report** skill.
### Parallel mode — autonomous
Run end to end WITHOUT stopping for per-checkpoint approval; present the final report when
done.
1. **SETUP** — Create `executions/execu_<timestamp>/` with `mobile-sessions/` and `bugs/`
subfolders (see Execution output layout above).
2. **LOAD** — Read the planned test files (one bucket per file). By convention these live in
`test/mobile-suite1/` (or wherever the user keeps their mobile specs). Stateful scenarios
stay grouped and run sequentially within their own file.
- **First run:** if no `test/mobile-suite1/` specs exist yet, copy the bundled samples from
`${CLAUDE_PLUGIN_ROOT}/test/mobile-suite1/` into `./test/mobile-suite1/` as an editable
starting point, and tell the user to adapt them to their app before a real regression.
3. **DISPATCH** — Spawn one **`mobile-qa-executor`** subagent per test file, each targeting its
own device/emulator, injecting its `SESSION`, `SESSION_DIR`
(`…/mobile-sessions/<session>`), `WORKING_DIR`, `ENVIRONMENT`, `MOBILE_CAPS` (the resolved
`mobile` block), `TEST_DATA`, and `TEST_SPEC`. `TEST_DATA` is the environment's `defaults` +
`users` JSON (secrets left as `{ envSecret }` refs — the executor resolves them only at use
time and never prints them). Launch them in a single batch. Confirm device availability
first — do not dispatch more subagents than there are devices/emulators to run them on.
4. **MERGE** — Collect each subagent's report; write the final `report.md` and build `bugs/`
(`bug-list.md` + copy the bug-evidence screenshots each subagent flagged) inside the
execution folder. Use the defect format below. Optionally generate an interactive
`extent-report.html` next to `report.md` via the **extent-report** skill.
5. **PRESENT** — Show the merged summary.
Autonomy boundary (applies in parallel mode): still never modify app source, never create real
accounts or complete a real purchase, never print secrets, never use real personal data (use
disposable values like `qa.tester@example.com`), and never run a destructive device command
(`adb uninstall`, `adb shell pm clear`, `adb reboot`, `adb root`, `xcrun simctl erase`, or
similar) — a test run only installs/launches/exercises the app under test and tears down its
own session. If the overall scope is ambiguous, ask once before dispatching; otherwise proceed
without pausing.
## Defect reporting format
- **Title** — concise, action-oriented
- **Steps to reproduce** — numbered, deterministic
- **Expected** vs **Actual**
- **Severity** — Critical / High / Medium / Low
- **Evidence** — screenshot filename, Appium server / adb log notes
## Rules
- Think out loud: state your reasoning before each action so the user can follow the chain.
- In **sequential mode**, never proceed past a checkpoint without an explicit "go" / "approved".
In **parallel mode**, do not pause for checkpoints — run autonomously within the autonomy
boundary above.
- Resolve config from `config/project.json` and `environments/<env>.json` only. Never read
`.env`: the bundled scripts read the values they need from it themselves (`appium_client.js
send-keys --text-env` for `envSecret` fields, the runners for `api:`/`db:`/`kb:`). Never
print, log, or pass secret values (tokens, credentials, envSecret targets) anywhere.
- Never modify application source code. You may write test notes/artifacts only.
- Never run a destructive device command (uninstall, wipe/clear data, reboot, root/jailbreak
actions) against the target device/emulator — the run's footprint is limited to installing,
launching, exercising, and closing the session for the app under test.
- If a step is ambiguous — including which device/emulator to target — ask, don't guess.
Files in this package (13)
- SKILL.md 12 KB
- references/appium-client-wrapper.md 5 KB
- references/appium-server-cli.md 7 KB
- scripts/appium_client.js 11 KB
- scripts/appium_client.test.js 13 KB
- scripts/init_run.js 4 KB
- scripts/init_run.test.js 6 KB
- scripts/merge_run.js 1 KB
- scripts/merge_run.test.js 3 KB
- scripts/preflight.js 1 KB
- scripts/preflight.test.js 3 KB
- templates/sample-android-caps.json 1 KB
- templates/sample-ios-caps.json 1 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · mhmdelgazzar/agentex | 100 | MIT |
| proffesor-for-testing/agentic-qe | 100 | MIT |
| irahardianto/awesome-agv | 100 | MIT |
| thedaviddias/front-end-checklist | 100 | MIT |
| arozumenko/sdlc-skills | 91 | MIT |
| j4flmao/agent-skills | 90 | MIT |
Database snapshot: 13.11.2026 · package version 699402db2284 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100test-execution
Run test specs against an application and report defects, routing each step to its driver (browser via playwright-cli, API calls, database checks, knowledge-base questions, UI design checks). Use whenever the user wants to test a website, web app, or API for defects (happy… - 100appium-skill
Generates production-grade Appium mobile automation scripts for Android and iOS in Java, Python, or JavaScript. Supports real device and emulator testing locally and on TestMu AI cloud with 100+ real devices. Use when the user asks to automate mobile apps, test on Android/iOS,… - 100mobile-test
Test mobile apps (Android/iOS) — drive a real Android device or emulator via adb, install builds, capture screenshots and logs, generate mobile-specific test cases and checklists. Use when the user is testing a mobile app, APK, Android or iOS application. - 100appium
Expert Appium mobile automation covering iOS, Android, and cross-platform UI testing. Use when automating mobile app workflows, end-to-end device testing, or configuring Appium drivers. - 100test-mobile
Drive the mobile app on an iOS simulator or Android emulator against this checkout's local stack: keep the development client in step with the native fingerprint, start Metro, sign in for real and capture evidence with `agent-device`. Use to see a mobile change working, not just tested. - 100mobile-testing-appium-maestro
Use this skill when automating native iOS and Android mobile user flows and UI assertions on simulators and physical devices.