Skip to main content

Recipes

Disable Sentry source-map upload during builds​

Sentry's "Upload Debug Symbols" Xcode build phase + the Android gradle equivalent both fail when SENTRY_AUTH_TOKEN is missing or lacks scope. For local CI / dev runs, skip the upload.

maestroparallel.config.ts
export default {
  buildEnv: { SENTRY_DISABLE_AUTO_UPLOAD: 'true' },
};

The var is merged into the build child process automatically.

Sign physical iOS​

mp builds the app via the auto-detected strategy; iOS code signing is handled by Xcode automatic signing or by your custom hook. mp itself only needs the Team ID for Maestro's WebDriver build:

maestroparallel.config.ts
export default {
  appleTeamId: 'YOUR10CHARS',
};

One-time setup on the Mac:

  1. Xcode → Settings → Accounts → + — sign in with an Apple ID that's a member of the target Developer team.

  2. Open ios/<App>.xcworkspace → target settings → Signing & Capabilities → ✓ Automatically manage signing → pick team.

  3. Xcode downloads cert into login Keychain and generates the provisioning profile. Verify:

    security find-identity -v -p codesigning

For CI, use App Store Connect API key (-allowProvisioningUpdates -authenticationKey*) — no interactive 2FA.

Pin build strategy​

Project has both rock.config.mjs AND eas.json? mp picks Rock by default. Override:

maestroparallel.config.ts
export default {
  buildStrategy: 'expo',  // or 'rock' / 'eas' / 'auto'
};

Inject Maestro env​

export default {
  maestroEnv: {
    APP_BASE_URL: 'https://staging.example.com',
    TEST_USER: 'qa+ci@example.com',
  },
};

In your flow YAML:

- runScript: |
    output.url = `${APP_BASE_URL}/healthcheck`;

Split flows across devices for speed​

Have 4 connected Androids and a flow suite that takes 10 min? shardMode: 'split' distributes flows across them, cutting wall time to ~2.5 min.

maestroparallel.config.ts
export default {
  shardMode: 'split',
};

Or one-off via CLI:

maestro-parallel --shard-split --all

Trade-off to remember:

  • ✅ Wall time drops ~linearly with device count.
  • ❌ Each flow runs on only one device — you lose multi-device validation (e.g. catching a bug that only reproduces on a Pixel 7a). Use shardMode: 'full' (the default) when coverage matters more than speed.
  • ⚠️ Don't mix with iosShardAll (mutually exclusive).
  • ⚠️ With split mode, iosSequential is forced off (sequential + split is degenerate).

Use shardMode: 'split' for fast feedback on PR / CI runs, and stick with 'full' for nightly regression suites where coverage matters most.

Run on every connected device in CI​

maestro-parallel --all --apple-team-id $MAESTRO_APPLE_TEAM_ID

--all skips the interactive picker (CI has no TTY). Use --apple-team-id or set MAESTRO_APPLE_TEAM_ID if physical iOS is in scope.