{"id":45773039,"url":"https://github.com/sh3lan93/mobile-automator","last_synced_at":"2026-03-12T23:05:30.501Z","repository":{"id":339072203,"uuid":"1154586187","full_name":"sh3lan93/mobile-automator","owner":"sh3lan93","description":"The intelligent mobile QA extension that learns your app and writes tests for you.","archived":false,"fork":false,"pushed_at":"2026-02-25T20:01:43.000Z","size":53901,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-26T10:10:10.916Z","etag":null,"topics":["gemini-cli-extension","mobile-qa","mobile-test-automation","semantic-testing"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sh3lan93.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-10T14:59:04.000Z","updated_at":"2026-02-25T20:01:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sh3lan93/mobile-automator","commit_stats":null,"previous_names":["sh3lan93/mobile-automator"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/sh3lan93/mobile-automator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sh3lan93%2Fmobile-automator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sh3lan93%2Fmobile-automator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sh3lan93%2Fmobile-automator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sh3lan93%2Fmobile-automator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sh3lan93","download_url":"https://codeload.github.com/sh3lan93/mobile-automator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sh3lan93%2Fmobile-automator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30448617,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T21:31:01.033Z","status":"ssl_error","status_checked_at":"2026-03-12T21:30:43.161Z","response_time":114,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gemini-cli-extension","mobile-qa","mobile-test-automation","semantic-testing"],"created_at":"2026-02-26T07:34:04.219Z","updated_at":"2026-03-12T23:05:30.495Z","avatar_url":"https://github.com/sh3lan93.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 Mobile Automator\n\n\u003e **The intelligent mobile QA extension that learns your app and writes tests for you.**\n\n\u003cdiv align=\"center\"\u003e\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![Platform](https://img.shields.io/badge/Platform-Android%20%7C%20iOS%20%7C%20Flutter%20%7C%20React%20Native-green.svg)](#)\n[![Powered by](https://img.shields.io/badge/Powered%20by-mobile--mcp-orange.svg)](https://github.com/mobile-next/mobile-mcp)\n\n\u003c/div\u003e\n\n---\n\n## 💡 Why Mobile Automator?\n\n**The story behind this tool:**\n\nEvery Monday, I had **4 hours blocked on my calendar** for manual regression testing. Four hours. Every single week.\n\nThat's **208 hours a year** tapping through the same flows, checking the same screens, validating the same features. Over and over again.\n\nI realized something had to change. **I refuse to repeat myself.** My time is too valuable to waste on tasks that can be automated.\n\nSo I built Mobile Automator—not just to run tests, but to **learn from my manual testing sessions** and replay them automatically. Now, those 4 hours are spent building features instead of repeating the same test flows.\n\n**If you're tired of manual regression testing eating your calendar, this tool is for you.** 🎯\n\n---\n\n## ✨ What Makes This Special?\n\n**Mobile Automator doesn't just run tests—it understands your app.**\n\nWhen you run setup, it analyzes your codebase and automatically detects:\n- 📱 **Platform \u0026 Architecture** - Android, iOS, Flutter, React Native, KMP, CMP\n- 🏗️ **Architecture Pattern** - MVVM, Clean Architecture, BLoC, Redux, MVP\n- 🎯 **Business Domain** - What your app actually does\n- ⚡ **Loading Patterns** - Your specific progress indicators and shimmer effects\n- 🔧 **Build Configuration** - Commands, flavors, environments\n- 📦 **Package IDs** - Android applicationId, iOS Bundle Identifier\n\nThen it generates **AI-powered testing skills** customized specifically for your project.\n\n---\n\n## 🎬 See It In Action\n\n### 📝 Generate Test Scenarios\n\nhttps://github.com/user-attachments/assets/6be4adce-4b30-45b1-a025-0e3373e30348\n\n**What you see:**\n- 🎮 Describe user flows in plain English\n- 🤖 AI controls your device/emulator automatically\n- 📸 Captures reference screenshots at each step\n- ✍️ Generates structured JSON test scenarios\n\n---\n\n### ▶️ Execute Tests \u0026 Get Intelligent Reports\n\nhttps://github.com/user-attachments/assets/fbc69108-0736-402c-846c-faca237fe4ca\n\n**What you get:**\n- ✅ Pass/fail status with detailed results\n- 🔍 Regression detection (spots UI changes)\n- ⚡ Flakiness detection (retries on transient failures)\n- 🧠 Contextual insights (device differences, environment details)\n\n---\n\n## 🎯 Quick Start\n\n### Prerequisites\n- **Gemini CLI** installed ([Get it here](https://geminicli.com))\n- **Mobile project** (Android, iOS, Flutter, React Native, KMP, or CMP)\n- **Node.js** v16+ (for mobile-mcp automation engine)\n\n### Installation\n\n**From GitHub:**\n```bash\ngemini extensions install https://github.com/sh3lan93/mobile-automator\n```\n\n**Local Development:**\n```bash\ngit clone https://github.com/sh3lan93/mobile-automator\ncd mobile-automator\ngemini extensions link .\n```\n\n### Setup Your Project\n\n```bash\n# Navigate to your mobile project\ncd ~/projects/my-awesome-app\n\n# Launch Gemini CLI\ngemini\n\n# Run setup\n\u003e /mobile-automator:setup\n```\n\nThe setup wizard will guide you through:\n1. ✅ **Platform Detection** - Identifies your tech stack\n2. ✅ **Environment Discovery** - Finds staging, prod, dev configs\n3. ✅ **App Package Inference** - Extracts bundle IDs\n4. ✅ **Project Knowledge** - Learns your architecture and domain\n5. ✅ **Skill Installation** - Generates customized testing skills\n6. ✅ **Directory Scaffolding** - Creates test artifact structure\n\n**After setup completes, reload skills:**\n```bash\n\u003e /skills reload\n```\n\n**Output:**\n```\nmobile-automator/\n├── config.json              # Project configuration\n├── index.md                 # Documentation\n├── scenarios/               # Generated test scenarios\n├── screenshots/             # Reference screenshots\n└── results/                 # Test execution reports\n\n.gemini/skills/\n├── mobile-automator-generator/   # Your custom test generator\n└── mobile-automator-executor/    # Your custom test runner\n```\n\n### Generate Your First Test\n\n```bash\n\u003e /mobile-automator:generate\n```\n\nWhen prompted, describe the test in natural language:\n\n**Example 1: Login Flow**\n```\n1. Launch the app\n2. Tap on \"Login\" button\n3. Enter email: test@example.com\n4. Enter password: Test123!\n5. Tap \"Sign In\"\n6. Validate user is logged in (shows profile icon)\n```\n\n**Example 2: Conversational Style**\n```\nfresh install -\u003e user opens app -\u003e wait for splash screen -\u003e\nvalidate bottom navigation shows 4 tabs: home, orders, offers, more\n```\n\n**What you get:**\n- 📄 `mobile-automator/scenarios/login_flow.json` - Structured test scenario\n- 📸 `mobile-automator/screenshots/login_flow/` - Reference screenshots\n- ✅ Ready to execute on any device\n\n### Execute Your Test\n\n```bash\n\u003e /mobile-automator:execute login_flow\n```\n\n**You'll see:**\n- ▶️ Real-time step execution on your device\n- 📊 Pass/fail status for each assertion\n- 🔍 Flakiness detection and retry logic\n- 📸 Screenshot comparison with visual analysis\n- 📝 Detailed failure reports with context\n\n---\n\n## 🏗️ Supported Platforms\n\n| Platform | Detection | Build Commands | Device Control |\n|----------|-----------|----------------|----------------|\n| **Android** | ✅ Native, Gradle | `./gradlew assembleDebug` | ✅ Emulator + Real Device |\n| **iOS** | ✅ Native, Xcode | `xcodebuild -scheme MyApp` | ✅ Simulator + Real Device |\n| **Flutter** | ✅ Cross-platform | `flutter build apk/ios` | ✅ All platforms |\n| **React Native** | ✅ Metro bundler | `npx react-native run-android/ios` | ✅ All platforms |\n| **Kotlin Multiplatform** | ✅ KMP structure | `./gradlew assembleDebug` | ✅ Android + iOS |\n| **Compose Multiplatform** | ✅ CMP structure | Gradle + Xcode | ✅ Android + iOS |\n\n---\n\n## 🧠 Intelligent Features\n\n### 1. Architecture Pattern Detection\nMobile Automator scans your codebase and recognizes:\n- **MVVM** (ViewModel, LiveData patterns)\n- **Clean Architecture** (domain, data, presentation layers)\n- **BLoC** (Flutter - Business Logic Component)\n- **Redux/MVI** (reducer, store, actions)\n- **MVP/VIPER** (presenter, interactor patterns)\n\n**Why it matters:** Skills are tailored to your architecture's naming conventions.\n\n### 2. Loading Indicator Auto-Detection\nGreps your source code for:\n- Android: `CircularProgressIndicator`, `ShimmerEffect`, `ProgressBar`\n- iOS: `UIActivityIndicatorView`, `ProgressView`, `SkeletonView`\n- Flutter: `CircularProgressIndicator`, `Shimmer`\n- React Native: `ActivityIndicator`, `SkeletonPlaceholder`\n\n**Why it matters:** Tests automatically wait for your specific loading patterns.\n\n### 3. Flakiness Detection \u0026 Diagnosis\nWhen tests fail, the executor:\n- 🔄 **Retries once** on suspected timing issues\n- 📊 **Flags flaky tests** with retry count\n- 🧪 **Analyzes root cause**: loading delay, animation, network dependency\n- 💡 **Suggests fixes**: \"Consider adding explicit wait for this step\"\n\n### 4. State-Aware Failure Analysis\nFailed assertions include context:\n- 🌓 Dark mode vs light mode mismatch\n- 📱 Device differences (Pixel 6 vs Pixel 8)\n- 🌐 Network state (WiFi vs cellular)\n- ⌨️ Keyboard visibility\n- 🔄 Orientation differences\n\n### 5. Semantic Visual Testing\nInstead of brittle pixel-matching:\n\u003e \"Does this screen fulfill the same purpose as the reference?\"\n\nUses AI vision to compare screenshots semantically, not pixel-by-pixel.\n\n---\n\n## 📋 Commands Reference\n\n| Command | Description | Usage | What It Does |\n|---------|-------------|-------|--------------|\n| **`/mobile-automator:setup`** | One-time setup - analyzes project and installs testing skills | `\u003e /mobile-automator:setup` | • Detects platform (Android/iOS/Flutter/React Native/KMP/CMP)\u003cbr\u003e• Discovers build environments (staging, production, etc.)\u003cbr\u003e• Infers app package IDs from build files\u003cbr\u003e• Analyzes architecture patterns and business domain\u003cbr\u003e• Installs customized QA skills\u003cbr\u003e• Creates `mobile-automator/` test directory\u003cbr\u003e• **Resume support:** If interrupted, run again to resume |\n| **`/mobile-automator:generate`** | **Record** test scenarios from natural language (do this once per test) | `\u003e /mobile-automator:generate` | • Connects to your device/emulator\u003cbr\u003e• Prompts for test steps in natural language\u003cbr\u003e• Executes steps on device while recording\u003cbr\u003e• Captures reference screenshots\u003cbr\u003e• Generates JSON scenario file (schema v2)\u003cbr\u003e**Output:** `mobile-automator/scenarios/\u003cscenario_id\u003e.json` |\n| **`/mobile-automator:execute`** | **Replay** saved test scenarios (run repeatedly for regression testing) | `\u003e /mobile-automator:execute \u003cscenario_id\u003e`\u003cbr\u003e\u003cbr\u003eExamples:\u003cbr\u003e• Single: `execute login_flow`\u003cbr\u003e• Multiple: `execute login_flow checkout_flow`\u003cbr\u003e• All: `execute` (interactive) | • Replays scenario steps on connected device\u003cbr\u003e• Captures actual screenshots for comparison\u003cbr\u003e• Validates assertions (element exists, text matches, visual state)\u003cbr\u003e• Detects flakiness and retries automatically\u003cbr\u003e• Generates detailed pass/fail report with diagnostics\u003cbr\u003e**Output:** `mobile-automator/results/\u003crun_id\u003e.json` |\n| **`/mobile-automator:migrate`** | **Migrate** a v1 scenario JSON to schema v2 format | `\u003e /mobile-automator:migrate \u003cscenario_id\u003e`\u003cbr\u003e\u003cbr\u003eExamples:\u003cbr\u003e• `migrate login_flow`\u003cbr\u003e• `migrate` (interactive file selection) | • Analyzes existing v1 scenario\u003cbr\u003e• Auto-converts step IDs, assertion IDs, metadata\u003cbr\u003e• Interactively resolves ambiguous waits\u003cbr\u003e• Creates `.v1.bak` backup before any changes\u003cbr\u003e• Outputs valid schema v2 scenario |\n| **`/mobile-automator:list-tags`**| Lists all tags currently used in test scenarios | `\u003e /mobile-automator:list-tags` | • Scans all JSON scenarios\u003cbr\u003e• Displays tag counts\u003cbr\u003e• Differentiates standard vs custom tags |\n| **`/mobile-automator:report`** | Generate aggregated test reports | `\u003e /mobile-automator:report`\u003cbr\u003e\u003cbr\u003eOptions:\u003cbr\u003e• `--last N` (default 10)\u003cbr\u003e• `--format table\\|json\\|html`\u003cbr\u003e• `--junit` (JUnit XML) | • Aggregates all test results\u003cbr\u003e• Shows pass rate, flaky steps, failures\u003cbr\u003e• Exports to JSON, HTML, or JUnit XML\u003cbr\u003e**Output:** `mobile-automator/results/report.{json,html,xml}` |\n\n## 🏷️ Tag-Based Filtering\n\nMobile Automator supports tagging scenarios logically (e.g. `smoke`, `regression`, `critical`) so you can execute specific subsets of your test suite.\n\n### Adding Tags\nDuring scenario generation (`/mobile-automator:generate`), the agent will ask you what tags describe the scenario before saving it. You can also manually add tags to the `scenario.json` file:\n\n```json\n{\n  \"$schema_version\": \"2.0\",\n  \"scenario_id\": \"login_flow\",\n  \"tags\": [\"smoke\", \"auth\", \"p0\"],\n  // ...\n}\n```\n\n### Filtering Executions\nUse the `--tag` parameter with `/mobile-automator:execute` to filter runs:\n\n- **Single tag:** `/mobile-automator:execute --tag smoke`\n- **Multiple tags (AND):** `/mobile-automator:execute --tag smoke,critical` (matches scenarios with BOTH tags)\n- **Multiple tags (OR):** `/mobile-automator:execute --tag smoke|regression` (matches scenarios with ANY tag)\n- **Exclude tags (NOT):** `/mobile-automator:execute --tag !flaky` (excludes scenarios with this tag)\n\nIf you run `/mobile-automator:execute` without arguments, the interactive menu will automatically group your scenarios by their primary tag.\n\n### Standard Tag Registry\nWe recommend standardizing on these common tags:\n- `smoke`: Quick validation of critical paths\n- `regression`: Full feature validation\n- `critical`, `p0`, `p1`: Priority levels\n- `fast`, `slow`: Execution time indicators\n- `flaky`: Network/timing dependent tests\n- `wip`: Under development\n\n---\n\n## Using TestRail\n\n**Optional:** Connect TestRail to auto-generate tests and sync results.\n\nSee [TESTRAIL.md](./TESTRAIL.md) for detailed setup and usage instructions.\n\n---\n\n### 📝 The Workflow\n\n1. **Generate once** - Use `/mobile-automator:generate` to record test scenarios by performing actions on your device\n2. **Execute many times** - Use `/mobile-automator:execute` to replay those scenarios automatically across devices/builds\n\n---\n\n## 📂 Project Structure\n\nAfter setup, your project will have:\n\n```\nyour-mobile-project/\n├── mobile-automator/                    # Test artifacts directory\n│   ├── config.json                     # Auto-generated project config\n│   ├── index.md                        # Documentation\n│   ├── scenarios/                      # Test scenario JSON files\n│   │   ├── login_flow.json\n│   │   └── checkout_flow.json\n│   ├── screenshots/                    # Reference screenshots\n│   │   ├── login_flow/\n│   │   │   ├── step_launch_app.png\n│   │   │   └── step_tap_login.png\n│   │   └── checkout_flow/\n│   └── results/                        # Test execution results\n│       ├── run_20250212_143022.json\n│       └── run_20250212_143022/\n│           └── screenshots/\n│\n└── .gemini/\n    └── skills/                         # Generated testing skills\n        ├── mobile-automator-generator/\n        │   ├── SKILL.md               # Customized for YOUR project\n        │   └── references/\n        │       ├── scenario_schema_v2.json  # Schema v2 (default)\n        │       └── scenario_schema.json     # Schema v1 (legacy)\n        └── mobile-automator-executor/\n            ├── SKILL.md               # Customized for YOUR project\n            └── references/\n                └── result_schema.json\n```\n\n---\n\n## 🔬 How It Works\n\n### The 3-Tier Architecture\n\n```\n┌─────────────────────────────────────┐\n│  TIER 1: Extension Commands         │\n│  /mobile-automator:setup                      │\n│  /mobile-automator:generate         │\n│  /mobile-automator:execute          │\n│  (Pre-flight checks, validation)    │\n└──────────────┬──────────────────────┘\n               │ delegates to\n┌──────────────▼──────────────────────┐\n│  TIER 2: Workspace Skills           │\n│  .gemini/skills/mobile-automator-*/ │\n│  (Test generation \u0026 execution logic)│\n└──────────────┬──────────────────────┘\n               │ uses\n┌──────────────▼──────────────────────┐\n│  TIER 3: Automation Engine          │\n│  mobile-mcp                         │\n│  (Device control primitives)        │\n└─────────────────────────────────────┘\n```\n\n**Why this design?**\n- ✅ **Separation of concerns** - infrastructure vs domain logic\n- ✅ **Project-specific skills** - tailored to your app\n- ✅ **Portable automation** - works across platforms\n\n---\n\n## 🎨 Test Scenario Schema\n\nTest scenarios are JSON files stored in `mobile-automator/scenarios/` following **schema v2** (default). Key fields:\n\n- **`$schema_version`**: `\"2.0\"` — required, enables version routing\n- **`scenario_id`**: Unique identifier (snake_case)\n- **`name`**: Human-readable description\n- **`platform`**: `\"android\"` | `\"ios\"` | `\"cross-platform\"`\n- **`variables`**: Named variables for capturing dynamic values across steps\n- **`preconditions`**: Structured object — `app_state`, `device_actions`, `device_properties`\n- **`steps`**: Array of actions — each step has a **named string `id`** (e.g., `\"tap_login\"`), plus:\n  - 14 action types: `launch_app`, `tap`, `long_press`, `double_tap`, `type`, `swipe`, `scroll_to_element`, `press_button`, `open_url`, `wait_for_element`, `wait_for_element_gone`, `wait_for_loading_complete`, `capture_value`, `clear_app_data`\n  - `optional: true` + `on_failure: \"skip\"` — for non-deterministic UI elements (dialogs, banners)\n  - `condition` — execute step only when a device property or runtime condition is met\n  - `retry_policy` — retry on transient failures before marking the step as failed\n  - `capture_to` — store a dynamic value for later assertion\n  - `sub_steps` — nested conditional sub-flow\n  - `wait_config` — smart wait parameters (`type`, `indicator`, `timeout_ms`)\n- **`assertions`**: Validation rules — each has a **named string `id`** and references its step by name (`after_step`):\n  - 9 types: `element_exists`, `element_not_exists`, `element_text`, `screenshot_match`, `pattern_match`, `value_matches_variable`, `element_count`, `visual_state`, `text_changed`\n\n\u003e **Migrating from v1?** Run `/mobile-automator:migrate \u003cscenario_id\u003e` or see [MIGRATION.md](MIGRATION.md).\n\nGenerated scenarios are project-specific and include your app's context (business domain, key features).\n\n---\n\n## 🐛 Troubleshooting\n\nFor common issues and solutions, see **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)**.\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! This project is open source under Apache 2.0 license.\n\n**Areas for contribution:**\n- Additional platform support\n- Enhanced architecture pattern detection\n- More assertion types\n- CI/CD integrations\n- Visual regression testing improvements\n\n---\n\n## 📄 License\n\nApache License 2.0 - See [LICENSE](LICENSE) for details.\n\n---\n\n## 🙏 Acknowledgments\n\n- **[Conductor](https://github.com/gemini-cli-extensions/conductor)** - Inspired the generator pattern and structured workflow approach\n- **[mobile-mcp](https://github.com/mobile-next/mobile-mcp)** - The automation engine powering device control\n- **Gemini CLI** - The AI-powered CLI platform\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Built with ❤️ for mobile QA engineers**\n\n[Report Bug](https://github.com/sh3lan93/mobile-automator/issues) · [Request Feature](https://github.com/sh3lan93/mobile-automator/issues) · [Documentation](https://github.com/sh3lan93/mobile-automator)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsh3lan93%2Fmobile-automator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsh3lan93%2Fmobile-automator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsh3lan93%2Fmobile-automator/lists"}