Verify On Device

Verify on Device

Build, install, and visually verify the app on an Android emulator or physical device. The skill prefers the Android CLI for agents (android) when installed and falls back to mobile-mcp + adb otherwise.

Prerequisites: Node.js v22+, Android SDK with platform-tools, and an emulator or device to target (step 0 can provision one when the Android CLI is installed).

Optional: Google's Android CLI for agents (android). When present, the skill uses android run for combined install+launch, android layout --diff for low-token screen-transition polling, and android docs for platform-API lookups. If not installed, every step falls back to the mobile-mcp / adb path with no behavior change.

Detect the Android CLI Once Per Session

Run this probe once at the start of a verification task and cache the result. Every CLI-based block in this skill is gated on USE_ANDROID_CLI=1.

The probe validates that android on PATH is Google's agent CLI (prints a semver like 0.7.15232955) and not the deprecated Android SDK android tool from tools/, which shadows it whenever the legacy SDK tools dir is on PATH. The probe only detects — it does not mutate PATH or create symlinks, since an in-script export PATH would not survive subsequent shell invocations in this skill. If android is missing, shadowed, or broken, it sets USE_ANDROID_CLI=0 and prints a hint pointing at the canonical install location (~/.android/bin/android-cli) when present. Exact PATH/symlink fix depends on the user's environment — the goal is to make android --version resolve to the agent CLI; the user applies the fix once in their shell rc so it persists.

The probe also writes USE_ANDROID_CLI to /tmp/.verify_on_device.env. Each subsequent Bash tool call starts a fresh shell, so a plain shell variable would be lost between invocations — every gated block in this skill begins by sourcing that file to restore the cached result.

_android_is_agent_cli() {
  android --version 2>&1 | grep -qE '^[0-9]+\.[0-9]+\.'
}

if command -v android >/dev/null 2>&1 && _android_is_agent_cli; then
  USE_ANDROID_CLI=1
  android --version   # log for reproducibility
else
  USE_ANDROID_CLI=0
  if [ -x "$HOME/.android/bin/android-cli" ]; then
    echo 'NOTE: Agent CLI binary is at ~/.android/bin/android-cli but `android` does not resolve to it (likely missing symlink or shadowed by the legacy Android SDK tool).'
    echo 'Fix: update your PATH/symlinks until `android --version` prints a semver (e.g. symlink android-cli to a name `android` on a directory earlier in PATH than the legacy Android SDK tools), then restart the session.'
  fi
fi

# Persist for subsequent Bash invocations (shell state does not survive
# across separate Bash tool calls). Subsequent gated blocks `source` this.
echo "USE_ANDROID_CLI=$USE_ANDROID_CLI" > /tmp/.verify_on_device.env

If USE_ANDROID_CLI=0, follow the fallback blocks (labelled "Fallback") throughout this skill.

Verification Status of Agent-CLI Blocks

The USE_ANDROID_CLI=0 fallback paths in this skill (mobile-mcp + adb) have been exercised end-to-end against this repo. The USE_ANDROID_CLI=1 blocks were all re-run against agent CLI 0.7.15232955 on 2026-04-21 against this repo. Results:

If a CLI block fails in practice, do not assume the docs are right. Fall back to the USE_ANDROID_CLI=0 path for that step, file the discrepancy as a skill issue, and fix it in the skill before the next run.

Critical Rule: Default to Main App (Store Management)

Unless the task explicitly mentions POS, Point of Sale, or WooPos, always operate in the main app (store management) context — MainActivity with bottom navigation tabs. This applies to all workflows: creating orders, viewing products, collecting payments, etc. The main app is the default; POS is only used when specifically requested.

Critical Rule: Always Restart the App

Do NOT attempt to recover from the current screen state when you start a task. Always force-stop the app and relaunch it to start from a known state (the dashboard or POS). This avoids wasted time navigating out of unknown screens.

Restarting is not resetting. Preserve and reuse a coherent authenticated session whenever one exists. Never uninstall the app or clear its data merely to begin verification, and install APK updates without clearing app data.

adb -s <device_id> shell am force-stop com.woocommerce.android.dev
adb -s <device_id> shell am start -n com.woocommerce.android.dev/com.woocommerce.android.ui.main.MainActivity

For POS tasks (only when explicitly requested):

adb -s <device_id> shell am force-stop com.woocommerce.android.dev
adb -s <device_id> shell am start -n com.woocommerce.android.dev/com.woocommerce.android.ui.woopos.root.WooPosActivity

Critical Rule: Never Estimate Tap Coordinates From Raw Screenshots

NEVER estimate tap coordinates directly from a raw (un-annotated) screenshot. Screenshots are scaled down from the actual device resolution (e.g., a 1080x2400 device produces a ~480x1065 screenshot). Coordinates derived from raw screenshots will be systematically wrong.

Use one of the two workflows below. Both translate a human-readable target (an accessibility label, a visual element) into exact device-pixel coordinates — neither relies on pixel-measuring a screenshot.

Option A — Accessibility-tree workflow (default)

1. Call mobile_list_elements_on_screen to get elements with their device-pixel coordinates
2. Compute tap target as the center of the element's bounding rect: tap_x = x + width/2, tap_y = y + height/2
3. Call mobile_click_on_screen_at_coordinates with those computed coordinates
4. Call mobile_take_screenshot AFTER tapping to visually confirm the result

Only use mobile_take_screenshot for visual verification — never for deriving coordinates.

Option B — Visual-label workflow (USE_ANDROID_CLI=1)

Useful when an element lacks an accessibility label or test tag, or when you already have an annotated screenshot in context. android screen capture --annotate overlays numeric labels (#1, #2, ...) on every interactive element; android screen resolve substitutes #N placeholders in a template string with the element's device-pixel x y coordinates.

The android screen ... commands do not support --device, so use this workflow only when the CLI's default device is the same device you intend to tap.

# Capture an annotated screenshot — each interactive element gets a number.
android screen capture --annotate --output=/tmp/ui.png

# Idiomatic: let resolve produce a complete `input tap X Y` command and pipe
# it straight to `adb shell`. The CLI replaces `#5` with the resolved coords.
android screen resolve --screenshot=/tmp/ui.png --string="input tap #5" \
  | adb -s <device_id> shell

# Alternative: capture just the coordinates and feed mobile-mcp's tap tool.
COORDS=$(android screen resolve --screenshot=/tmp/ui.png --string="#5")
# $COORDS is now "<x> <y>"; call mobile_click_on_screen_at_coordinates with those.

Option A remains the default — accessibility-tree coordinates are stable and don't require visual inspection. Reach for Option B when Option A does not surface the element you need.

Waiting for Screen Transitions

After every navigation action (tap, BACK press, app launch, swipe), the screen may be animating or loading data. ALWAYS follow one of the two stabilization protocols below.

Preferred: Diff-Based Polling (USE_ANDROID_CLI=1)

android layout --diff returns only the elements that changed since the last snapshot, instead of re-reading the entire accessibility tree (50-200+ elements per call). This is the single biggest token-consumption win over repeated mobile_list_elements_on_screen calls — measure on your own flow to confirm the magnitude.

Always pass --device=<device_id> to keep these calls pinned to the same device chosen in step 1; without it, android layout may target a different connected device than the one the app was launched on.

# `[[:space:]]*` around the colon makes the pattern tolerant of both
# compact and pretty-printed JSON, so a stray --pretty in the chain
# doesn't silently break the grep.
TARGET='"resource-id"[[:space:]]*:[[:space:]]*"com.woocommerce.android.dev:id/ordersList"'

# Baseline snapshot immediately after the action — also greppable: if the
# transition was instantaneous, the target is already on screen and every
# subsequent --diff would return empty (diffs are delta-only).
android layout --device=<device_id> --pretty --output=/tmp/layout_t0.json
if ! grep -qE "$TARGET" /tmp/layout_t0.json; then
  # Poll diffs until the expected target appears (1 second between polls).
  for i in 1 2 3 4 5; do
    android layout --device=<device_id> --diff --output=/tmp/layout_diff.json
    grep -qE "$TARGET" /tmp/layout_diff.json && break
    sleep 1
  done
  # Safety net — one full-layout read in case the target arrived between
  # two diffs but didn't change after that (so no later diff mentions it).
  android layout --device=<device_id> --pretty --output=/tmp/layout_final.json
  grep -qE "$TARGET" /tmp/layout_final.json || echo "Target not found after polling."
fi

Replace the TARGET pattern with the resource-id, Compose test tag, or content-description of the screen you expect to land on (see the WooCommerce Navigation Reference). Compose test tags surface as resource-id because testTagsAsResourceId is on, so the example pattern works for both — but content-description lives under a different JSON key (typically content-desc), so swap the key, not just the value.

Fallback: Repeated Layout Reads (no android CLI)

1. Call mobile_list_elements_on_screen after the action.
2. If the expected target element is NOT present, call mobile_list_elements_on_screen again. Each tool round-trip takes ~1-2 seconds, which provides sufficient implicit delay.
3. Repeat up to 5 times.
4. If after 5 attempts the expected element is still missing, take a screenshot for diagnosis and report the issue.

Guidance That Applies to Both Paths

Loading indicators to watch for:

• Skeleton/shimmer views (animated placeholder content) — the screen is loading data, keep waiting.
• CircularProgressIndicator or ProgressBar elements — an operation is in progress, keep waiting.
• Empty state views with text like "No orders yet" — the screen IS loaded, just empty. Do NOT keep waiting.

When NOT to retry: If the layout (full or diff) returns the same result 3 times in a row with no change, the screen is stable. The element you want is genuinely not present — consider scrolling or navigating differently.

Timing Guidelines

Text Input Workflow

Typing text into a field requires a specific sequence:

1. Find the input field using mobile_list_elements_on_screen. Look for elements with type EditText, TextField, or hint text like "Search".
2. Tap the field using mobile_click_on_screen_at_coordinates at its center to give it focus. The soft keyboard will appear.
3. Confirm focus — call mobile_list_elements_on_screen to verify the field is focused.
4. Type the text using mobile_type_keys. Set submit: false unless you want to press Enter after typing.
5. Dismiss the keyboard if needed: call mobile_press_button with BACK. On Android, the first BACK press while the keyboard is visible dismisses the keyboard only — it does NOT navigate back. A second BACK press would navigate back.

Common pitfall: Calling mobile_type_keys without first tapping the input field types into whatever element last had focus (or nothing).

Search fields: The orders and products lists use a toolbar search icon. Tap the magnifying glass icon first, wait for the search field to expand, then type into the expanded field.

Handling Unexpected Dialogs

WooCommerce may show dialogs automatically on launch or during navigation. Detect and dismiss these before proceeding.

After launching the app or navigating to a new screen, call mobile_list_elements_on_screen and check for:

General dialog dismissal strategy: Look for a dismiss/close/cancel button and tap it. If none visible, try mobile_press_button with BACK. If BACK doesn't work (non-cancellable dialogs), look for any actionable button ("OK", "Save", "Got it") and tap it. After dismissing, call mobile_list_elements_on_screen to confirm the dialog is gone.

Finding Elements That Require Scrolling

When mobile_list_elements_on_screen does not return the element you expect, it may be off-screen:

1. Call mobile_list_elements_on_screen and check for the target element.
2. If not found, call mobile_swipe_on_screen with direction up (swipe up = scroll down) from the center of the screen.
3. Call mobile_list_elements_on_screen again.
4. Repeat up to 10 times. If the same elements keep appearing (no new content), you have reached the bottom of the list.
5. If still not found, try scrolling back up (direction down) or try an alternative navigation path.

Tip: To scroll within a specific scrollable container (not the full screen), use the container's center coordinates as the swipe starting point.

Working with Element Lists

mobile_list_elements_on_screen can return 50-200+ elements. To find what you need:

• By resource identifier (most reliable): Match the identifier field (e.g., com.woocommerce.android.dev:id/ordersList). Resource IDs are stable across app versions.
• By display text: Match the element's text or label field. Useful for finding specific list items (e.g., order "#1234").
• By position: Elements are returned in document order (top to bottom, left to right). Toolbar/status bar elements appear first, list items in visual order.

Compose vs View elements: View-based screens have stable com.woocommerce.android.dev:id/* identifiers. Compose-based screens (Dashboard cards, Settings, newer screens) may lack resource IDs — rely on contentDescription or display text instead.

Authentication and Session Preservation

Prefer an already coherent, authenticated app session. Upgrade/reinstall the APK in place so app data is preserved; do not call mobile_uninstall_app or pm clear unless the task explicitly requires destructive clean-state testing.

After launch, inspect the screen:

• If the dashboard for the expected target appears, preserve and reuse that session.
• If login is required, the target is not the expected store, or the session cannot be confirmed, invoke tools/agent-login/agent-login.sh with the target flavor, selected serial, and Android user. It uses the deterministic default profile. Add --profile <name> only when the user or task explicitly supplies that nonsecret override. Do not list, open, read, or print profile files. Report only the script's sanitized outcome.
• On PROFILE_ERROR, ask the user to complete the one-time profile setup documented in references/agent-auto-login.md, or to log in manually on the device. Never ask for credentials in chat.

ALREADY_ACTIVE means the selected session matches the requested target and connection. A different selected store or connection returns CONFLICT; auto-login never replaces it. The dev tool assumes the configured target is connected, the account has the correct role and eligibility, and WordPress.com does not require 2FA. The app may surface store configuration errors after login. Do not run agent auto-login concurrently with manual login or another login flow; it reuses production WordPress.com and Jetpack repositories, whose global auth events are not request-correlated. Never synthesize or modify a credential profile to work around a failure, and never retry OUTCOME_UNKNOWN automatically. See references/agent-auto-login.md and load references/main-app-login.md when login is encountered.

Steps

Shortcut: If the app is already installed with a coherent session, preserve it and skip to step 6 (Set Up API Mocks) when a mock response is required.

0. Provision an Emulator (Optional, macOS/Linux only — Experimental)

Only run this step when no physical device is attached, no emulator is running, and the task requires a clean-slate device. Skip otherwise.

Status: experimental. Of the three emulator subcommands used here, only android emulator list has been exercised end-to-end against this repo. android emulator create, start, and stop were shape-confirmed via --help only — no AVD was created during PR verification. Expect to iterate on this step the first time you actually use it; if it fails, fall back to booting the emulator manually via Android Studio or emulator -avd <name> and continue from step 1.

. /tmp/.verify_on_device.env  # restore USE_ANDROID_CLI from the probe step

# `android emulator` is disabled on Windows per Google's docs — detect Git
# Bash / MSYS / Cygwin and skip there. macOS and Linux both reach the `then`.
case "$(uname -s)" in MINGW*|MSYS*|CYGWIN*) IS_WINDOWS=1 ;; *) IS_WINDOWS=0 ;; esac

if [ "$USE_ANDROID_CLI" = "1" ] && [ "$IS_WINDOWS" = "0" ]; then
  # List existing AVDs; reuse one if it already fits the task.
  android emulator list

  # Create a device from a profile. The CLI only accepts --profile and
  # --list-profiles — the profile name doubles as the device name.
  android emulator create --profile=medium_phone

  # Snapshot existing serials BEFORE start so we can pin every adb call
  # to the new emulator. The moment a second device is attached, plain
  # `adb shell ...` errors with "more than one device/emulator" and the
  # boot-completed loop spins forever.
  PRE_SERIALS=$(adb devices | awk 'NR>1 && $2=="device"{print $1}' | sort -u)

  # Start the device using that profile name. `android emulator start`
  # returns once the command is issued — use `adb wait-for-device` plus a
  # boot-completed check before step 1, or `mobile_list_available_devices`
  # will race the boot sequence.
  android emulator start medium_phone

  # Identify the new serial by diffing `adb devices` (give it up to 30s
  # to register).
  for _ in $(seq 1 30); do
    POST_SERIALS=$(adb devices | awk 'NR>1 && $2=="device"{print $1}' | sort -u)
    NEW_SERIAL=$(comm -13 <(echo "$PRE_SERIALS") <(echo "$POST_SERIALS") | head -n1)
    [ -n "$NEW_SERIAL" ] && break
    sleep 1
  done

  adb -s "$NEW_SERIAL" wait-for-device
  until [ "$(adb -s "$NEW_SERIAL" shell getprop sys.boot_completed | tr -d '\r')" = "1" ]; do sleep 2; done
fi

At the end of the task, if this session created the AVD, stop it using the device serial (adb devices or android emulator list will print it):

. /tmp/.verify_on_device.env  # restore USE_ANDROID_CLI from the probe step

if [ "$USE_ANDROID_CLI" = "1" ]; then
  android emulator stop <device-serial-number>
fi

Fallback (no android CLI): continue to step 1 and assume a running device, as before.

1. Discover Devices

Call mobile_list_available_devices. If multiple devices are returned, ask the user which to use. If none are found, instruct the user to boot an emulator or connect a device.

2. Prepare the Device

Run these ADB commands to configure the device for reliable agent interaction:

# Disable animations (prevents flaky element detection during transitions)
adb -s <device_id> shell settings put global animator_duration_scale 0
adb -s <device_id> shell settings put global transition_animation_scale 0
adb -s <device_id> shell settings put global window_animation_scale 0

3. Disable LeakCanary

LeakCanary shows leak detection notifications and dialogs that interfere with agent verification. Disable it before building by setting the flag in developer.properties (a git-ignored local config file):

# Ensure developer.properties exists and has LeakCanary disabled
touch developer.properties
grep -q "enable_leak_canary" developer.properties && sed -i '' 's/enable_leak_canary=.*/enable_leak_canary=false/' developer.properties || echo "enable_leak_canary=false" >> developer.properties

4. Build the Debug APK

./gradlew assembleWasabiDebug

If the build fails with "SDK location not found", check that local.properties exists and contains the sdk.dir path. See the Error Recovery section below.

5. Install the APK

Preferred path (USE_ANDROID_CLI=1): skip this step. The single android run call in step 7 installs and launches in one shot — APK resolution and the install itself happen there.

Both paths must install in place without clearing app data. Do not uninstall first.

Fallback (no android CLI): install via mobile-mcp; its install operation must replace the APK while preserving the existing app data.

Use mobile_install_app with:

• path: WooCommerce/build/outputs/apk/wasabi/debug/WooCommerce-wasabi-debug.apk

Optionally call mobile_list_apps first to check if the app is already installed.

6. Set Up API Mocks (Optional)

If the user requests verification of a specific scenario (error states, empty data, custom responses), set up ApiFaker mock endpoints before launching the app. See the "API Mocking with ApiFaker" section and docs/api-faker-adb.md for commands and workflow.

7. Restart and Launch the App

Always force-stop the app first, then launch fresh. This ensures a clean starting state regardless of what screen was previously active — the "Always Restart the App" rule above applies to both paths.

Preferred path (USE_ANDROID_CLI=1, full flow): locate the APK produced by step 4, then one android run call reinstalls and launches the exact Activity. android run has no "launch-only" mode — it always reinstalls. When the app is already installed and the build hasn't changed (shortcut flow from the top of "Steps"), use the launch-only form further below to skip the reinstall — the CLI does not offer a launch-only equivalent, so both no-CLI users and CLI shortcut users land on the same am start block.

# 1. Resolve the APK path. `android describe` was evaluated for this purpose but
#    its output is multi-line plain text (not JSON/paths-to-JSON) and the
#    underlying Gradle task requires ANDROID_HOME; a plain `find` is simpler and
#    works whether the CLI is installed or not.
APK=$(find WooCommerce/build -type f -name 'WooCommerce-wasabi-debug.apk' | head -n1)

# Persist for the POS variant below (each Bash tool call is a fresh shell, so
# a plain $APK does not survive between separate code blocks). %q shell-quotes
# the value so a path with spaces or other special chars survives sourcing.
printf 'APK=%q\n' "$APK" >> /tmp/.verify_on_device.env

# 2. Force-stop — android run does not guarantee a cold start.
adb -s <device_id> shell am force-stop com.woocommerce.android.dev

# 3. Combined install + launch.
android run --apks="$APK" \
  --activity=com.woocommerce.android.ui.main.MainActivity \
  --device=<device_id>

For POS tasks (only when explicitly requested) — sources $APK from the block above:

. /tmp/.verify_on_device.env  # restore $APK persisted by the main launch block

adb -s <device_id> shell am force-stop com.woocommerce.android.dev
android run --apks="$APK" \
  --activity=com.woocommerce.android.ui.woopos.root.WooPosActivity \
  --device=<device_id>

Launch-only form (no reinstall): force-stop + am start. Use this when (a) the agent CLI is not available, or (b) the agent CLI is available but the app is already installed and the build hasn't changed (the CLI shortcut path).

adb -s <device_id> shell am force-stop com.woocommerce.android.dev
adb -s <device_id> shell am start -n com.woocommerce.android.dev/com.woocommerce.android.ui.main.MainActivity

Do NOT use mobile_launch_app — it launches the default launcher intent which may not always resolve to MainActivity.

For POS (only when explicitly requested): Launch directly into POS with:

adb -s <device_id> shell am force-stop com.woocommerce.android.dev
adb -s <device_id> shell am start -n com.woocommerce.android.dev/com.woocommerce.android.ui.woopos.root.WooPosActivity

8. Handle Authentication and Post-Launch Dialogs

Call mobile_list_elements_on_screen to check what appeared. If login is shown, follow "Authentication and Session Preservation" and references/agent-auto-login.md.

If a dialog or overlay is blocking the main UI, dismiss it using the guidance in "Handling Unexpected Dialogs" above. Repeat until you reach the dashboard or the expected screen.

9. Start Screen Recording (Optional)

If the user requests a recording or demo video, start an ADB screen recording before navigating:

# Start recording in the background (max 180s, Android hard limit)
adb -s <device_id> shell "screenrecord --size 720x1280 /sdcard/_agent_rec.mp4" &

Use --size 720x1280 to keep the file small. The recording runs in the background while you perform navigation steps. See the Screen Recording section below for full details.

10. Navigate and Verify

Navigate as needed per the user's request. After each navigation action:

1. Wait for the screen to stabilize (see "Waiting for Screen Transitions").
2. Verify you arrived at the expected screen using the Key Screen Identifiers table.
3. Take a screenshot with mobile_save_screenshot as evidence.

If the expected screen identifier is NOT present after retries:

1. Take a screenshot with mobile_take_screenshot.
2. Call mobile_list_elements_on_screen and identify which screen you are actually on.
3. Report to the user: "Navigation to [target] failed. Currently on [detected screen]."

11. Stop Recording and Save Evidence

If recording: stop the recording, pull the file, and clean up:

adb -s <device_id> shell "pkill -l SIGINT screenrecord"
sleep 2
adb -s <device_id> pull /sdcard/_agent_rec.mp4 ./verification_recording.mp4
adb -s <device_id> shell rm /sdcard/_agent_rec.mp4

Always: use mobile_save_screenshot at each verification step to save screenshots to disk.

12. Report Results

Summarize what was verified, include saved screenshot and recording paths, and flag any issues found.

Available MCP Tools Reference

Device Management

App Lifecycle

Screen Interaction

Screenshots

Screen Recording via ADB

Use adb shell screenrecord to capture video of navigation flows. This is useful for demo recordings, PR evidence, or reproducing bugs.

Start Recording

Run in the background so the agent can continue navigating while recording:

adb -s <device_id> shell "screenrecord --size 720x1280 /sdcard/_agent_rec.mp4" &

Stop Recording

CRITICAL: Always stop with SIGINT. Using SIGKILL or just killing the process leaves the MP4 unfinalized and unplayable.

adb -s <device_id> shell "pkill -l SIGINT screenrecord"
sleep 2
adb -s <device_id> pull /sdcard/_agent_rec.mp4 ./recording.mp4
adb -s <device_id> shell rm /sdcard/_agent_rec.mp4

Flows Longer Than 3 Minutes

Android limits recordings to 180 seconds. For longer flows, chain recordings:

# Record in segments
adb -s <device_id> shell "screenrecord --time-limit 180 /sdcard/_agent_rec_1.mp4"
adb -s <device_id> pull /sdcard/_agent_rec_1.mp4 ./segment_1.mp4
adb -s <device_id> shell rm /sdcard/_agent_rec_1.mp4
# Start next segment...

Note: with --time-limit, the command blocks until done, so navigation must happen from a parallel process or between segments.

Recording Failure Modes

API Mocking with ApiFaker

ApiFaker intercepts API calls at the OkHttp layer and returns fake responses from a local database. Control it via ADB broadcast commands to test specific scenarios (error states, empty lists, custom data) during device verification. ApiFaker is available only in debug builds.

When the user requests verification of a specific scenario, follow this workflow:

1. Clear any existing endpoints
2. Add mock endpoint(s) for the scenario
3. Enable ApiFaker
4. Launch or navigate the app — mocked endpoints return fake responses
5. Verify the UI shows the expected behavior
6. Disable ApiFaker and clear endpoints when done

For all ADB commands, extras, API types, examples, and debugging tips, read docs/api-faker-adb.md.

Key tips:

• All am broadcast commands must include -p com.woocommerce.android.dev — without it, Android 8.0+ silently drops the broadcast.
• All actions log results to logcat under the WCApiFaker tag — use adb logcat -s WCApiFaker -d to check feedback.

WooCommerce Navigation Reference

All resource IDs below use the debug package prefix com.woocommerce.android.dev:id/. Compose test tags (applied via Modifier.testTag()) also appear as resource IDs in the accessibility tree because testTagsAsResourceId is enabled in the app's theme.

The app has two distinct navigation domains with different architectures. Only load the reference files you need for the task — each file adds significant context cost.

Always load first

• Overview & Feature Tree -- lightweight index of all screens, bottom tabs, global elements. Read this first to orient yourself, then load only the detailed references you need.

Load on demand — match task keywords to the right reference

Key distinction: "Adding products to an order" is an Orders workflow (order creation screen), NOT a Products workflow. Only load the Products reference when the task is about the standalone product catalog (Products tab).

Common Navigation Patterns

• Go back: Call mobile_press_button with button BACK. This is the most reliable way to navigate back.
• Dismiss the soft keyboard: Call mobile_press_button with BACK. This only dismisses the keyboard; it does NOT navigate back. If you need to navigate back AND the keyboard is visible, press BACK twice: once to dismiss keyboard, once to navigate.
• Pull to refresh: Use mobile_swipe_on_screen with direction down from the middle of the screen.
• Scroll down a list: Use mobile_swipe_on_screen with direction up (swipe up to scroll down).
• Open a list item: Find the item in mobile_list_elements_on_screen by its text or identifier, compute center coordinates, and tap.
• Toolbar back arrow: Look for elements in the toolbar area (com.woocommerce.android.dev:id/toolbar). If the back arrow is not exposed as a separate element, use mobile_press_button with BACK instead.

Error Recovery

Diagnostic ADB Commands (via Bash)

When mobile-mcp tools are not giving enough information:

Android Knowledge Base (USE_ANDROID_CLI=1)

When a platform-behavior question comes up mid-task (intent flags, am start semantics, Activity launch modes, permissions, animation scales, settings put global keys), prefer the Android Knowledge Base over a web search — the answers are authoritative, local, and don't cost browsing tokens.

# Search by free-form query, then fetch one of the kb:// URLs it returns.
android docs search "am start intent flags"
android docs fetch <kb-url-from-the-search-result>

If the CLI is not installed, fall back to the Android developer website as before.