ai-mobile-tester
This server lets AI assistants write and run deterministic mobile UI tests (Android & iOS simulators, native & WebView) from natural language, using reusable YAML flows with self-healing locators and HTML reports.
Author & validate flows: write YAML flows (tap, input, assert, scroll, capture, conditional branching), statically validate them offline with
validate_flow(schema, fragile selectors, credential warnings, variable order).Run flows deterministically:
run_flowexecutes a flow on a device without AI per run, self-heals drifted native locators, produces an HTML report, JUnit XML, and exit codes for CI.Observe screens:
observe_ui(compact native snapshot with[ref]handles),describe_element(all attributes & indexes),observe_webview(DOM snapshot by CSS selector).Drive WebViews:
webview_tap,webview_input,switchContext— CSS/text selectors, on both Android (WebView debugging) and iOS (Web Inspector).Interact with devices: tap, tap_xy, long_press, swipe, scroll, type_text, press_key (platform-neutral keys), plus device/app management: list/connect devices, launch/install/uninstall/clear/force-stop apps.
Assert & wait: assert_visible/not_visible/text, is_element_visible, wait_for_element/text/activity, capture runtime values into variables for later assertions.
Cross-platform flows: one YAML flow runs on Android or iOS (via
platform:or device selection), withwhen: { platform }branching.Authoring diagnostics:
check_testabilityaudits Compose testTag coverage; failed lookups list what was on screen.Handle flaky screens:
dismiss:auto-dismisses dialogs during waits; escape hatches liketapXYfor screens that can't be read.CI integration: headless CLI (
run,validate) with exit codes and JUnit output.
Enables automated UI testing of Android native and WebView apps on devices/emulators via ADB, including UI observation, deterministic YAML flow replay, and self-healing locators.
Enables automated UI testing of iOS native and WKWebView apps on simulators via xcrun simctl and WebDriverAgent.
Provides Compose testTag coverage checks to help make Jetpack Compose UI elements addressable for automated testing.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ai-mobile-tester Write a UI test that logs in and verifies the welcome screen"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ai-mobile-tester
An MCP server that lets AI assistants (Claude Code, Cursor, Windsurf, …) write and run mobile UI tests by natural language — Android and iOS simulators, native and WebView/hybrid — with no Appium and no Chromedriver. Android drives over ADB; iOS simulators over xcrun simctl + WebDriverAgent, and their WKWebViews over Apple's Web Inspector protocol. You describe a test in plain English; the assistant captures the screen, authors a durable YAML flow, then replays it deterministically with self-healing locators (native) and an HTML report.
One flow can target both platforms: leave platform: out and it runs on Android by default, or on iOS when given a simulator UDID (device_id for run_flow, --device for the CLI), with when: { platform } for the steps that genuinely differ. A flow that only ever runs on iOS declares platform: ios instead, and then uses the only booted simulator on its own. iOS is simulators only — no physical-device support.
How it works
Observe — the assistant captures a compact, token-frugal snapshot of the screen —
observe_ui(native) orobserve_webview(WebView) — with stable selectors and[ref]handles.Author — it writes a YAML flow (tap / input / assert / scroll steps) from those selectors. You keep the flow file.
Validate —
validate_flowlints the flow offline (schema, fragile selectors, undefined variables) — no device needed.Run —
run_flowexecutes it deterministically on the device (no AI per run), self-heals drifted native locators, and writes an HTML report.
The YAML flow is the durable artifact: author once with the assistant, then replay forever (CI, daily, …) at zero AI cost and with no drift.
Related MCP server: Argent
Prerequisites
Node.js 18+
For Android: the Android SDK Platform Tools —
adbin your PATH (download) — and a device with USB debugging enabled, or a running emulatorFor iOS: a Mac with the full Xcode and an iOS simulator runtime — see ios-testing.md. Running an iOS flow needs no Android SDK, but
list_devicesfails withoutadb(find a simulator's UDID withxcrun simctl list devicesinstead), andinitwarns thatadbis missing.For WebView / hybrid apps: the app's WebView must opt in to remote debugging — on Android
WebView.setWebContentsDebuggingEnabled(true)(debug builds usually have it), on iOSWKWebView.isInspectable = true(iOS 16.4+; Safari needs no opt-in). iOS also needs the optionalappium-remote-debuggerclient — see ios-testing.md
Install & set up
npm install -g ai-mobile-tester
npx ai-mobile-tester initThe wizard checks adb, registers the MCP server with Claude Code (via claude mcp add, writing ~/.claude.json) and Claude Desktop (its claude_desktop_config.json, if installed), and installs the /run-test slash command. Restart Claude Code / Claude Desktop and the tools are available.
Manual / advanced MCP configuration
init is the easy path, but you can register the server by hand for any MCP client. The server runs on stdio via the serve subcommand:
{
"mcpServers": {
"ai-mobile-tester": { "command": "npx", "args": ["-y", "ai-mobile-tester", "serve"] },
},
}For Claude Code you can also run claude mcp add --scope user ai-mobile-tester -- ai-mobile-tester serve. For the most stable setup, install globally (npm i -g ai-mobile-tester) and point at ai-mobile-tester serve (or the absolute node <prefix>/dist/index.js that init writes) — the npx form re-resolves from a cache that npm can garbage-collect.
Example — a native flow
appId: com.example.app
env:
TEST_USER: "you@example.com"
TEST_PASSWORD: "" # keep the secret out of the file; pass it at run time (--env TEST_PASSWORD=…)
---
- launchApp
- tapOn: { id: login_button }
- inputText: { into: { id: email }, text: "${TEST_USER}" }
- inputText: { into: { id: password }, text: "${TEST_PASSWORD}" }
- tapOn: "Sign in"
- assertVisible: "Welcome"Example — a WebView flow
appId: com.example.shop
env:
TEST_USER: "you@example.com"
TEST_PASSWORD: "" # keep the secret out of the file; pass it at run time (--env TEST_PASSWORD=…)
---
- launchApp
- switchContext: "WEBVIEW_com.example.shop@shop.example.com"
- assertVisible: { css: "#email" }
- inputText: { into: { css: "#email" }, text: "${TEST_USER}" }
- tapOn: { css: '[data-testid="signin"]' }
- assertVisible: { css: ".order-summary" }
- switchContext: NATIVE_APPValidate offline, then run it:
/run-test path/to/flow.yaml…or just ask the assistant to run it.
Run in CI (no AI)
Once a flow exists, run it headlessly — no Claude, no MCP, just a device (Android through adb, or a booted iOS simulator):
ai-mobile-tester run flow.yaml --junit results.xml # exit 0 pass · 1 fail · 2 could-not-run
ai-mobile-tester validate flow.yaml # offline pre-checkPortable to any CI (GitHub Actions, MacStadium, GitLab, …). See docs/ci-runner.md.
Documentation
Authoring UI tests — the full workflow — start here.
YAML flow format reference — every command and selector.
Waits, timeouts and
dismiss:— which commands poll, whatoptionalandtimeoutMsreally cost, and thedismiss:rules.When the screen never idles —
ERROR: could not get idle state: what it means, how to confirm it, and the escape hatches.Testing WebView / hybrid apps — drive WebViews by CSS selector, on both platforms.
Testing iOS apps (simulators) — prerequisites, WebDriverAgent, divergences from Android, and the WebView setup.
Compose testability — make Jetpack Compose elements addressable with
testTags.Running flows in CI — exit codes, secrets, JUnit, a portable recipe.
MCP tools
Flow engine:
Tool | Description |
| Compact, token-frugal snapshot of the native screen (actionable elements get a |
| Every attribute of the element(s) a selector matches — the state flags |
| Lists the app's WebView pages and returns a compact DOM snapshot of the richest, by CSS selector |
| Tap a WebView element by css/text, then return the updated DOM (interactive observe→act→observe) |
| Type into a WebView field by css/text, then return the updated DOM |
| Type into a field (optionally focus it by selector first) |
| Statically validate a YAML flow (schema + lints), no device needed |
| Run a validated YAML flow deterministically; self-heals native locators; writes an HTML report |
| Report Compose |
Device & app: list_devices, device_info, connect_device, launch_app, install_apk, uninstall_app, clear_app_data, force_stop.
Interaction: tap, tap_xy, tap_element, long_press, swipe, scroll_down, scroll_up, type_text, press_key.
Observation & assertions: take_screenshot, dump_ui, describe_element, find_element, get_current_activity, is_element_visible, assert_visible, assert_not_visible, assert_text, wait_for_element, wait_for_text, wait_for_activity.
Development
git clone <your-fork> ai-mobile-tester && cd ai-mobile-tester
npm install
npm run build
npm test # the test suite
npm run lint && npm run format:checkWhat's new in 3.0.0
Cross-platform flows: write one YAML flow that runs on Android or iOS. Neutral
pressKeynames (ENTER,TAB,DELETE,HOME, …) and friendly permission names (camera,microphone,location, …) resolve to the right platform-native key automatically, and awhen: { platform }clause onrunFlowlets a shared flow branch for a platform-specific step. See yaml-flow-format.md and ios-testing.md.
What's new in 3.1.0
WebView taps dispatch real touches:
tapOnin a WebView now sends a real trusted CDP touch event instead of a syntheticclick(). Elements must be unoccluded to actuate. After a WebView tap that should launch a native screen, use the newassertActivitycommand (Android-only) to verify the Activity transition happened — a content-onlyassertVisiblecan pass even if the native transition failed.
What's new in 3.2.0
dismiss:auto-dismisses async dialogs. A config-level list of selectors was checked at every step boundary (native only, skipped inside a WebView context) and the first visible match tapped — for permission prompts, rating nags, or promo interstitials that appear unpredictably. Dismissals show up as a run-level annotation in the report header, not as numbered steps, so step indices stay diffable. (Since 3.5.0 the watcher also fires during a wait, not only between steps — see below.)Conditional branching:
runFlow'swhen:now also accepts{ visible: <selector> }/{ notVisible: <selector> }alongside the existing{ platform }, plus anelse:for the other side. Useelse, not two adjacentwhens — see yaml-flow-format.md. Note: steps inside avisible/notVisible-guarded branch don't self-heal (a{ platform }guard still does for an inlinecommands:branch — afile:subflow is always strict-only).observe_uino longer hands back a bare empty tree on a continuously animating screen — it retries briefly, then returns an actionable diagnostic naming the likely cause instead of silence.
What's new in 3.3.0
tapandinput_textwait for the screen to settle before returning their snapshot. Previously they captured immediately after acting, so the tree you got back could still be the screen you just left, or a half-drawn one mid-transition. They now re-capture until the tree has both changed and stopped changing. When it never settles you get the newest snapshot plus a note saying which test failed — either the screen kept moving (a live animation), or it never changed at all, in which case the note says plainly that the snapshot is the screen from before your action. Costs one extra UI dump per action, two when it never settles;observe_uiis unchanged.
What's new in 3.4.0
WebView tools now work on iOS simulators.
observe_webview,webview_tap,webview_input, andswitchContext: "WEBVIEW_<bundle-id>@<url-match>"drive WKWebViews over Apple's Web Inspector protocol, with the same YAML grammar as Android. Needs the optionalappium-remote-debuggerclient (npm install --no-save appium-remote-debugger) and the target app to setWKWebView.isInspectable = true(iOS 16.4+; Safari needs no opt-in) — see ios-testing.md for the full setup and its honest limits (one simulator at a time, taps need exactly one on-screen WebView, the page must not be pinch-zoomed).
What's new in 3.5.0
The runner no longer reports green for a run that never happened.
uiautomator dumpprintsERROR: could not get idle state.and exits 0, and the dump file was never deleted first — so the follow-up read silently returned the previous dump. A 19-minute-old tree of a different screen was measured being served as the current UI, and selector resolution,assertVisible,assertNotVisible,tapOnand the self-healing locator store all consumed it. That produces false passes as readily as false failures. A refused dump now fails with a named cause instead of returning a tree, andrun_flowreports it asscreen never idlerather than asnot visible: #your_selector— a misattribution that cost one reporter most of a session. See When the screen never idles.⚠ Runs will fail more often after upgrading, and that is the fix working — not a regression. Two shapes of flow change colour, and both were passing on something untrue:
A screen whose UI tree could never be read used to be tested against a stale tree from an earlier screen. Those steps passed or failed at random; they now fail honestly, with the cause named and the escape hatches listed in the error itself.
A flow whose
assertNotVisiblepassed at 300ms because the element had not rendered yet will now wait for it, find it, and fail. That assertion was winning a race, not checking the screen. If the step means "this never appears at all", give it a short explicit budget (assertNotVisible: { id: error_banner, timeoutMs: 1000 }); if it was standing in for "wait for the spinner to go away", it now does what it always read like.A selector that named nothing native — a
cssoutside a WebView,{ index: 0 }, anid/textthat a${VAR}expanded to nothing — used to match every node and be answered with the first one.assertVisiblepassed without looking,tapOntapped the root node's centre, andscrollUntilVisiblewith acsselement inside aWEBVIEW_context returnedpassedin 1ms having never scrolled. Every native lookup now fails withmatches any node on the native path — needs id or text, before it takes a dump. Give the step anidortext, or move it into the WebView context wherecssbelongs.
Waiting for something to go away is a real wait.
assertNotVisiblepolls until the element is gone instead of answering off one snapshot in ~300ms while every other lookup polled ~11s. NewwaitFor: { element, state: visible | notVisible, timeoutMs? }states a synchronisation point explicitly (and never self-heals, so the locator is taken literally). New per-step and flow-leveltimeoutMs— the hard-coded 10s fitted no real app. Precedence is step → flow default → 10000, and an explicit value beatsoptional's short cap in both directions. The flow default reaches every polling wait,assertActivityincluded;scrollUntilVisibleis the one deliberate exception, because its budget funds scroll gestures rather than one lookup. The full table, with harness-measured costs, is in Waits, timeouts anddismiss:.dismiss:now fires during waits, not only between steps.tapOn/assertVisiblespend up to 10s polling inside a single step, so a dialog that rendered mid-poll was never dismissed and the step failed with the dialog correctly declared. The watcher now runs on every poll tick, reusing that tick's snapshot — zero extra UI dumps — capped at 3 dismissals per wait so a mis-aimed entry cannot become a tap storm. The rule that goes with it: never pointdismiss:at an element an explicit step also touches.Escape hatches for screens that cannot be read.
tapXY: { x, y }/{ xPct, yPct }taps a raw coordinate from YAML (percentages survive a change of device);stopAppandlaunchApp: { forceStop: true }give a cold start withoutclearState's data wipe, on both platforms; andget_current_activity/assertActivity— the only assertion that never reads the UI tree — now falls back throughmResumedActivity→mCurrentFocus→mFocusedApp→topResumedActivityinstead of returning null on Android 16.
What's new in 3.6.0
Three authoring diagnostics. Nothing about how a flow runs changes — this release is about what you are told while writing one.
A failed lookup now says what WAS on screen.
not visible: #navigation_rebrand_explore, after twelve seconds of silent polling, names the one thing that is not there and nothing that is — so a wrong selector, a modal covering the screen, and the wrong screen entirely all read identically. Every native miss now appends a second line listing the screen's addressable nodes:not visible: #ghost on screen (3): #email_field, #login_button, #titleYou see it wherever the failure surfaces: inline in
run_flow's and the CLI's summary — 3.6.0 inlines the failing step's error for any failure, not only a refused dump — as well as inreport.htmland the JUnit XML. The interactivewait_for_element/assert_visibleMCP tools do not carry it yet.It reuses the snapshot the poll loop already captured, so it costs zero extra UI dumps — and on a screen that will not dump at all, taking another one is exactly what would fail while trying to explain the failure. Ids first, text where there is no id, both clamped to 40 characters, capped at 12 entries with identical handles collapsed (
#row_item ×30) so a whole list screen cannot turn one failure into a token bomb (~600 characters worst case). Read the(N)in the header to tell an overlay from a whole screen — it is the true node count. A dialog or bottom sheet has few addressable nodes, fits inside the cap and is listed in full; a large(N)is a whole screen. Do not read the+N moretail that way: the collapse means a 48-node list screen shows 9 entries and no tail at all. Applies totapOn,assertVisible,inputText,waitFor: { state: visible },scrollUntilVisibleand — since 3.7.0 —capture; not toassertNotVisible, whose failure already means the element is on screen. A WebView miss keeps its own text — with one exception,scrollUntilVisible, which has no WebView branch and so reports the native tree it actually searched even inside aswitchContext.New
describe_elementtool: "is this state even assertable?" in one call.observe_uirenders a compact view and hides most attributes, so the only way to find out whether a control exposes its state was to drop to rawuiautomator dumpXML. An entire test was once authored around "the heart turns red" before anyone discovered the app never reported that state at all. One call would have shown it:"Favorite" — 1 match. match index: 0 ... contentDesc: "Favorite" checkable: false checked: false selected: false ...(Abridged — the real block lists all 17 attributes plus bounds;
...marks the 13 elided here.)Nothing flips between the two states, so no assertion can be written on it — a fact worth five seconds rather than a session.
describe_elementreturns every attribute the dump carries, plus exact bounds, and one block per match with theindex:a flow selector would use — so an ambiguous selector shows all its candidates instead of silently picking the first. Read-only and native. It matches onid/text, and accepts the sameenabled/checked/focused/selectedqualifiers a flow selector does — so theindex:it reports is the one that selector will get. See authoring-tests.md.validate_flowcatches a password committed inenv:. Flow files get committed, and so do the credentials in them — this repository's own example flow carries a plaintext password, which is how the rule earned its place.validate_flownow warns when anenv:default is a non-empty literal under a credential-shaped key (password,passwd,passphrase,passcode,pwd,secret,token,credential, pluskeyonly in compound form likeapi_key/apiKey), and tells you to blank the default and pass the real value at run time. Barekeyand barepassare deliberately excluded —KEY_CODE,SORT_KEYandBOARDING_PASSare ordinary flow variables, and a false positive has no remedy but renaming yours. It never warns on a${VAR}reference or on the empty default ci-runner.md tells you to commit — warning on the recommended pattern is how a validator teaches people to ignore it. A non-empty placeholder is not exempt: nothing about the value is inspected, so"changeme"warns too. Key names only: no entropy scoring, no guessing from the value's shape, and the value is never echoed into the warning. It is a warning, not an error; by the time you read it the value is already in your history, and the follow-up is to rotate it.
What's new in 3.7.0
capture: assert on the value that was actually on the screen. A test that favourites the first vehicle in a re-ranking list and then checks the Favorites tab could previously express nothing stronger thanassertVisible: 'View \d{4} .*'— and on any account that already has favourites, that is already true before the test runs. It passed with the feature completely broken.capturebinds a string read off the screen to a flow variable that every later step can use:- capture: { from: { id: toolbar_split_title }, as: VEHICLE } - tapOn: { id: favorite_button } - tapOn: { id: favorites_tab } - assertVisible: { text: "View .*${VEHICLE}.*" } # the car you actually favouritedThe full form is
{ from: <selector>, as: NAME, attr?: text | contentDesc, redact?: true }.fromis an ordinary selector with the same polling,timeoutMsbudget and self-healing asassertVisible.asmust match^[A-Z][A-Z0-9_]*$, and that is enforced, not advised. Omitattrand it readstext, falling back tocontentDescwhentextis empty; writeattrout and it reads only the attribute you named — naming one and being answered with a different one is the quiet substitution this command exists to remove, so an explicitattr: texton an icon whose label lives incontentDescfails where omitting it would have worked. Scope is flow-wide and forward-only, and it crossesrunFlowboundaries in both directions: a parent's capture is visible inside a sub-flow, and a sub-flow's is still bound after it returns. See yaml-flow-format.md.An empty read fails the step rather than binding nothing.
""would turntext: "View .*${VEHICLE}.*"intoView .*.*— a pattern matching any card on the screen, so the run goes green while the assertion has quietly become the tautology this feature exists to remove. A capture whose element is on screen but whose attribute is empty fails, and the report row says(element found, value empty)so it does not read as a missing element.optional: trueis refused at parse time for the same reason: a skipped capture leaves the name unbound and every later step then fails on an unresolved variable — correct, but bewildering.captureis native only; inside aswitchContext: "WEBVIEW_…"it fails instead of quietly reading the native tree behind the page, which would bind a real-looking wrong value.⚠ Behaviour change: an interpolated value is now matched literally in a native
id/text.idandtextare regex full-match, so a${VAR}used to be spliced in as a pattern. A real UI string —$29,499,2020 or newer (19,125)— compiles to a perfectly valid regex that matches nothing, and the step fails as though the element were absent, with nothing in the message saying the value was read as a pattern. Since 3.7.0 the substituted value is escaped so it matches itself and nothing else.The rule is by field, not by origin, so
${VAR}means the same thing wherever its value came from — anenv:default,--env,process.envor a capture:escaped: a native
id, a nativetext.never escaped:
css(a CSS selector, not a regex — a backslash corrupts it), atextselector inside a WEBVIEW context (the DOM path compares with===, exact equality),inputText'stext:(this is the string typed into the app), and everything that is not a regex-matched selector field (appId,tapXY,switchContext).
The pattern you wrote around the reference is untouched, so
{ text: "View .*${VEHICLE}.*" }keeps its own.*live and only the value goes in literal.${VAR:raw}is the opt-out, applied per reference, for a variable whose value really is meant as a pattern. What can change colour: a flow whoseenv:default was deliberately written as a regex and used in a nativeid/text—validate_flownow warns on exactly that combination, so those flows name themselves offline rather than on a device. It also fixes a latent bug in the other direction: an email address in atext:selector had its dots matching any character, and now matches itself.validate_flowrefuses a${VAR}used above thecapturethat binds it. No execution order resolves it, so it is an error — caught offline, before a device, an app install and eleven steps have been spent. The line between error and warning is drawn on how many runs the flow is wrong on: wrong on every path is an error, wrong on some paths is a warning, wrong on no path is silence. So a capture inside arunFlow when:branch (or arepeatwhosetimesmay be0) still defines the name and only warns — that branch may well run, and a fatal false positive stops a working flow dead. Awhen:/else:pair where both sides capture the same name is bound on every path and stays silent. Capturing the same name twice warns, naming both steps; so does acaptureinside a WebView context.optional:and a malformedas:are hard parse errors.An empty
env:default does not buy silence, and that is the subtle one.NAME: ""is the shapedocs/ci-runner.md#secretsteaches for a value injected at run time, so it is the idiom most flows carry — and treating a declared-but-blank key as "defined" would make every check above inert on exactly the flows they were written for. If the branch holding the capture never runs,VEHICLEstays"",text: "View .*${VEHICLE}.*"collapses toView .*.*, and the step passes against any card on the screen. It warns rather than errors, because--env VEHICLE=…legitimately fills a declared key and a fatal error would block that run. A flow that declaresNAME: ""and captures nothing is untouched.One gap, stated rather than papered over: a
dismiss:entry that references a captured name is not covered by the ordering checks — they walk the step list, anddismiss:is config. At run time such an entry stands itself down and warns at every step boundary until the capture lands, so it is noisy rather than silent, butvalidate_flowwill not tell you offline.A "selector without an id is fragile" warning no longer fires on a
textthat interpolates a${VAR}. Asserting on a captured value requires a text selector by definition — the value is only knowable at run time — so the warning was unsatisfiable on the pattern this release recommends. It still fires on a plain text-only or index-only selector, where an id genuinely is the better choice.Captured values are reported — and two of the three places are new machine-readable output you may already be parsing. The capture's own row in
report.htmlgainsVEHICLE = 2021 Honda Civic (read from text). The JUnit XML (--junit) gainscaptured NAME=valuein that step's<system-out>, next to the existinghealednote. Andrun_flow's summary text gains acaptured: NAME=value, …line on a failed run only —report.htmlis a path a model cannot open, and that string is returned on every single call, so a passing run stays quiet.redact: truestores***in the record itself, so no renderer can leak a redacted value by forgetting a flag; the real value still reaches later steps. There is noreport.json— the machine-readablerun_flowpayload remains deferred work, and this release deliberately did not invent a partial one, so--junitis still the machine-readable artifact that exists.
What's new in 3.7.1
iOS runs no longer abort when their WebDriverAgent session is replaced. WDA holds one session at a time, and a session that has been replaced answers
404with the error codeinvalid session idand the messageSession does not exist. The client already had a retry for exactly that case — but it looked for the code's wording inside the message, which never contains it, so the retry never ran and the run died withWDA GET /session/<id>/window/size failed: Session does not exist. It shipped behind a green unit test whose fake WDA copied the code into the message field, which a real WDA never does. Recovery now reads the structured error code, and still retries only once. That is safe because WDA rejects a command sent on a dead session before running it (measured: a tap sent on a dead session left an on-screen counter untouched).Tool calls made during a run share its WDA session instead of ending it. The server builds a fresh driver for every tool call, and each one used to create a session of its own — so an
observe_uiortapissued while a backgroundedrun_flowwas still running ended that run's session. Every call and run in the server process now shares one session per WDA, and clients that hit a dead session at the same moment create one replacement between them, not one each. Measured against a simulator: 201 interleaved calls from several clients ran on a single session with no failures, where the same kind of loop with a session per client created a new session on every one of its 80 calls. A second process driving the same simulator — another MCP server, Appium, a script — can still replace the session; that is recovered from, not prevented. See ios-testing.md.WDA is never reinstalled because it was slow to answer. A
/statuscheck that timed out used to be read as "WDA is not running" and answered with a reinstall, which ends every session and sends the app under test to the background — after which later steps silently read the home screen. But/statuswaits behind a UI dump already in progress: on a 1,500-element page the dump took 3.8s, and a/statussent meanwhile missed its 2-second budget against a perfectly healthy WDA. A timed-out check is now checked again, so WDA gets up to 32s in all (the 2s check, then a 30s wait); a WDA that still does not answer is an error naming the command that restarts it; and only a WDA that is actually down — a refused or reset connection, or an error answer from/status— is reinstalled. WDA is also confirmed once per tool call or run, instead of before every one of the hundreds of commands a long flow sends. ⚠ Behaviour change: if WDA genuinely dies partway through a run, the run fails at the step that met the dead WDA — withdismiss:configured too — and nothing in that run brings WDA back, because a relaunch would send the app under test to the background and later steps would read the home screen. Depending on where the crash lands, the step's error is a connection failure (fetch failed) or an error containingWebDriverAgent stopped responding partway through this run or tool call(inside a WebView context, awhen:check or the WebView tap bridge, it arrives wrapped in their own prefix). The next run or tool call relaunches WDA.A run says when its session was recreated. Recovery is silent by design, so a run whose WDA session was replaced now carries one warning — in the
run_flowsummary, the CLI output andreport.html— saying how many times, without failing a flow that recovered. Relatedly, adismiss:watcher whose screen capture fails for any reason now warns that it could not look. It used to warn only for a screen that never idles, so a watcher blinded by a WDA error said nothing at all. This second change is in the platform-neutral runner, so Android runs can show that warning too.
What's new in 3.7.2
ai-mobile-tester runruns an iOS flow without--device. The CLI used to pick its device through adb before it looked at the flow'splatform:, so aplatform: iosflow could only run with an explicit--device <udid>. Without one it failed in one of four ways, depending on the machine: with one Android device attached, the adb serial was handed to the iOS driver (No iOS simulator with UDID <serial>); with several, it asked you to pick one with--device <serial>; with none, it said to start an Android emulator; and on a Mac with no Android SDK, it asked whether the Android SDK platform-tools were on your PATH. The CLI now takes the platform from the flow — or, for a flow that declares none, from--device— and an iOS run uses the only booted simulator, exactly as therun_flowMCP tool always has. Android runs keep the same default device and every adb message.A
--devicethat contradicts the flow's declaredplatform:now says so, in either direction —--device <id> is not an iOS simulator UDID, but <flow> declares platform: ios, or--device <udid> looks like an iOS simulator UDID, but <flow> declares platform: android— instead of failing later on a missing simulator or device. A flow that declares no platform is never refused: that is how one shared flow runs on iOS, by being given a simulator UDID.A flow without
platform:keeps separate self-heal memory per platform. Its iOS runs used to read and write the Android file,<flow>.fingerprints.json, where awhen: { platform }branch that runs on only one platform shifts which stored locator each later step is paired with — so an iOS step could heal onto a different element and pass. Heal memory now follows the device a run actually got: iOS runs use<flow>.fingerprints.ios.json, fromrun_flowand the CLI alike. If you ran such a flow on iOS before: when it only ever ran on iOS, rename its<flow>.fingerprints.jsonto<flow>.fingerprints.ios.jsonto keep that memory; when it ran on both platforms, delete the file once, so each platform re-learns from its own runs (a step that was passing only by healing then fails until its selector is updated).The HTML report names the simulator an iOS run used when no device id was passed, instead of
default.
What's new in 3.8.0
A run's report now says what happened in a way that cannot be misread — a green test used to render red, and one did get filed as a bug. Three outputs change shape; see "What changes for you" below.
A verdict.
report.htmlopens with✓ PASSEDor✗ FAILED. It used to state no verdict at all.A real tally.
66 passed · 10 skipped · 0 failedreplaces the report's66 of 76 steps passedand the CLI's andrun_flow's66/76 steps passed. A deliberate skip — anoptional:miss, awhen:that did not apply — is not a shortfall, and the old wording read as ten failures.Warnings look like warnings. They render amber with
⚠, and dismissed dialogs render neutral; red and orange are kept for step results. A warning raised more than once says how often, e.g.(17×).Steps after a failure are
not run, each with the reason —not run — the run stopped at step 4— instead ofskippedwith an empty detail. Inside arunFloworrepeat, the rest of the block is listed too, and a loop's unstarted iterations are counted on the loop's own row.Every block has a row. A
runFlowthat ran, and everyrepeat, gets a row with its file, its condition,times:, or — lacking both — a command count as the target, and what ran as the detail (when: visible #promo — ran else). Its steps are indented beneath it and numbered by position:4.2is the second step inside the block at step 4, and6.3.1is the first step of iteration 3 of therepeatat step 6.Time is in the row that spent it. With
dismiss:, the dialog check before each step reads the screen, and that read is the step's first look — but it was timed outside every row, so a run's steps could add up to a small fraction of its duration. Each row now includes it; the header shows what is left over (298.5 s (0.4 s outside steps)), how many dialog checks ran, how long they took and how many could not read the screen.
What changes for you:
JUnit testcase names are unchanged for flows without
runFloworrepeat. Flows that use them now number steps by position (4.2), so CI shows those testcases as renamed once — and from then on the names stop changing when awhen:branch runs on one run and not the next.The summary line reads
✓ login — 7 passed · 0 skipped · 0 failedinstead of✓ login — 7/7 steps passed. Anything that parsessteps passedneeds updating.Steps after a failure are
not run, notskipped. JUnit reports them as skipped, now with a message.Per-step times in a flow with
dismiss:go up by the dialog check before each step. The run's total time does not change.
What's new in 3.8.1
The
switchContexthelp text shows a neutral example domain. The guidanceobserve_webviewandswitchContextprint for pinning the right WebView page — "use a stable domain/path segment, not a full URL with session tokens" — illustrated it with a real company's domain. It now reads"@shop.example.com/browse". Text only: no behaviour change, and no flow needs editing.
Roadmap
Phase 1 (current): Android (native + WebView) via ADB, distributed as an npm package. Also: iOS simulator support (native + WebView), via
xcrun simctl+ WebDriverAgent + Apple's Web Inspector.Phase 2: web (Playwright).
Phase 3: cloud device farms (Firebase Test Lab, BrowserStack), CI/CD integration.
Phase 4: SaaS — web dashboard, team collaboration, history & analytics.
License
MIT
Available Tools
38 toolsassert_not_visibleA
Assert that an element is NOT currently visible on screen. Returns an error if the element IS found.
Inputs: text, device_id, resource_id.
assert_textC
Assert that an element with a given resource ID contains the expected text
Inputs: resource_id (required), expected_text (required), device_id.
assert_visibleC
Assert that an element is currently visible on screen. Returns an error if the element is NOT found.
Inputs: text, device_id, resource_id.
check_testabilityA
Audit the current screen for locator stability: how many actionable elements have a stable id, which don't, and the Compose testTag fix. (Android; on iOS, id-coverage is not meaningful — see docs/ios-testing.md)
Inputs: device_id.
clear_app_dataA
Clear all data for an app (cache, databases, shared preferences)
Inputs: package (required), device_id.
connect_deviceC
(Android) Connect to a device over TCP/IP (wireless debugging)
Inputs: ip (required), port.
describe_elementA
Read-only: dump EVERY attribute of the element(s) a selector matches — the state flags observe_ui hides (checkable, checked, selected, focused, enabled, password, scrollable), the full resource-id and class, and exact bounds. Returns one block per match with the index: a flow selector would use, so an ambiguous selector shows all its candidates instead of silently picking the first. Accepts the same enabled/checked/focused/selected qualifiers a flow selector does, so the index it reports is the index that selector will get. Use it while authoring to answer 'does this control expose its state at all?' before writing an assertion around it. For a single match with fewer attributes, find_element is the smaller answer.
Inputs: id, text, checked, enabled, +3 more.
device_infoB
(Android) Get detailed information about a connected Android device
Inputs: device_id.
dump_uiC
(Android) Dump the current UI hierarchy and return a structured representation of all visible elements
Inputs: device_id.
find_elementA
Find a UI element by text, resource ID, or class name and return its attributes and bounds. Returns the FIRST match with 8 of the node's attributes; describe_element returns every match with all 17 plus the index: a flow selector would use, and is the one to reach for when a selector may be ambiguous or when a state flag is in question.
Inputs: text, device_id, class_name, resource_id.
flow_referenceA
Return the compact YAML-flow grammar reference (commands, selectors, env, switchContext, examples). Call this before authoring a flow — no file lookup needed.
Inputs: no named parameters.
force_stopB
Force stop a running app
Inputs: package (required), device_id.
get_current_activityA
Get the name of the currently resumed activity (foreground screen)
Inputs: device_id.
input_textA
Type text into a field (optionally focus it first by selector). Uses ADBKeyboard for reliability. Waits for the screen to settle, then returns a fresh snapshot — annotated if it never settled.
Inputs: value (required), id, text, index, +2 more.
install_apkA
Install an APK file on a connected Android device
Inputs: apk_path (required), device_id.
is_element_visibleB
Check if an element with the given text or resource ID is currently visible on screen
Inputs: text, device_id, resource_id.
launch_appB
Launch an Android app by package name, optionally specifying an activity
Inputs: package (required), activity, device_id.
list_devicesB
List all connected Android devices/emulators and iOS simulators
Inputs: no named parameters.
long_pressB
Long press at specific screen coordinates
Inputs: x (required), y (required), device_id, duration_ms.
observe_uiB
Capture a compact, token-frugal snapshot of the current screen (actionable elements get a [ref=eN]).
Inputs: device_id.
observe_webviewA
List the app's debuggable WebView pages and return a compact DOM snapshot of the one with the most content (css-selectored). The app must opt in to WebView debugging: on Android WebView.setWebContentsDebuggingEnabled(true), on iOS WKWebView.isInspectable = true (16.4+; Safari needs no opt-in). Pass match (a URL substring/regex) to target a specific page; pin a page in a flow with switchContext "WEBVIEW_@".
Inputs: package (required), match, device_id.
press_keyB
Press a hardware/software key (BACK, HOME, ENTER, MENU, etc.)
Inputs: key (required), device_id.
run_flowA
Run a validated YAML test flow on a device (deterministic, no AI). Writes an HTML report and returns a pass/fail summary + report path. Call flow_reference for the YAML grammar.
Inputs: path (required), env, heal, device_id, +1 more.
scroll_downB
Scroll down on the screen (swipe from bottom to top)
Inputs: device_id.
scroll_upA
Scroll up on the screen (swipe from top to bottom)
Inputs: device_id.
swipeC
Swipe from one point to another on the screen
Inputs: x1 (required), x2 (required), y1 (required), y2 (required), +2 more.
take_screenshotA
Take a screenshot of the device screen and return it as an image (returns a large image; prefer observe_ui / observe_webview text — use only when those cannot answer).
Inputs: device_id.
tapA
Find an element by selector and tap its center. Waits for the screen to settle, then returns a fresh snapshot — annotated if it never settled.
Inputs: id, text, index, optional, +1 more.
tap_elementC
Find a UI element by text, resource ID, or class name and tap its center
Inputs: text, device_id, class_name, resource_id.
tap_xyA
Tap at raw screen coordinates (x, y). To tap an element by selector, use the 'tap' tool.
Inputs: x (required), y (required), device_id.
type_textA
Type text into the currently focused input field. Unicode is supported when ADBKeyboard is installed on the device.
Inputs: text (required), device_id.
uninstall_appA
Uninstall an app from a connected Android device
Inputs: package (required), device_id.
validate_flowA
Statically validate a YAML test flow file (schema, fragile-selector + undefined-env lint, and subflow resolution). No device needed. Call flow_reference for the YAML grammar.
Inputs: path (required).
wait_for_activityC
Wait until a specific activity becomes the foreground (resumed) activity
Inputs: activity (required), device_id, timeout_ms, poll_interval_ms.
wait_for_elementB
Wait until a UI element matching the query appears on screen, polling at regular intervals
Inputs: text, device_id, timeout_ms, resource_id, +1 more.
wait_for_textB
Wait until specific text appears anywhere on the screen
Inputs: text (required), device_id, timeout_ms, poll_interval_ms.
webview_inputA
Type text into a WebView field by css (or text) selector, then return the updated WebView DOM (focuses + sets the value so framework inputs accept it).
Inputs: value (required), package (required), css, text, +2 more.
webview_tapB
Tap an element inside the app's WebView by css (or text) selector, then return the updated WebView DOM (auto-waits + scrolls into view). Use the css from observe_webview; pass match= to target a specific page.
Inputs: package (required), css, text, match, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 38 tools
Multiple tools overlap heavily: tap_element and tap both tap by selector; type_text and input_text both type into fields; find_element, describe_element, dump_ui, and observe_ui all provide UI hierarchy/element querying. An agent would need to read detailed descriptions to avoid misselecting the wrong tool.
Most tools use a readable verb_noun snake_case pattern, but there are notable inconsistencies: tap_element and tap are near-synonyms, type_text and input_text are duplicate concepts, and webview_tap/webview_input invert the expected verb-object order. The general pattern is still recognizable.
38 tools is a heavy surface for a mobile testing server, and several tools are near-duplicates rather than genuinely distinct capabilities. The count would be more reasonable if tap_element/tap and type_text/input_text were merged.
The core mobile testing lifecycle is well covered: discovery, interaction, waiting, assertions, screenshots, app lifecycle, device management, WebView automation, and YAML flow validation. Minor gaps exist, such as clearing text fields, element-level swipes, and waiting for an element to disappear, but these are workaroundable.
Maintenance
Related MCP Connectors
Write, run and check natural-language browser tests of your web app from your AI assistant.
No-code, AI-assisted UI testing: record new tests, run existing ones, and monitor the results.
Cloud iPhone Simulators for AI agents: build the Xcode project, read the screen, tap by label, test.
Let AI agents control Android and iOS devices on Mobilerun Cloud: screen, input, apps, workflows.
Related MCP Servers
AlicenseAqualityAmaintenanceEnables AI assistants to automate mobile app testing and development for iOS and Android through natural language interactions. Supports intelligent element identification, session management, automated test generation, and comprehensive device interactions including clicks, swipes, screenshots, and app management.3210,260 npm519Apache 2.0
Argentofficial
AlicenseAqualityBmaintenanceEnables AI assistants to interact with iOS Simulators and Android Emulators, allowing autonomous app development, UI interaction, profiling, and debugging through natural language.773,217Apache 2.0
MobAI MCP Serverofficial
AlicenseAqualityCmaintenanceEnables AI assistants to automate mobile devices (Android and iOS) through a single DSL interface, supporting actions like tap, type, swipe, and assertions.20426 npm255Apache 2.0- AlicenseBqualityCmaintenanceEnables AI assistants to automate Android and iOS mobile apps through natural-language interactions, intelligent element location, session management, screenshots, and automated test generation.40Apache 2.0