Exit course
Chapter 5 of 10 Beginner 7 min read 3 quick checks Updated

iOS vs Android: Permissions, State, Links

On this page
  1. One flow, two app ids
  2. What you install on each platform
  3. Resetting state: clearState and clearKeychain
  4. Permissions
  5. Launch arguments and resuming
  6. Deep links
  7. Smaller differences that bite

One of Maestro's selling points is that a single flow can drive both the Android and the iOS build of an app. In practice that works when the two builds expose the same ids and texts, and when you handle the handful of places where the platforms genuinely behave differently. This chapter covers those places.

One flow, two app ids#

The sample app is com.sampleapp on Android and org.reactjs.native.example.SampleApp on iOS. Rather than keeping two copies of every flow, make the app id a variable:

appId: ${APP_ID}
---
- launchApp
- assertVisible:
    id: inputA

and pass it per platform:

maestro test -e APP_ID=com.sampleapp flows/
maestro test -e APP_ID=org.reactjs.native.example.SampleApp flows/

If you run on both platforms from the same machine, remember the global --device option so each command goes to the right emulator or simulator.

What you install on each platform#

Target Build to use
Android emulator or device .apk
iOS Simulator .app bundle built for the simulator (xcodebuild -sdk iphonesimulator), often zipped
Physical iPhone signed .ipa

Locally, Maestro's documentation describes iOS testing on Xcode Simulators, which means a Mac. Android works with both emulators and physical devices connected over ADB. Physical iPhones are where a device cloud helps; chapter 7 covers running the same flows on real iOS hardware.

Resetting state: clearState and clearKeychain#

launchApp with clearState: true, or the standalone clearState command, gives you a fresh app. How it does that differs:

  • Android: equivalent to adb shell pm clear <package>. Shared preferences, databases and accounts are wiped; the app stays installed.
  • iOS: Maestro reinstalls the app, which removes its data folders.

The iOS Keychain is cleared by its own option, clearKeychain, which wipes the entire Keychain. Add it when your app keeps credentials or tokens there and the test must start logged out:

- launchApp:
    clearState: true
    clearKeychain: true

Because a reinstall is slower than a data wipe, clearState costs more time on iOS. Use it where the test needs a fresh start (onboarding, first-run permission prompts) rather than in every flow by reflex.

After adding clearState: true to every flow, your iOS suite got much slower while Android barely changed. Why?

Android uses the equivalent of pm clear; iOS reinstalls. Use clearState where a fresh start is needed, not by reflex. The Keychain is only wiped with clearKeychain.

Permissions#

By default launchApp grants all permissions, so most flows never see a system prompt. To test the other paths, set them explicitly:

- launchApp:
    permissions:
      all: deny
      camera: allow
      location: allow

Each permission can be allow, deny or unset (reset, so the system prompts again). Names are cross-platform where possible: camera, location, microphone, contacts, calendar, notifications and medialibrary work on both, while some exist only on one side, such as photos and usertracking on iOS or sms, phone and storage on Android. On Android you can also use a full permission id like android.permission.ACCESS_FINE_LOCATION. iOS adds finer values: location: always, location: inuse and photos: limited.

Two platform behaviours to know:

  • iOS notifications cannot be granted silently. When the app asks, the system prompt appears and Maestro taps Allow for you. On Android the permission is granted without a prompt.
  • Changing a permission mid-flow uses setPermissions, for example to revoke location just before opening a map screen:
- setPermissions:
    permissions:
      location: deny
- tapOn: "Show nearby stores"
- assertVisible: "Location access is off"

Permission values can come from variables (camera: ${CAMERA_STATE}), so one flow can cover the granted and the denied journey.

You want to test the screen that appears when location access is denied, but the flow never reaches it. Why, and what do you change?

By default every permission is granted, so the denied path never happens. Setting it explicitly (or with setPermissions mid-flow) makes it deterministic.

Launch arguments and resuming#

launchApp can pass key-value arguments that your app reads at start-up, which is a clean way to switch on a test backend or skip an onboarding carousel:

- launchApp:
    arguments:
      useMockBackend: true
      onboardingSeen: true

On Android they arrive as intent extras; on iOS through the process arguments and UserDefaults. Your app has to read them; Maestro only delivers them.

launchApp stops a running app before launching it. To bring a backgrounded app to the front instead (for example after visiting Settings), use stopApp: false.

openLink opens a URL or a custom scheme, which lets a flow jump straight to the screen under test:

- openLink: myapp://settings/notifications

The platforms add their own friction:

  • Android may show a dialog asking which app should handle an https link, and from Android 12 web links open in a browser unless the app is verified. autoVerify: true attempts to verify your app for the link and also accepts Chrome's first-run screens; browser: true forces Chrome.
  • iOS may ask the user to confirm opening the app the first time. That choice is remembered by the simulator and is not reset by clearState, so handle it conditionally:
- openLink:
    link: myapp://settings
- runFlow:
    when:
      visible: 'Open in "MyApp"'
    commands:
      - tapOn: "Open"

On iOS, openLink sometimes shows an Open in MyApp confirmation and sometimes does not, even with clearState: true. How should the flow handle it?

The simulator remembers the choice and clearState does not reset it, so the dialog is genuinely optional. An unconditional tap fails whenever it is absent.

Smaller differences that bite#

  • back exists on Android (and web) only. On iOS, tap the app's own back button, typically by its id.
  • hideKeyboard sends a back event on Android but performs small swipes on iOS, which do not always work. With the sample app's iOS number pad it failed outright. The workaround from the Maestro docs is to tap a neutral, non-interactive element such as a title. Chapter 5 covers this failure.
  • Platform branches. When a step really differs, wrap it in runFlow with when: { platform: iOS } or put each variant in its own subflow, as shown in chapter 3.
  • Animations. System animations are a common source of timing noise. Some config keys for disabling them, such as disableAnimations, only take effect on cloud devices and are ignored on a local emulator or simulator; check what your runner supports before relying on them.

On TestingBot, platform.ios.disableAnimations and platform.android.disableAnimations in config.yaml (or the --disable-animations CLI flag) turn on Reduce Motion on iOS and switch off animation scales on Android; the platform configuration section of the Maestro options has the details. The device locale, timezone and orientation, which you would otherwise script per platform, are run options there too. A summary of what the cloud adds is on the Maestro feature page.

Next, debugging: what to do when a flow fails and you do not immediately know why.