Mobile Testing AI Agent Server

Native mobile app testing for iOS & Android Real Devices

Mobile testing, mobile automation, mobile QA, and mobile test automation framework powered by AI agents and MCP tooling.

Project Overview: Mobile Testing, Mobile Automation, and Mobile QA

This repository provides an AI-powered framework for mobile testing and mobile test automation (plus web validation) using:

• Planner Agent: explores a target app or site and generates a structured Markdown test plan for mobile QA.
• Generator Agent: converts the Markdown test plan into executable Playwright or Mobilewright tests for mobile automation workflows.
• Healer Agent: runs tests, detects failures, and attempts automated repair cycles to improve mobile test automation stability.
• Android and iOS Orchestrators: run Planner -> Generator -> Healer as end-to-end pipelines for each platform and mobile testing lifecycle.
• MCP Server: exposes the framework as callable MCP tools over stdio for AI clients and automation platforms.

The framework is designed to accelerate mobile test authoring, improve test stability, and provide an extensible baseline for AI-assisted mobile QA workflows.

Native Development Framework Support Matrix

The automation stack runs against Android and iOS app binaries/devices. In practice, this means support is based on platform runtime behavior rather than only the app framework.

Native app development framework	Support status	Notes
Android native (Kotlin/Java)	Supported	Run with the Android Mobilewright flow (npm run test:android / Android orchestrator).
iOS native (Swift/Objective-C)	Supported	Run with the iOS Mobilewright flow (npm run test:ios / iOS orchestrator).
React Native	Supported (via Android/iOS builds)	Test the compiled Android/iOS app using platform-specific selectors and flows.
Flutter	Supported (via Android/iOS builds)	Works through generated native app binaries on Android/iOS devices/simulators.
.NET MAUI / Xamarin	Supported (via Android/iOS builds)	Use Android/iOS pipelines after producing platform app builds.
Ionic / Cordova / Capacitor	Supported (via Android/iOS builds)	Treat as mobile app binaries; use web-context selectors where applicable.

Notes:

• This project currently provides platform orchestrators for Android and iOS.
• Framework support is validated at runtime through the produced Android/iOS app package and testability of UI selectors.

Quick Setup for Mobile Test Automation (One Command)

For a fast web-ready setup:

npm install && npx playwright install chromium

Then run the default web test:

npm run test:web

Optional environment setup:

cp .env.example .env

On Windows PowerShell:

Copy-Item .env.example .env

Dependencies for Mobile Automation and Mobile QA

Required

• Node.js 20.18.1+ (recommended to satisfy current package engine requirements)
• npm 9+
• Playwright Chromium browser

Core NPM packages

• mobilewright ^0.0.33
• @playwright/test ^1.59.1
• playwright ^1.59.1
• @modelcontextprotocol/sdk ^1.29.0
• zod ^4.4.3
• openai ^6.37.0
• dotenv ^17.4.2
• fs-extra ^11.3.5
• chalk ^5.6.2
• axios ^1.16.0
• cheerio ^1.2.0

Platform prerequisites

Web

• No additional setup after installing dependencies and Chromium.

Android

• Android SDK installed
• ADB available on PATH
• ANDROID_HOME configured
• At least one connected Android device or emulator

Useful checks:

npm run doctor
npm run devices

iOS

• macOS host for local iOS automation
• Xcode + Command Line Tools
• Booted iOS Simulator (or compatible cloud/mobile device provider)

Repository Structure for Mobile Testing Projects

Mobile-App-Testing-AI-Agent-MCP-Server/
├── agents/
│   ├── planner.js
│   ├── generator.js
│   └── healer.js
├── mcp/
│   └── server.js
├── orchestrators/
│   ├── android-orchestrator.js
│   └── ios-orchestrator.js
├── tests/
│   ├── generated/
│   └── uselessweb/
│       ├── uselessweb.spec.js
│       ├── uselessweb-android.test.js
│       └── uselessweb-ios.test.js
├── plans/
│   └── uselessweb-org--web-test-plan.md
├── reports/
├── mobilewright.config.js
├── playwright.config.js
├── .env.example
└── package.json

What each area does for mobile testing and automation

• agents: AI agent implementations for planning, generation, and healing in mobile test automation pipelines.
• mcp: stdio MCP server exposing planner, generator, healer, and orchestrator tools.
• orchestrators: platform-specific pipeline runners for Android and iOS mobile automation.
• tests: executable specs, including generated tests and curated examples for mobile QA.
• plans: Markdown test plans used as source input for code generation.
• reports: mobile testing and healing run artifacts.

Usage Guide for Mobile Testing and Mobile QA

1. Run web test suite

npm run test:web

2. Run mobile viewport projects in Playwright (mobile testing)

npm run test:mobile-chrome
npm run test:mobile-safari

3. Run Android or iOS Mobilewright tests for mobile automation

npm run test:android
npm run test:ios

4. Use individual AI agents

Planner

npm run agent:planner
npm run agent:planner:android
npm run agent:planner:ios

Direct CLI example:

node agents/planner.js --url=https://uselessweb.org/ --platform=web --out=plans/

Generator

npm run agent:generator
npm run agent:generator:android
npm run agent:generator:ios

Direct CLI example:

node agents/generator.js --plan=plans/uselessweb-org--web-test-plan.md --platform=web --out=tests/generated/

Healer

npm run agent:healer
npm run agent:healer:android
npm run agent:healer:ios

Direct CLI example:

node agents/healer.js --spec=tests/uselessweb/uselessweb.spec.js --platform=web --retries=3

5. Add a new test with Android and iOS agents (mobile test automation flow)

Use this flow when you want to create tests for a new target URL in your mobile QA process.

Android agent flow (plan -> generate -> run -> heal)

1. Generate an Android test plan:

node agents/planner.js --url=https://uselessweb.org --platform=android --out=plans/

2. Generate Android tests from the plan:

node agents/generator.js --plan=plans/example-com-android-test-plan.md --platform=android --out=tests/generated/

3. Run the generated Android test:

npx mobilewright test tests/generated/example-com-android-test-plan.test.js

4. Auto-heal failing Android tests:

node agents/healer.js --spec=tests/generated/example-com-android-test-plan.test.js --platform=android --retries=3

iOS agent flow (plan -> generate -> run -> heal)

1. Generate an iOS test plan:

node agents/planner.js --url=https://uselessweb.org --platform=ios --out=plans/

2. Generate iOS tests from the plan:

node agents/generator.js --plan=plans/example-com-ios-test-plan.md --platform=ios --out=tests/generated/

3. Run the generated iOS test:

npx mobilewright test tests/generated/example-com-ios-test-plan.test.js

4. Auto-heal failing iOS tests:

node agents/healer.js --spec=tests/generated/example-com-ios-test-plan.test.js --platform=ios --retries=3

Optional: use orchestrators instead of running each step manually

npm run orchestrate:android -- --url=https://uselessweb.org --retries=3
npm run orchestrate:ios -- --url=https://uselessweb.org --retries=3

6. Run orchestration pipelines for mobile automation

Android pipeline

npm run orchestrate:android

iOS pipeline

npm run orchestrate:ios

7. Run complete web AI pipeline

npm run pipeline:web

This executes Planner -> Generator -> Healer for web.

7b. Run complete mobile QA pipelines

For end-to-end mobile test automation on each platform:

npm run orchestrate:android
npm run orchestrate:ios

8. Start the MCP server

npm run mcp:start

The server runs on stdio and exposes tools including:

• health_check
• run_planner
• run_generator
• run_healer
• run_orchestrator
• list_repo_commands

9. Inspect MCP tools locally

npm run mcp:inspect

10. Example MCP client configuration

Use this in an MCP-capable client configuration file:

{
   "mcpServers": {
      "mobile-testing-ai-agent": {
         "command": "node",
         "args": ["mcp/server.js"],
         "cwd": "."
      }
   }
}

11. CI/CD pipeline (GitHub Actions)

This repository now includes a CI/CD workflow at .github/workflows/ci-cd.yml.

CI behavior:

• Runs on pushes to main and pull requests targeting main.
• Installs dependencies with npm ci.
• Installs Playwright Chromium.
• Executes the web suite with npm run test:web.
• Uploads Playwright report artifacts when available.

CD behavior:

• Runs after CI on pushes to main.
• Triggers deployment only if DEPLOY_WEBHOOK_URL is configured as a repository secret.
• Safely skips deployment when the secret is not set.

To enable deployment, add this repository secret:

• DEPLOY_WEBHOOK_URL

Contributing to Mobile Testing and Mobile Automation

Contributions are welcome. Please follow the workflow below:

1. Fork the repository.
2. Create a feature branch from main.
3. Keep changes focused and well-scoped.
4. Add or update tests for new behavior.
5. Run relevant checks before opening a PR:
   • npm run test:web
   • npm run test:all
   • npm run doctor (for mobile environments)
6. Open a pull request with:
   • clear problem statement
   • implementation summary
   • validation evidence (logs, test output, screenshots where useful)

Contribution guidelines

• Prefer small, reviewable pull requests.
• Avoid unrelated refactors in the same PR.
• Preserve script and folder naming conventions.
• Document new commands and agent behaviors in this README.

Acknowledgements

This project is built on top of the excellent Mobilewright ecosystem.

• Mobilewright framework: https://github.com/mobile-next/mobilewright
• Mobilewright documentation: https://mobilewright.dev

Special thanks to the Mobilewright maintainers and contributors for enabling practical mobile automation workflows across Android and iOS.

License

ISC

Mobile Testing FAQ

What is native mobile test automation?

Mobile test automation is the practice of using tools and scripts to validate mobile apps and mobile web experiences automatically across Android and iOS.

How does this repository help with mobile QA?

This project supports mobile QA with AI-driven planning, test generation, and self-healing execution, plus Android and iOS orchestration flows.

Is this suitable for mobile automation teams?

Yes. It is built for teams that need scalable mobile automation, repeatable test pipelines, and faster feedback cycles for releases.

Which mobile testing keywords does this framework target?

This framework focuses on practical workflows for mobile testing, mobile automation, mobile QA, and mobile test automation.

Questions?

If you have any questions:

• 💬 Open a GitHub Discussion
• 🐛 Report bugs via GitHub Issues
• 📧 Email: padmaraj dot nidagundi at gmail.com

Response time: Typically 24-48 hours.

---

First-Time Contributors Welcome! 👋👋👋👋👋👋

New to open source? No problem! Look for issues tagged with good-first-issue or help-wanted. We provide mentorship and guidance to help you succeed.

Thank you for making test automation better for everyone! 🚀