Skip to main content

Getting started

Requirements​

  • macOS (for iOS testing) / Linux / Windows (Android only)
  • Deno ≥ 2.0 — brew install deno (for the JSR distribution)
  • Maestro CLI — curl -fsSL https://get.maestro.mobile.dev | bash
  • For iOS: Xcode + at least one iOS simulator runtime installed
  • For Android: adb (Android SDK platform-tools)

Install​

JSR (Deno):

deno install --global --reload --allow-all -n maestro-parallel \
  jsr:@kaln/maestro-parallel/cli

Or run without installing:

deno run -A jsr:@kaln/maestro-parallel/cli

npm (Node ≥ 18.17):

npm i -g maestro-parallel
# or one-shot
npx maestro-parallel

First run​

In your Expo / React Native project root:

# Boot one iOS sim and/or plug an Android device, then:
maestro-parallel

maestro-parallel will:

  1. Detect the build strategy (Rock / EAS / expo run:*).
  2. Show an interactive picker if you have more than one device.
  3. Build a release artifact, install on every selected device.
  4. Run flows from .maestro/ (or wherever your config points).
  5. Print a per-device summary + JUnit at .maestro/output/parallel-<timestamp>/report.xml.

Common flags​

maestro-parallel --all              # skip the picker, run on every device
maestro-parallel --skip-build       # reuse the already-installed app
maestro-parallel --cwd ../other-app # run against a different project

See CLI reference for the full list.

Project config​

Optional: drop a maestroparallel.config.ts at the repo root to pin build strategy, env vars, Maestro env, Apple Team ID, and more. See Configuration.

iOS simulator auto-preflight​

Every selected sim is configured before flows run — no opt-in needed:

  • AutoFillPasswords = false in both relevant defaults domains. Kills the "Save Password?" / "AutoFill Passwords" overlay that otherwise blocks Maestro after a credentials submit.
  • Keychain reset via xcrun simctl keychain <udid> reset.
  • SBIdleTimerDisabled = true so the sim doesn't auto-lock mid-test.

You can also run it on its own:

maestro-parallel setup-ios-sim

Physical iOS can't be configured programmatically — disable AutoFill manually under Settings → Passwords → Password Options → AutoFill Passwords.