appilot 0.1.9

Autopilot for mobile apps - MCP server for AI-driven Android and iOS automation

Appilot

Autopilot for mobile apps - An MCP server that lets Claude automate Android and iOS apps.

Installation

Using uvx (Recommended)

No installation needed - runs directly:

# Run appilot
uvx appilot@latest serve

# Update to latest version
uvx --refresh appilot@latest --version

Using pip

# Install
pip install appilot

# Update to latest version
pip install --upgrade appilot

Quick Start with Claude Code

Using uvx

claude mcp add appilot -s user -- uvx appilot@latest serve

Using pip

claude mcp add appilot -s user -- appilot serve

Restart Claude Code. Done.

What You Can Do

Talk to Claude naturally:

"Connect to my iPhone and take a screenshot"

"Find the login button and tap it"

"Check the app's memory usage"

"Swipe up to scroll the list"

"Type my email in the input field"

Requirements

• Node.js 18+ - brew install node (macOS) or download
• Xcode (iOS) - App Store
• Android SDK (Android) - Install Guide

CLI Commands

Using uvx

uvx appilot@latest serve          # Start MCP server
uvx appilot@latest devices        # List devices
uvx appilot@latest health         # Health check
uvx appilot@latest status         # System status
uvx appilot@latest --version      # Check version
uvx --refresh appilot@latest --version  # Update & check version

Using pip

appilot serve          # Start MCP server
appilot devices        # List devices
appilot health         # Health check
appilot status         # System status
appilot --version      # Check version
pip install -U appilot # Update to latest

MCP Tools

Category	Tools
Session	create_session, end_session, list_devices
Screen	take_screenshot, get_screen_size, get_orientation
Elements	find_element, find_elements, get_page_source
Actions	tap, type_text, swipe, long_press
App	install_app, launch_app, terminate_app
Performance	get_memory_info, get_cpu_info, get_battery_info

Troubleshooting

MCP not connecting?

uvx appilot@latest --version   # Test if appilot works
# or
appilot --version

No devices found?

# iOS - boot a simulator
xcrun simctl boot "iPhone 16 Pro"

# Android - check connection
adb devices

Appium issues?

curl http://127.0.0.1:4723/status   # Check if running

Physical Device Testing

iOS Physical Device Setup

Testing on physical iOS devices requires code signing for WebDriverAgent. Follow these steps (one-time setup):

1. Sign into Xcode with Apple ID

# Open Xcode
open -a Xcode
# Go to: Xcode > Settings > Accounts > Add Apple ID
# Sign in with any Apple ID (free account works)

2. Set Your Team ID (Optional - auto-detected if signed into Xcode)

Find your Team ID at https://developer.apple.com/account or in Xcode:

• Open Xcode > Settings > Accounts > Select your account
• Click "Manage Certificates" - Team ID shown in parentheses

# Add to your shell profile (~/.zshrc or ~/.bashrc)
export APPLE_TEAM_ID=YOUR_TEAM_ID

3. Trust Developer Certificate on iPhone (First Time Only)

The first time you run Appilot on a physical device:

1. Connect your iPhone via USB
2. Run Appilot - it will fail with a signing error (this is expected)
3. On your iPhone: Settings > General > VPN & Device Management
4. Tap your Apple ID under "Developer App"
5. Tap "Trust" to allow apps from this developer
6. Run Appilot again - it should work now!

4. Verify Setup

# Check code signing - should show your Apple Team ID
appilot setup --check

# List devices - your iPhone should appear
appilot devices

# Test connection
appilot health

Note: Appilot auto-detects your Apple Team ID from your code signing certificates. Run appilot setup --check to verify detection. If not detected, set APPLE_TEAM_ID environment variable manually.

Android Physical Device Setup

1. Enable USB Debugging

On your Android device:

1. Go to Settings > About Phone
2. Tap Build Number 7 times to enable Developer Mode
3. Go to Settings > Developer Options
4. Enable USB Debugging

2. Connect and Verify

# Connect device via USB and verify
adb devices

# Should show your device:
# List of devices attached
# ABC123XYZ    device

3. Allow USB Debugging

When you connect, your phone will prompt "Allow USB debugging?"

• Check "Always allow from this computer"
• Tap "Allow"

Troubleshooting Physical Devices

iOS: "xcodebuild failed with code 65"

• Xcode not signed in, or Team ID not set
• Run: security find-identity -v -p codesigning to check certificates

iOS: "WebDriverAgent not trusted"

• Need to trust certificate on device (step 3 above)

iOS: "Device is locked"

• Unlock your iPhone and keep it unlocked during testing

Android: "Device unauthorized"

• Check for USB debugging prompt on phone
• Revoke USB debugging in Developer Options, then re-enable

Android: "adb not found"

• Install Android SDK: brew install android-platform-tools (macOS)

Links

• PyPI
• MCP Protocol

---

Claude Code Custom Command: /test-mobile-app

You can add a powerful end-to-end mobile testing command to Claude Code that leverages Appilot MCP.

How to Add the Command

1. Create the commands directory if it doesn't exist:

   mkdir -p ~/.claude/commands
   

2. Create the command file:

   touch ~/.claude/commands/test-mobile-app.md
   

3. Copy the command content below into ~/.claude/commands/test-mobile-app.md

4. Restart Claude Code

Usage

Once installed, run in Claude Code:

/test-mobile-app [app-path-or-bundle-id] [platform]

Examples:

/test-mobile-app com.example.myapp ios
/test-mobile-app ./build/MyApp.app ios
/test-mobile-app com.example.myapp android
/test-mobile-app ./build/app-debug.apk android

Command Content

Save the following content to ~/.claude/commands/test-mobile-app.md:

---
description: Comprehensive end-to-end mobile app testing using Appilot MCP - analyzes codebase, discovers UI, and tests all functionality
argument-hint: [app-path-or-bundle-id] [platform ios|android]
allowed-tools: Read, Glob, Grep, Bash, Write, Task, mcp__appilot__*
---

# Comprehensive Mobile App End-to-End Testing with Appilot

You are an expert mobile QA engineer. Your mission is to perform comprehensive end-to-end testing of a mobile application using the Appilot MCP server. You must be thorough, methodical, and report all findings.

## Arguments

- `$1` - App path (.app/.ipa/.apk) OR bundle ID/package name (e.g., "com.example.app")
- `$2` - Platform: "ios" or "android" (defaults to "ios")

---

## PHASE 1: CODEBASE ANALYSIS & TEST PLANNING

### 1.1 Project Discovery

First, understand what you're testing by analyzing the codebase:

```
SEARCH FOR:
- Package.json, pubspec.yaml, build.gradle, Podfile, *.xcodeproj - identify framework
- App entry points (App.tsx, main.dart, MainActivity, AppDelegate)
- Navigation structure (routes, screens, pages directories)
- API/Network layer (services, api, network directories)
- State management (redux, provider, bloc, zustand)
- Authentication flows (login, auth, signin)
- Key features and screens
```

Use Glob and Grep to find:
- `**/screens/**` or `**/pages/**` - UI screens
- `**/components/**` - Reusable components
- `**/services/**` or `**/api/**` - Backend integration
- `**/models/**` or `**/types/**` - Data structures
- `**/*.test.*` or `**/*.spec.*` - Existing tests for insights

### 1.2 Build Test Matrix

Based on codebase analysis, create a test matrix covering:

| Category | Test Cases | Priority |
|----------|------------|----------|
| App Launch | Cold start, warm start, deep links | Critical |
| Authentication | Login, logout, session persistence | Critical |
| Navigation | All screen transitions, back navigation | High |
| Core Features | Main app functionality | High |
| Forms & Input | Text entry, validation, submission | High |
| Data Display | Lists, details, loading states | Medium |
| Error Handling | Network errors, invalid input | Medium |
| Performance | Load times, memory, responsiveness | Medium |
| Edge Cases | Empty states, long text, special chars | Low |

---

## PHASE 2: ENVIRONMENT SETUP & VERIFICATION

### 2.1 Appilot MCP Health Check

Execute these checks in order - STOP if any critical check fails:

```
CRITICAL CHECKS:
1. health_check - Verify MCP server responding
2. get_status - Check Appium server status
3. list_devices - Find available devices
```

Report format:
```
[ENVIRONMENT CHECK]
MCP Server: ✓ Connected (version X.X.X)
Appium: ✓ Running at http://127.0.0.1:4723
Devices Found:
  - iOS: X devices (list names)
  - Android: Y devices (list names)
```

### 2.2 Device Selection & Session Creation

Select optimal device for testing:
- Prefer booted/online devices
- Prefer simulators/emulators for consistency
- For iOS: Boot simulator if none running (`xcrun simctl boot <UDID>`)

Create session:
```
create_session(
  platform: "$2" or "ios",
  device_id: <selected_device_udid>,
  capabilities: {
    app: "$1" (if path),
    bundleId: "$1" (if bundle ID),
    noReset: true
  }
)
```

Record session_id for all subsequent operations.

---

## PHASE 3: APP INSTALLATION & LAUNCH TESTING

### 3.1 App Installation (if app path provided)

```
IF $1 is a file path:
  1. install_app(app_path: "$1")
  2. Verify installation with is_app_installed()
  3. Record installation time
```

### 3.2 App Launch Tests

```
TEST: Cold Start
  1. terminate_app() - ensure app not running
  2. Record start time
  3. launch_app(bundle_id/package)
  4. Wait for main screen (take_screenshot, analyze)
  5. Record launch duration
  PASS: App launches within 5 seconds, main UI visible

TEST: App State Verification
  1. get_app_state()
  PASS: Returns RUNNING_IN_FOREGROUND (4)

TEST: Screenshot Capture
  1. take_screenshot()
  2. Save to ./test-results/screenshots/launch.png
  PASS: Screenshot captured successfully
```

---

## PHASE 4: UI DISCOVERY & MAPPING

### 4.1 Screen Analysis

For the current screen:
```
1. get_page_source() - Get full UI hierarchy
2. get_accessibility_tree() - Get accessible elements
3. take_screenshot() - Visual reference

EXTRACT:
- All interactive elements (buttons, inputs, links)
- Text content and labels
- Element hierarchy and relationships
- Accessibility identifiers
```

### 4.2 Navigation Discovery

```
DISCOVER ALL SCREENS:
1. Identify navigation elements (tabs, menus, buttons)
2. For each navigation element:
   a. Record current screen state
   b. tap() on element
   c. Wait for transition
   d. take_screenshot()
   e. get_page_source()
   f. Record new screen
   g. Navigate back if possible
3. Build screen map with transitions
```

Create navigation graph:
```
Screen Map:
├── Home Screen
│   ├── [Tab: Profile] → Profile Screen
│   ├── [Tab: Settings] → Settings Screen
│   └── [Button: New] → Create Screen
├── Profile Screen
│   └── [Button: Edit] → Edit Profile Screen
...
```

---

## PHASE 5: FUNCTIONAL TESTING

### 5.1 Element Interaction Tests

For each discovered interactive element:
```
TEST: Element Visibility
  1. find_element(strategy, locator)
  PASS: Element found and visible

TEST: Tap Interaction
  1. tap(element_id)
  2. Verify response (screen change, state change, feedback)
  PASS: Tap registered, expected response occurred

TEST: Text Input (for input fields)
  1. find_element() - locate input
  2. tap() - focus input
  3. type_text("test input")
  4. get_element_attribute(element, "value")
  PASS: Text entered correctly
```

### 5.2 Core Flow Testing

Based on codebase analysis, test critical user flows:

```
FLOW: User Authentication (if applicable)
  1. Navigate to login screen
  2. find_element() - username field
  3. type_text() - enter test username
  4. find_element() - password field
  5. type_text() - enter test password
  6. find_element() - login button
  7. tap() - submit
  8. Wait for response
  9. Verify success/failure state
  PASS: Login flow completes, appropriate response

FLOW: Main Feature Usage
  [Dynamically generate based on codebase analysis]

FLOW: Data Display
  1. Navigate to list/data screen
  2. Verify data loads (elements present)
  3. Test scroll if applicable: swipe(direction: "up")
  4. Test item selection if applicable
  PASS: Data displays correctly, interactions work
```

### 5.3 Gesture Tests

```
TEST: Swipe/Scroll
  1. swipe(start_x, start_y, end_x, end_y)
  2. Verify scroll occurred (element positions changed)
  PASS: Swipe gesture recognized

TEST: Long Press (if applicable)
  1. Find element supporting long press
  2. long_press(element_id, duration: 1000)
  3. Verify context menu or action triggered
  PASS: Long press action triggered
```

---

## PHASE 6: PERFORMANCE & STABILITY

### 6.1 Performance Metrics

```
COLLECT:
1. get_memory_info() - Memory usage
2. get_cpu_info() - CPU utilization
3. get_battery_info() - Battery impact (if physical device)

ANALYZE:
- Memory: Baseline < 100MB typical, warn if > 200MB
- CPU: Idle < 5%, active < 50% typical
- Look for memory growth over time (potential leaks)
```

### 6.2 Stability Tests

```
TEST: Rapid Interactions
  1. Perform 10 rapid taps on same element
  2. Verify no crash, UI remains responsive
  PASS: App handles rapid input

TEST: Background/Foreground
  1. background_app(duration: 5)
  2. activate_app()
  3. Verify app state restored
  PASS: App resumes correctly

TEST: Orientation Change (if supported)
  1. get_orientation()
  2. set_orientation("landscape")
  3. take_screenshot()
  4. Verify UI adapts
  5. set_orientation("portrait")
  PASS: Orientation change handled
```

---

## PHASE 7: ERROR HANDLING & EDGE CASES

### 7.1 Input Validation

```
TEST: Empty Input Submission
  1. Find form with required fields
  2. Leave fields empty
  3. Submit form
  4. Verify error message displayed
  PASS: Validation error shown

TEST: Invalid Input
  1. Enter invalid data (wrong format, special chars)
  2. Submit
  3. Verify appropriate error handling
  PASS: Invalid input rejected gracefully

TEST: Long Text Input
  1. Enter very long string (500+ chars)
  2. Verify truncation or scroll behavior
  PASS: Long text handled without crash
```

### 7.2 Network Conditions (if testable)

```
TEST: Offline Behavior
  1. Note: May require device-level network control
  2. Verify offline indicators if applicable
  3. Verify cached data display
  PASS: App handles offline gracefully
```

---

## PHASE 8: CLEANUP & REPORTING

### 8.1 Session Cleanup

```
1. terminate_app() - Close app cleanly
2. end_session() - Release Appium session
3. Verify cleanup successful
```

### 8.2 Generate Test Report

Create detailed report at `./test-results/report.md`:

```markdown
# Mobile App Test Report

**Generated:** <timestamp>
**App:** $1
**Platform:** $2
**Device:** <device_name>
**Duration:** <total_time>

## Summary

| Category | Passed | Failed | Skipped | Total |
|----------|--------|--------|---------|-------|
| Environment | X | X | X | X |
| Launch | X | X | X | X |
| Navigation | X | X | X | X |
| Functional | X | X | X | X |
| Performance | X | X | X | X |
| Stability | X | X | X | X |
| **TOTAL** | **X** | **X** | **X** | **X** |

## Overall Result: PASS/FAIL

## Detailed Results

### Environment Setup
[Details for each check]

### App Launch Tests
[Details for each test]

### UI Discovery
[Screen map and element inventory]

### Functional Tests
[Details for each test with screenshots]

### Performance Metrics
[Memory, CPU, battery data]

### Issues Found
1. [Issue description, severity, reproduction steps]
2. ...

## Screenshots

All screenshots saved to: ./test-results/screenshots/

## Recommendations

[Based on findings, suggest improvements]
```

### 8.3 Save Artifacts

```
./test-results/
├── report.md
├── screenshots/
│   ├── launch.png
│   ├── screen_home.png
│   ├── screen_profile.png
│   └── ...
├── logs/
│   └── test_execution.log
└── data/
    ├── page_sources/
    ├── accessibility_trees/
    └── performance_metrics.json
```

---

## EXECUTION INSTRUCTIONS

1. **Start with Phase 1** - Understand the codebase before testing
2. **Be thorough** - Don't skip steps, document everything
3. **Adapt dynamically** - If you discover features not in codebase analysis, test them
4. **Fail gracefully** - If a test fails, log it and continue
5. **Take screenshots** - Visual evidence for every significant state
6. **Think step by step** - Use extended thinking for complex decisions
7. **Report continuously** - Update user on progress after each phase

## BEGIN TESTING

Start by announcing:
```
===========================================
APPILOT END-TO-END TEST SUITE
===========================================
App: $1
Platform: $2
Timestamp: <current_time>
===========================================

Beginning Phase 1: Codebase Analysis...
```

Then proceed systematically through all phases.

What This Command Does

The /test-mobile-app command instructs Claude to:

1. Analyze your codebase - Understands your app structure, frameworks, and features
2. Set up testing environment - Verifies MCP connection, Appium, and devices
3. Install and launch app - Tests cold start and app state
4. Discover UI - Maps all screens and navigation paths
5. Run functional tests - Tests all interactive elements and user flows
6. Check performance - Collects memory, CPU, and battery metrics
7. Test edge cases - Validates error handling and input validation
8. Generate report - Creates detailed test report with screenshots

Requirements

• Appilot MCP server configured in Claude Code
• iOS Simulator or Android Emulator running
• App installed or .app/.apk file available