AgenTest
Enables automated testing of Android applications by connecting to an emulator or physical device, reading UI trees, and executing actions like taps, typing, gestures, and assertions.
Used as part of Flutter support, the Dart VM Service provides semantics and idle detection for Flutter app testing.
Supports testing Flutter apps via the Dart VM Service for semantics and idle sync, enabling automated UI testing.
Provides the same testing capabilities as Android, targeting iOS simulators (currently in development).
Supports testing React Native apps by extracting React component names from the Hermes runtime, enabling interaction with UI elements without test IDs.
Allows querying SQLite databases on the device (debug builds) for verification during tests.
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., "@AgenTest Test the login flow for my app."
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.
AgenTest
AI-driven mobile app testing via MCP. Any AI coding agent can test any Android app.
Your AI reads your code, generates test cases, and executes them against a real emulator -- no test framework, no boilerplate, no testIDs required.
Works with: Claude Code, Cursor, Windsurf, Copilot, Kiro, Antigravity, and any MCP-compatible agent.
How is AgenTest different from Appium or Maestro?
Appium and Maestro are excellent test frameworks. If you have a QA team writing and maintaining structured test suites, they're the right tools. AgenTest solves a different problem.
AgenTest is for developers who don't write tests. If you're building with Cursor, Bolt, v0, or Lovable -- shipping fast, iterating daily, no QA team -- you probably have zero test coverage. AgenTest lets your AI agent test your app with a single prompt. No test code, no YAML, no page objects.
Where AgenTest shines
Zero setup overhead.
npm install -g agentest+ 4 lines of JSON. No Java, no Selenium, no drivers.No testIDs required. Most AI-generated apps don't have
testIDs. AgenTest auto-generates@refselectors and extracts React component names from the Hermes runtime -- icon buttons like<Phone />and<Microphone />just work.No test maintenance. The AI sees the current UI tree and adapts. No selectors to update, no flows to rewrite when the UI changes.
Source code awareness. When a test fails, the AI reads your code to explain why -- not just which assertion broke.
Fast. ~150-400ms per action with the on-device helper + gRPC, comparable to Maestro, faster than Appium.
Where Appium and Maestro are better
Deterministic CI suites. If you need the same test to run identically 1000 times, a hand-written Appium/Maestro test is more predictable than an AI-generated one.
Cross-platform parity. Appium supports iOS, Android, web, and desktop today. Maestro supports iOS and Android. AgenTest is Android-only (iOS coming soon).
Team-scale test management. Page object patterns, test reporting dashboards, parallelized test runs across device farms -- Appium's ecosystem is mature here.
Bottom line
Use Appium or Maestro when you have dedicated QA and need deterministic, version-controlled test suites. Use AgenTest when you're a developer who wants AI-powered testing with zero boilerplate -- especially on apps built with code-generation tools where nothing has a testID.
Related MCP server: Mobile E2E MCP
How it works
Developer: "Test the login flow of my app"
AI agent:
1. Connects to your emulator via AgenTest
2. Reads the UI tree (compact, token-efficient format)
3. Generates test steps from your source code + UI
4. Executes taps, types, swipes, gestures, assertions
5. Reports exactly what broke -- down to the line of codeAgenTest handles the hard parts: reading accessibility trees, injecting input via gRPC/ADB/helper APK, syncing with React Native and Flutter frameworks, extracting component metadata from running apps, and detecting when the UI has settled. All test intelligence lives in your AI agent.
Quick start
1. Install
npm install -g agentestOr from source:
git clone https://github.com/arjun-vegeta/agenTest.git
cd agentest
npm install && npm run build2. Prerequisites
Node.js >= 18
Android SDK installed (Android Studio or standalone SDK)
Android emulator running (or physical device via USB)
AgenTest auto-discovers adb from standard SDK locations -- no PATH configuration needed. It checks ANDROID_HOME, ANDROID_SDK_ROOT, ~/Library/Android/sdk (macOS), ~/Android/Sdk (Linux), and %LOCALAPPDATA%\Android\Sdk (Windows).
Verify your emulator is running: adb devices should list at least one device.
3. Configure your AI agent
Add AgenTest as an MCP server. The config format depends on your agent:
Claude Code (.claude/settings.json or .mcp.json):
{
"mcpServers": {
"agentest": {
"command": "npx",
"args": ["-y", "agentest"]
}
}
}Cursor (.cursor/mcp.json):
{
"mcpServers": {
"agentest": {
"command": "npx",
"args": ["-y", "agentest"]
}
}
}VS Code / Copilot (.vscode/mcp.json):
{
"servers": {
"agentest": {
"command": "npx",
"args": ["-y", "agentest"]
}
}
}Windsurf (~/.codeium/windsurf/mcp_config.json):
{
"mcpServers": {
"agentest": {
"command": "npx",
"args": ["-y", "agentest"]
}
}
}4. Use it
Tell your AI agent:
Test the login flow. Package name is com.example.myapp.That's it. The AI handles the rest.
Tools
AgenTest exposes 10 MCP tools:
Tool | What it does |
| Connect to emulator, launch app, auto-detect backends, return compact UI tree |
| Fresh UI snapshot (compact text with |
| Execute a batch of actions + assertions, stop on first failure |
| Force-stop and relaunch, return fresh tree |
| Capture screen as base64 PNG |
| Logcat output filtered to app PID |
| Screen size, density, Android version, model |
| Simulate network conditions (offline, 2g, 3g, lte) |
| Inspect SharedPreferences (debug builds) |
| Query SQLite databases (debug builds) |
Supported actions in agentest_run_flow
Category | Actions |
Tap |
|
Input |
|
Gestures |
|
Scroll |
|
Wait |
|
Assert |
|
Compact UI tree
AgenTest returns UI trees in a token-efficient compact format with stable @ref selectors:
screen 1280x2856 com.example.myapp #a1b2c3
@b1 btn "Sign in"
@f1 input "Email"
@f2 input "Password"
@c1 check "Remember me"
@b2 btn "Forgot password?"
"Don't have an account?"
@l1 link "Sign up"Ref types: @b = button, @f = input field, @c = checkbox/switch, @s = scrollable, @l = link, @g = generic tappable.
The AI uses refs in subsequent actions:
{ "action": "tap", "target": { "ref": "@b1" } }
{ "action": "type", "target": { "ref": "@f1" }, "value": "user@example.com" }Traditional selectors (id, text, textContains, className, description) also work alongside refs.
No testIDs needed
For React Native apps built with Cursor, Bolt, v0, or Lovable, AgenTest extracts React component names directly from the running Hermes runtime and labels icon buttons automatically:
@b5 btn "Phone" -- from React Fiber: <Phone /> component
@b6 btn "DotsVertical" -- from React Fiber: <DotsVertical /> component
@b7 btn "Microphone" -- from React Fiber: <Microphone /> componentThis means every icon button in a zero-testID app gets a usable label without any code changes to the target app.
Framework support
Framework | Support | How |
React Native (debug) | Full | Hermes CDP for fiber labels + JS-idle sync |
React Native (release) | Good | A11y tree + text hoisting (no fiber labels) |
Flutter (debug) | Full | Dart VM Service for semantics + idle sync |
Flutter (release) | Good | A11y tree only |
Native Android / Compose | Good | A11y tree + text hoisting |
Idle detection: AgenTest auto-waits after every action. The helper APK detects UI stability via accessibility events (~150-300ms). For RN/Flutter debug builds, framework-specific sync probes (Hermes CDP JS-idle, Dart VM frame-idle) run as tail checks to catch async state changes the a11y layer doesn't see.
iOS support (coming soon)
iOS simulator support is in active development -- same MCP tools, same compact tree format, same AI workflow. Android is fully supported today.
Architecture
+------------------------------------------+
| AI Agent (any MCP client) |
+------------------------------------------+
| MCP (stdio)
+------------------------------------------+
| AgenTest Server (TS) |
| tree parsing, idle detection, fiber |
| extraction, framework sync, ref mgmt |
+------------------------------------------+
| | |
gRPC ADB Helper APK
(emulator (universal (on-device,
gestures) fallback) auto-installed)Helper APK (~1.8 MB): Auto-installed on first connect. Reads UI trees in ~80ms via in-process UiAutomation (vs ~1.5s with
uiautomator dump). Detects idle via accessibility events. Zero user setup.gRPC: Direct emulator input injection at 60 FPS (tap, swipe, long-press, pinch, rotate). Instant, no shell overhead. Emulator only.
ADB fallback: Works everywhere -- physical devices, CI, and when gRPC/helper aren't available. Slower but always functional.
Framework sync: Hermes CDP (React Native) and Dart VM Service (Flutter) for JS/Dart idle detection and React Fiber component extraction.
Performance
Mode | Per-action latency | When |
Helper + gRPC | ~150-400ms | Emulator (best case) |
Helper + ADB | ~300-600ms | Physical device |
ADB only | ~1.5-3s | Fallback when helper can't install |
Optional: Idling Bridge
For apps with heavy background work (network requests, sync queues), add the opt-in idling bridge AAR to eliminate flakiness:
// android/app/build.gradle.kts
dependencies {
debugImplementation(
files("../../node_modules/agentest/android-helper/prebuilt/agentest-idling-bridge.aar")
)
}AgenTest auto-detects it on the next connect. See docs/setup.md for details.
Troubleshooting
adb not found
AgenTest auto-discovers adb from standard locations. If it still can't find it:
Set
ANDROID_HOMEin your shell profile:# macOS / Linux export ANDROID_HOME=~/Library/Android/sdk # macOS export ANDROID_HOME=~/Android/Sdk # Linux # Windows (PowerShell) $env:ANDROID_HOME = "$env:LOCALAPPDATA\Android\Sdk"Or pass PATH explicitly in your MCP config:
{ "mcpServers": { "agentest": { "command": "npx", "args": ["-y", "agentest"], "env": { "PATH": "/path/to/android/sdk/platform-tools:/usr/local/bin:/usr/bin:/bin" } } } }
No devices found
Make sure your emulator is fully booted (past the Android boot animation)
Run
adb devicesmanually -- you should see at least onedevice(notofflineorunauthorized)Try
adb kill-server && adb start-serverto reset the connection
Helper APK didn't install
If agentest_connect returns "helperInstalled": false, AgenTest falls back to the slower ADB path automatically. Everything still works, just ~3-5x slower tree reads. To fix:
Check that the emulator has enough disk space
Make sure the emulator is fully booted before connecting
Try
adb uninstall com.agentest.helper.test && adb uninstall com.agentest.helperthen reconnect
UI tree is empty
The app may still be loading. Wait a moment and call
agentest_get_ui_treeagainSome screens (splash, OpenGL/SurfaceView) don't expose accessibility nodes
Use
agentest_screenshotas a fallback to see what's on screen
Slow performance
AgenTest has three speed tiers:
Helper + gRPC (~150-400ms/action) -- best, emulator only
Helper + ADB (~300-600ms/action) -- physical devices
ADB only (~1.5-3s/action) -- fallback when helper can't install
If you're stuck on tier 3, check the helper install issue above.
Documentation
Architecture -- system design, data flow
MCP Tools Reference -- all tools, parameters, responses
Type System -- types, schemas, constants
Setup Guide -- installation, configuration, troubleshooting
Examples -- usage patterns, real-world flows
Development
npm install # install dependencies
npm run build # compile TypeScript
npm run dev # watch mode
npm test # run tests (293 tests)
npm run typecheck # type check
npm run lint # lintLicense
MIT
Available Tools
10 toolsagentest_connectA
Connect to an Android emulator/device and launch the app. Returns the initial UI screen in compact text format with @ref tokens you can use as selectors.
The compact format uses one line per element: @b1 btn "Sign in" — button, ref @b1 @f1 input "Email" — text field, ref @f1 @c1 check "Remember me" — checkbox @s1 scroll — scrollable area @l1 link "Forgot?" — clickable text link @g1 tap — generic clickable (unlabeled) "plain text" — non-interactive text
Use refs in subsequent run_flow steps: { "action": "tap", "target": { "ref": "@b1" } } Traditional selectors (id/text/className/description) still work alongside refs.
Pass verbose:true to include framework-sync diagnostics.
Inputs: packageName (required), backend, verbose, deviceId.
agentest_device_infoA
Get device/emulator info: screen size, density, Android version, SDK level, model. Use to understand the test environment.
Inputs: no named parameters.
agentest_get_logsA
Get recent app logs (logcat) filtered to the target app. Use to diagnose failures — API errors, crashes, exceptions.
Inputs: maxLines, packageName.
agentest_get_ui_treeA
Get a fresh snapshot of the current UI screen. Returns compact text with @ref tokens by default.
Use refs in selectors: { "ref": "@b1" }. If a ref is stale (screen changed), you'll get a clear error — just call this tool again for fresh refs.
Options:
format: "compact" (default) or "full" (legacy JSON tree with bounds + classNames — use for debugging or layout inspection)
depth: max tree depth (omit for unlimited)
onlyInteractive: true to drop plain text lines (hoisted labels still appear on interactives)
Inputs: depth, format, onlyInteractive.
agentest_query_dbA
Run a SQL query against an app SQLite database (including Room). Use to verify DB state after test actions. Requires a debuggable build.
Inputs: query (required), database (required), packageName.
agentest_reset_appA
Force-stop and relaunch the app. Returns fresh compact tree with @refs. Use between test cases for clean state.
Inputs: packageName.
agentest_run_flowA
Execute a batch of UI actions and assertions. Stops on first failure.
TARGET ELEMENTS using refs from the last tree snapshot: { "action": "tap", "target": { "ref": "@b1" } } Or use traditional selectors (id/text/textContains/className/description/index) — both work.
DO NOT add "wait" or "wait_for_stable" steps — the server auto-waits after every action.
RESPONSE: includes screenFingerprint and screenChanged. If screenChanged is false and success is true, the UI is exactly where you left it — reuse your prior refs without re-snaphotting. The tree is only included when the screen actually changed or the flow failed.
ACTIONS: tap, tap_coordinates, type, clear_text, swipe, swipe_coordinates, long_press, long_press_coordinates, double_tap, double_tap_coordinates, press_key, scroll_to. ASSERTIONS: assert_visible, assert_not_visible, assert_text_equals, assert_text_contains.
SELECTORS: ref (fastest — from last snapshot), id (substring), text (exact), textContains (substring), className (short or full name), description (substring), index (0-based Nth match).
Inputs: steps (required).
agentest_screenshotA
Capture a screenshot of the current screen as a base64-encoded PNG. Use when the accessibility tree is insufficient — custom canvas, images, visual layout issues.
Inputs: no named parameters.
agentest_set_networkA
Simulate network conditions on the emulator for testing offline/slow connections.
Presets: "full" (unlimited), "lte" (58/173 Mbps), "3g" (384 kbps), "edge" (237/474 kbps), "gsm" (14 kbps), "gprs" (29/58 kbps), "offline" (wifi + data off). Latency presets: "none", "gprs" (150-550ms), "edge" (80-400ms), "umts" (35-200ms). Custom: "speed" as "up:down" kbps, "delay" as "min:max" ms. Also: toggle wifi and airplaneMode explicitly.
Inputs: wifi, delay, speed, preset, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct aspect of Android app testing: connection, device info, logs, preferences, UI tree, database, app reset, flow execution, screenshots, and network simulation. No overlap in functionality.
All tools follow the pattern 'agentest_' + descriptive verb phrase in snake_case (e.g., 'agentest_connect', 'agentest_get_logs'), providing a predictable and clear naming convention.
With 10 tools, the set is well-scoped for the domain of Android UI testing, covering essential operations without being overly large or too sparse.
The tool surface covers the full lifecycle of test sessions: setup (connect, reset), interaction (run_flow with actions/assertions), diagnostics (logs, screenshots, device info, shared prefs, database queries), and conditioning (network simulation). No obvious gaps.
Maintenance
Related MCP Connectors
AI agents on real phones: run tasks, read the screen, tap, type and install apps.
Mozark's MCP server for AI-powered app testing: device access, test automation, and QA insights.
Let AI agents control Android and iOS devices on Mobilerun Cloud: screen, input, apps, workflows.
Cloud Android phones for AI agents: create a phone, read the screen, tap, type, install APKs, park.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI-driven mobile test automation through planning, generation, and self-healing agents for Android and iOS, exposed as callable MCP tools.10ISC
- AlicenseNot gradedqualityDmaintenanceAI-safe mobile device control via MCP: a policy-guarded, session-oriented mobile automation harness for AI agents with 66 MCP tools and an Explorer for automatic page traversal.3MIT
- AlicenseAqualityCmaintenanceA Model Context Protocol server for ad-hoc UI testing of Android and iOS apps, enabling LLM agents to interact with mobile app UIs and react to observations.407 npm3MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI agents to drive real Android apps, capture API traffic, and test mobile-native attack surfaces, similar to Playwright for mobile.MIT