🚀 AppPilot Mobile — The Master Guide

Welcome to the world-class documentation for AppPilot Mobile. This framework is designed to be the "Playwright for Mobile" — a Python-first, human-readable automation engine that handles the complexity of mobile UI so you can focus on writing tests.

🏗️ 1. Professional Architecture (POM)

AppPilot is optimized for the Page Object Model (POM). By following this structure, your tests will be readable, maintainable, and stable.

1.1 Screen Transition Example

In this model, the LoginScreen fills in credentials, taps submit, and then instantiates and returns the next screen (DashboardScreen):

class LoginScreen:

    def login(self, username, password) -> DashboardScreen:
        self.mobile.input("Username").fill(username)
        self.mobile.input("Password").fill(password)
        self.mobile.button("Login").tap()
        
        return DashboardScreen(self.mobile)

1.2 Handling Elements Without Text Dynamically

You do not need separate methods (like tap_xpath() or tap_by_id()) for elements without text. The exact same public methods (mobile.tap(), mobile.fill(), etc.) handle all targets dynamically:

• Accessibility ID / Content Description:

  mobile.tap("shopping_cart_icon")  # Taps by accessibility label even if there is no text.
  

• Resource ID:

  mobile.tap("com.example.app:id/submit_btn")  # Identifies the developer-assigned element ID.
  

• Placeholder / Hint Text:

  mobile.tap("Enter your password")  # Text
  

• XPath Fallback:

  mobile.tap("//android.widget.FrameLayout[1]/android.widget.Button[2]")  # Triggers automatically if starting with "//".
  

🛠️ 2. Developer & Diagnostic Tools

2.1 Device Diagnostic (mobile.diagnose())

Provides a complete health check of the device and the automation environment.

• System Info: Model, Android version, and Serial.
• App State: Package and Activity currently in focus.
• Performance: Real-time Memory (MB) and CPU (%) usage.
• Usage:

mobile.diagnose()

📊 3. Complete API Reference

🏗️ 4. CLI Tooling Reference

📂 5. Configuration (apppilot.yaml)

# apppilot.yaml
tools:
  adb_path: 'C:\path\to\adb.exe'
  scrcpy_path: 'C:\path\to\scrcpy.exe'
  log_path: '.apppilot/logs'  # Custom log folder

mirror_screen: true
auto_scroll: true
timeout: 30
recorder_refresh_delay: 1.5  # Time (in seconds) to wait for screen transitions before refreshing the recorder view

Note for Windows Users: Always use single quotes ' for paths to avoid errors with backslashes.

🛠️ 6. Discovery & Debugging Example

When you are automating a new app and don't know the IDs, use this "Discovery Script" to find everything you need.

import pytest
from apppilot.api.mobile import Mobile

def test_discovery_session(mobile):
    # 1. Launch the app and check health
    mobile.launch_app("com.android.chrome")
    mobile.diagnose()  # Prints CPU/Memory and current Activity
    
    # 2. Navigate to a complex page
    mobile.navigate("https://www.google.com")
    mobile.wait_for_page_ready()
    
    # 3. Inspect the UI to find hidden locators
    # This will print every INPUT, BUTTON, and TEXT with coordinates
    mobile.inspect()
    
    # 4. Use Relational Selectors for elements without IDs
    # "Find the input to the right of the Google Search icon"
    mobile.right_of("Google Search").input().fill("AppPilot Mobile")
    
    # 5. Check performance after interaction
    perf = mobile.get_performance()
    print(f"Current App Memory Usage: {perf['memory_mb']} MB")
    
    mobile.press_key(66) # Enter
    mobile.screenshot("discovery_result")

© 2026 AppPilot Mobile Framework | Built for Engineers.