Permissions
Configure app permissions on launch or mid-flow for iOS and Android testing.
Managing system permissions is a common challenge in mobile test automation. Since OS prompts (like "Allow Camera Access") typically only appear once, your test journey can become inconsistent if the app state isn't reset.
Maestro solves this by allowing you to explicitly configure permissions either at launch or during the Flow, ensuring a predictable environment every time.
Configure permissions on launch
The easiest way to manage permissions is during the launchApp command. By default, Maestro grants all permissions, but you can override this behavior to test specific scenarios.
To customize launch permissions, you need to specify them when calling launchApp. The following example denies all permissions but explicitly allows the camera and location:
- launchApp:
permissions:
all: deny
camera: allow
location: allowChanging permissions mid-flow
Sometimes you need to change permissions while the app is running, for example, to test how your app handles a permission denial or to prepare for a specific feature flow like scanning a QR code. Use the setPermissions command for this purpose.
- setPermissions:
permissions:
notifications: allowBrowser limitation
Maestro can manage permissions for iOS and Android applications, but it has no control over Chrome’s system permissions.
Available permissions
Maestro uses standardized names to make your Flows cross-platform. For example, using bluetooth on Android targets both BLUETOOTH_CONNECT and BLUETOOTH_SCAN automatically.
The following table list all permissions available in iOS and Android.
bluetooth
❌
✅
calendar
✅
✅
camera
✅
✅
contacts
✅
✅
health
❌
❌
homekit
✅
❌
location
✅
✅
medialibrary
✅
✅
microphone
✅
✅
motion
✅
❌
notifications
✅
✅
phone
❌
✅
photos
✅
❌
reminders
✅
❌
siri
✅
❌
sms
❌
✅
speech
✅
❌
storage
❌
✅
usertracking
✅
❌
Android custom permissions
If a specific Android permission isn't listed above, you can use the full Android Permission ID. The following example adds the ADD_VOICEMAIL permission:
Android special permissions
Not all permissions are prompted for in the app, like location is. Some require the user to leave the app and grant the permission within the Settings app.
android.permission.MANAGE_EXTERNAL_STORAGE permission has been required since Android 12 if an app wished to access files that weren't its own (e.g. file browsers, virus scanners).
Maestro can manage this like other permissions without additional user interaction, acting like an app's "second use" rather than first use. If it's declared in the app's AndroidManifest.xml then it'll be set automatically. If you want fine grained control, do as with custom permissions:
Permission values
You can set permissions to one of the following states:
allow
Grants the permission. On iOS, this also automatically dismisses the system prompt.
deny
Denies the permission. Android will request permission during the Flow execution if the app requires access to a specific feature.
unset
Resets the permission state, causing the system to prompt permission requests when running the Flow.
Permission values can come from a variable or a JavaScript expression instead of being hard-coded:
This lets one Flow cover both the granted and the denied journey, driven by --env or by the env block of the calling Flow.
Push notifications on iOS
Unlike other permissions, iOS does not grant notification permissions silently. When the app requests permissions, the system prompt appears, and Maestro automatically taps Allow.
On Android, the permission is granted silently without a prompt.
iOS-specific values
iOS supports additional granular values for certain permissions.
location
always
Grants Always Allow location access.
inuse
Grants While Using the App location access.
never
Same as deny.
photos
limited
Grants Limited Access to the photo library.
Usage examples
Deny all permissions
To ensure your app handles permission denied states, start your Flow by denying everything. This forces you to handle the edge cases where a user declines a system permission prompt.
Deny all but allow specific ones
This is a common pattern for testing specific features in isolation.
Related resources
launchApp: See the full reference for launching apps.setPermissions: Command for altering permissions configuration mid-flow.
Last updated