Debugging, Inspector & CI

Pick reliable locators with the Inspector, diagnose issues with doctor and debug logs, and run tests in GitHub Actions.

The Inspector: Stop Guessing Locators

The Mobilewright Inspector is a browser-based UI that shows a live screenshot of your device next to a list of every element — each annotated with the best locator Mobilewright would use to target it. Click a row to highlight the element on the screenshot, or click the screenshot to find the row:

# Open the Inspector in your browser (default port 4621)
npx mobilewright inspect

# Or pick a port
npx mobilewright inspect --port 8080

The Inspector recommends locators in the same priority order the query engine uses: getByTestId > getByRole > getByLabel > getByText. If two elements resolve to the same locator, both get a dup badge — your signal to add a unique testID before relying on it.

doctor: Check Your Environment

When something is not working, run doctor first. It verifies Node.js, Xcode, the Android SDK, ADB, connected devices, and more — and prints exactly what is wrong:

npx mobilewright doctor

# Check only one platform
npx mobilewright doctor --category ios

# JSON output for CI
npx mobilewright doctor --json

Debug Logging

Mobilewright uses the DEBUG environment variable for diagnostic logs. They are silent by default:

# All mobilewright logs
DEBUG=mw:* npx mobilewright test

# Only the device driver logs
DEBUG=mw:driver-mobilecli npx mobilewright test

Running in GitHub Actions

Mobilewright runs in CI like any Node.js tool. Use macos-latest when you need iOS simulators (ubuntu-latest is enough for Android emulators), and upload the HTML report as an artifact so you can inspect failures — the !cancelled() condition makes sure the report uploads even when tests fail:

name: Mobilewright Tests
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24

      - run: npm ci
      - run: npx mobilewright test --reporter html

      - uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: mobilewright-report
          path: mobilewright-report/
          retention-days: 30

After a run, download the report artifact from the Actions summary page and open it locally with npx mobilewright show-report ./mobilewright-report. Congratulations — you have completed the Mobilewright course! You now know enough to build a full mobile test suite, from first tap to green pipeline.