Mobile Testing

If multiple devices returned:

• Ask user to select one
• Store the selected device ID in a variable
• Proceed with that device ID

If only one device:

• Use it directly
• Optionally inform the user which device was selected

--# Step 2: Verify Device State

Call mcp__mobile-mcp__mobile_get_screen_size to confirm device is responsive.

Example response includes screen dimensions for coordinate calculations.

--# Step 3: Prepare Application State

For testing an app:

If app needs to be installed first:

mcp__mobile-mcp__mobile_install_app(
  device: deviceId,
  path: "/path/to/app.ipa"  // iOS
  // or
  path: "/path/to/app.apk"  // Android
)

If app needs to be launched:

mcp__mobile-mcp__mobile_launch_app(
  device: deviceId,
  packageName: "com.example.app"
)

If app is already running:

mcp__mobile-mcp__mobile_terminate_app(
  device: deviceId,
  packageName: "com.example.app"
)
// Then re-launch for clean state

--# Step 4: Perform Interactions

To click an element:

1. Call mcp__mobile-mcp__mobile_list_elements_on_screen(device: deviceId)
2. Identify target element coordinates from response
3. Call mcp__mobile-mcp__mobile_click_on_screen_at_coordinates(device: deviceId, x: x, y: y)

To type text:

mcp__mobile-mcp__mobile_type_keys(
  device: deviceId,
  text: "input text",
  submit: true  // or false if not submitting
)

To swipe/navigate:

mcp__mobile-mcp__mobile_swipe_on_screen(
  device: deviceId,
  direction: "up" | "down" | "left" | "right",
  distance: 400  // optional, uses defaults if omitted
)

To verify state:

mcp__mobile-mcp__mobile_take_screenshot(device: deviceId)
// or
mcp__mobile-mcp__mobile_list_elements_on_screen(device: deviceId)

--# Step 5: Verify Results

CRITICAL: ALWAYS verify outcomes after interactions.

1. Take screenshot: mcp__mobile-mcp__mobile_take_screenshot to capture current state
2. Check elements: mcp__mobile-mcp__mobile_list_elements_on_screen to verify expected elements exist
3. Compare against expectations: Report results to user

Interaction Patterns

Click Pattern

ALWAYS follow this sequence:

1. mcp__mobile-mcp__mobile_list_elements_on_screen → get coordinates
2. mcp__mobile-mcp__mobile_click_on_screen_at_coordinates → perform click
3. mcp__mobile-mcp__mobile_take_screenshot → verify change

NEVER click without first identifying the element.

Swipe Pattern

When swiping:

• direction must be: up, down, left, or right
• distance defaults: 400px (iOS) or 30% screen (Android)
• Specify distance when precise control needed

After swiping:

• Wait for animations (500ms implicit)
• Take screenshot to verify navigation occurred

Type Pattern

Before typing:

• Verify input field is focused (list elements to check)

When typing:

• Use submit: true to send Enter key
• Use submit: false for partial input

Note: Typing requires focused element. If typing fails, click the element first.

Orientation Pattern

To change orientation:

mcp__mobile-mcp__mobile_set_orientation(
  device: deviceId,
  orientation: "portrait" | "landscape"
)

When orientation matters:

• Set BEFORE interactions that depend on layout
• Verify with mcp__mobile-mcp__mobile_get_orientation before critical operations

Verification Checklists

Before Any Interaction

• Device selected and device ID stored
• App is in expected state
• Coordinates verified (for clicks)

After Any Interaction

• Screenshot captured
• Expected elements present
• Unexpected elements absent
• State change confirmed

Before Test Completion

• All screenshots saved or reviewed
• Results logged
• App returned to clean state (optional)
• User notified of outcome

Common Issues

--# Element Not Found

Symptom: mcp__mobile-mcp__mobile_list_elements_on_screen returns empty or unexpected elements.

Diagnosis:

1. Is the correct app launched?
2. Is the app on the expected screen?
3. Are there loading animations blocking the view?

Recovery:

// 1. Take screenshot to debug
mcp__mobile-mcp__mobile_take_screenshot(device: deviceId)

// 2. Try swiping to navigate
mcp__mobile-mcp__mobile_swipe_on_screen(device: deviceId, direction: "up")

// 3. Re-launch app for clean state
mcp__mobile-mcp__mobile_terminate_app(device: deviceId, packageName: package)
mcp__mobile-mcp__mobile_launch_app(device: deviceId, packageName: package)

--# Click Fails

Symptom: Click action completes but nothing happens.

Diagnosis:

1. Wrong coordinates (element moved)?
2. Overlapping elements?
3. Element disabled or not interactive?

Recovery:

// 1. Re-list elements (coordinates may have changed)
mcp__mobile-mcp__mobile_list_elements_on_screen(device: deviceId)

// 2. Try double-tap
mcp__mobile-mcp__mobile_double_tap_on_screen(device: deviceId, x: x, y: y)

// 3. Try long-press
mcp__mobile-mcp__mobile_long_press_on_screen_at_coordinates(device: deviceId, x: x, y: y)

--# Typing Fails

Symptom: Text not appearing or error on type.

Diagnosis:

1. No element focused?
2. Wrong input field?
3. Special characters not supported?

Recovery:

// 1. Click to focus first
mcp__mobile-mcp__mobile_click_on_screen_at_coordinates(device: deviceId, x: x, y: y)

// 2. Type without submit
mcp__mobile-mcp__mobile_type_keys(device: deviceId, text: "text", submit: false)

// 3. Submit separately if needed
mcp__mobile-mcp__mobile_press_button(device: deviceId, button: "ENTER")

--# App Crashes

Symptom: App becomes unresponsive after interaction.

Recovery:

// 1. Terminate and re-launch
mcp__mobile-mcp__mobile_terminate_app(device: deviceId, packageName: package)
mcp__mobile-mcp__mobile_launch_app(device: deviceId, packageName: package)

// 2. If persists, take screenshot for debugging
mcp__mobile-mcp__mobile_take_screenshot(device: deviceId)

// 3. Report to user with device state

Device Management

Listing Devices

mcp__mobile-mcp__mobile_list_available_devices()
// Returns: array of {id, name, type, ...}

Selecting a Device

For single device: Use directly.

For multiple devices:

Ask user: "Which device should I use? [1] iPhone 15, [2] Android Emulator"
Store selection and use that deviceId

Device Info

mcp__mobile-mcp__mobile_get_screen_size(device: deviceId)
// Returns: {width, height}
mcp__mobile-mcp__mobile_get_orientation(device: deviceId)
// Returns: {orientation: "portrait" | "landscape"}

App Management Reference

Best Practices

DO:

• ALWAYS select device first
• VERIFY state before and after actions
• USE screenshots for verification
• HANDLE errors with recovery attempts
• REPORT results clearly

DON'T:

• NEVER click without listing elements first
• DON'T assume coordinates are stable
• DON'T skip verification steps
• DON'T leave app in crashed state
• DON'T proceed after failures without diagnosis

Notes

• Coordinate system: top-left is (0, 0)
• All tools require device parameter
• Screen sizes vary by device model
• Wait times are implicit in tool calls
• Screenshot tool does not save automatically; use mobile_save_screenshot to persist