appilot 0.1.9
Autopilot for mobile apps - MCP server for AI-driven Android and iOS automation
Requires Python: >=3.11
Keywords: ai-testing, android, appilot, appium, automation, claude, ios, mcp, mobile-testing

# Appilot

[![PyPI version](https://badge.fury.io/py/appilot.svg)](https://badge.fury.io/py/appilot)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)

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

## Installation

### Using uvx (Recommended)

No installation needed - runs directly:

```bash
# Run appilot
uvx appilot@latest serve

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

### Using pip

```bash
# Install
pip install appilot

# Update to latest version
pip install --upgrade appilot
```

## Quick Start with Claude Code

### Using uvx

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

### Using pip

```bash
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](https://nodejs.org/)
- **Xcode** (iOS) - App Store
- **Android SDK** (Android) - [Install Guide](https://developer.android.com/studio)

## CLI Commands

### Using uvx

```bash
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

```bash
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?**
```bash
uvx appilot@latest --version   # Test if appilot works
# or
appilot --version
```

**No devices found?**
```bash
# iOS - boot a simulator
xcrun simctl boot "iPhone 16 Pro"

# Android - check connection
adb devices
```

**Appium issues?**
```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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](https://pypi.org/project/appilot/)
- [MCP Protocol](https://modelcontextprotocol.io/)

---

## 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:
   ```bash
   mkdir -p ~/.claude/commands
   ```

2. Create the command file:
   ```bash
   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`:

````markdown
---
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