Quick Start¶

Get mobile-automator working in 5 minutes with a real test scenario.

This quick start uses Claude Code as the example agent. For Cursor, swap --agent claude → --agent cursor. For any other agent, see Using another agent.

Prerequisites¶

mauto installed and on your PATH (installation guide)
Mobile project directory (Android, iOS, Flutter, React Native, KMP, or CMP)
An AI coding agent (Claude Code, Cursor, Gemini CLI, GitHub Copilot, OpenAI Agents, or any MCP-capable agent)
Connected device or simulator

Step 1: Wire mobile-automator into Your Project¶

cd /path/to/your/mobile-app
mauto init --agent claude      # or: cursor | gemini | copilot | agents | all

init installs native Agent Skills into your host's skills directory and writes the agent command files + MCP server entry (.claude/commands/ + .mcp.json for Claude Code; .cursor/ for Cursor).

Step 2: Run Setup¶

mauto setup                    # add --mode agnostic for cross-platform apps

setup scaffolds the mobile-automator/ workspace and writes its config. Add --mode agnostic for cross-platform apps (Flutter/RN/KMP/CMP) so one scenario runs on Android and iOS.

What Gets Created¶

After setup completes:

mobile-automator/
├── config.json              # mode, environments, project config
├── scenarios/               # test scenario files (JSON, schema 2.1)
├── screenshots/             # reference screenshots
└── results/                 # test execution results

Read any config value with mauto config get <key>.

Step 3: Check Your Device Is Visible¶

Before generating a test, confirm mauto can see a device:

mauto devices                 # lists connected devices and emulators/simulators

If more than one device is listed, pin the one you want:

mauto devices use <id>        # pin a specific device (mauto devices clear to unpin)

Step 4: Generate a Test Scenario — From Inside Your Agent¶

Open your agent in the project. In Claude Code, init installs slash commands:

/mobile-automator-generate

This launches the generate workflow. Describe what you want to test:

Example prompt:

"Test the login flow: 1) Launch the app, 2) Tap the login button, 3) Enter email 'test@example.com', 4) Enter password 'password123', 5) Tap Sign In, 6) Wait for home screen to load, 7) Verify welcome message appears"

The agent drives the app through mauto verbs and writes a complete test scenario in JSON, including:

Step definitions (launch, tap, type, wait, etc.)
Assertions (element visibility, text content, etc.)
Capture values for later verification
Retry logic for flaky operations

A new scenario file is created in mobile-automator/scenarios/.

In Cursor, init installs a project rule instead — just ask the agent in plain language (e.g. "generate a login test"). Any other agent: run mauto mcp (MCP prompts server) or read mauto bootstrap + mauto guide generate, then call the verbs directly.

Step 5: Execute the Test¶

/mobile-automator-execute

The agent replays the scenario and:

Lists available scenarios
Confirms device connection
Installs a named artifact if you gave one; otherwise builds and installs (platform-aware) or asks you to install the app yourself (platform-agnostic)
Executes the scenario step by step
Captures observations (flakiness, regressions, state context)
Generates a detailed result report

Results are saved to mobile-automator/results/<run_id>.json.

Step 6: Review Results¶

Open the result file in your editor:

cat mobile-automator/results/<run_id>.json

The result includes:

{
  "run_id": "login_flow_20250227_143022",
  "scenario_id": "login_flow",
  "status": "passed",
  "steps_executed": [
    {
      "step_id": "launch_app",
      "status": "passed",
      "duration_ms": 2300
    },
    {
      "step_id": "tap_login_button",
      "status": "passed",
      "duration_ms": 450
    }
    // ... more steps
  ],
  "observations": [
    {
      "type": "regression",
      "message": "Login button styling differs from reference screenshot"
    }
  ]
}

Common Next Steps¶

Generate More Tests¶

Repeat Step 4 with different user flows:

Onboarding flow
Checkout flow
User profile editing
Search functionality
Data filtering

Organize Tests with Tags¶

Add tags to scenarios for easy filtering:

{
  "scenario_id": "login_flow",
  "tags": ["critical", "authentication", "smoke-test"],
  "actions": [ ... ]
}

Then ask your agent to execute only the critical-tagged scenarios.

Troubleshooting¶

No device listed by `mauto devices`¶

Ensure an emulator/simulator is running or a physical device is connected and authorized. See the installation guide for platform-specific device setup.

Generate can't find the app package¶

The app must be:

Built successfully in the project
Installed on the connected device/simulator

To reuse a build you already have, name the artifact path when you start the run and the agent installs it instead of rebuilding. Without an artifact, a platform-aware project builds and installs as needed; a platform-agnostic project asks you to install the app yourself.

Tests fail with "element not found"¶

Common causes:

App is still loading — Use wait_for_element in the scenario
Element is off-screen — Use scroll_to_element before tapping
Different environment — Verify you're testing the correct environment (staging vs production)

Check the result observations for hints about what went wrong.

What's Next?¶

Core Concepts — Understand the brain/hands architecture
Guides — Deep dive into each command
Reference — Complete list of assertion types
Examples — Real-world test scenarios

Congratulations! You've completed your first mobile test. Now explore the full documentation to master advanced features like result observations, custom assertions, and CI/CD integration.