Skip to content

arjun-vegeta/agenTest

BranchesTags

Repository files navigation

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 @ref selectors 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.

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 code

AgenTest 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 agentest

Or from source:

git clone https://github.com/arjun-vegeta/agenTest.git
cd agentest
npm install && npm run build

2. 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
agentest_connect Connect to emulator, launch app, auto-detect backends, return compact UI tree
agentest_get_ui_tree Fresh UI snapshot (compact text with @ref tokens)
agentest_run_flow Execute a batch of actions + assertions, stop on first failure
agentest_reset_app Force-stop and relaunch, return fresh tree
agentest_screenshot Capture screen as base64 PNG
agentest_get_logs Logcat output filtered to app PID
agentest_device_info Screen size, density, Android version, model
agentest_set_network Simulate network conditions (offline, 2g, 3g, lte)
agentest_get_shared_prefs Inspect SharedPreferences (debug builds)
agentest_query_db Query SQLite databases (debug builds)

Supported actions in agentest_run_flow

Category Actions
Tap tap, tap_coordinates, double_tap, double_tap_coordinates, long_press, long_press_coordinates
Input type, clear_text, press_key
Gestures swipe, swipe_coordinates, pinch, rotate
Scroll scroll_to (scroll until target is visible)
Wait wait (fixed delay), wait_for_stable (wait for UI to settle)
Assert assert_visible, assert_not_visible, assert_text_equals, assert_text_contains

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 /> component

This 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:

  1. Set ANDROID_HOME in 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"

  2. 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 devices manually -- you should see at least one device (not offline or unauthorized)
  • Try adb kill-server && adb start-server to 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.helper then reconnect

UI tree is empty

  • The app may still be loading. Wait a moment and call agentest_get_ui_tree again
  • Some screens (splash, OpenGL/SurfaceView) don't expose accessibility nodes
  • Use agentest_screenshot as a fallback to see what's on screen

Slow performance

AgenTest has three speed tiers:

  1. Helper + gRPC (~150-400ms/action) -- best, emulator only
  2. Helper + ADB (~300-600ms/action) -- physical devices
  3. 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

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         # lint

License

MIT

About

AI-driven mobile app testing via MCP. Any AI coding agent can test any Android app — no test framework, no boilerplate, no testIDs

agentest.tech/

Topics

android testing emulator automation react-native ai adb accessibility mcp cursor hermes flutter ai-agents claude mobile-testing openai-codex model-context-protocol agentic-developer-tools

Resources

Readme

License

MIT license
Activity

Stars

4 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

2 tags

Contributors

Languages