[BUG] Appium driver rejects parsed setPermissions step on Android

[yesiamdaniel]

Description

The Appium driver does not implement the parsed SetPermissionsStep on Android. Execution aborts before any permission request reaches Appium or the application.

Steps to Reproduce

1. Start an Android Appium session using UiAutomator2.
2. Run the flow below using maestro-runner with --driver appium.
3. Observe that execution stops at setPermissions.

Expected Behavior

maestro-runner applies the requested Android runtime permissions and continues the flow.

Actual Behavior

The Appium driver reports SetPermissionsStep as unsupported and aborts the flow.

Environment

• OS: AWS Device Farm Amazon Linux 2 host / Android 15
• Go version: N/A (prebuilt release binary)
• maestro-runner version: v1.1.19; source inspection confirms the handler is also absent from v1.1.25
• Executor: Appium 2.11.5 with UiAutomator2
• Device/Simulator: Physical Samsung Galaxy S25

Flow File

appId: com.example.app
---
- setPermissions:
    permissions:
      notifications: allow
      microphone: allow

Error Output

onFlowStart failed: unsupported step type: *flow.SetPermissionsStep

Additional Context

The Appium dispatcher has no SetPermissionsStep case and falls through to its generic unsupported-step result:

https://github.com/devicelab-dev/maestro-runner/blob/v1.1.25/pkg/driver/appium/driver.go#L145-L209

The Appium client already exposes mobile: changePermissions, which could support Android grant/revoke handling:

https://github.com/devicelab-dev/maestro-runner/blob/v1.1.25/pkg/driver/appium/client.go#L758-L799

This is separate from #147, which covers iOS Native/WDA location permission values.

This report covers standard Android runtime permissions. Special app-op permissions such as SCHEDULE_EXACT_ALARM are outside its scope.

[omnarayan]

@yesiamdaniel Thanks — this is an unusually good report, and you were right on both counts: the dispatcher case was missing, and mobile: changePermissions was the route to take.

Fixed

The gap turned out to be wider than the Appium driver. setPermissions was dispatched by two drivers out of six — Appium, UIAutomator2, DeviceLab Android and DeviceLab iOS all parsed the step and then rejected it, so this hit the default Android driver too. Every one of them already had the capability; UIAutomator2 and DeviceLab have carried grant/revoke since launchApp's permissions: block. What was missing in each case was the case in the switch.

There was a second bug behind yours. setPermissions never inherited the flow's appId, unlike every other app-lifecycle step, so the form in your report — which omits it, because the flow already declares one — would have failed even on the drivers that did implement the step. Fixed on both the top-level and nested paths; the nested one is where onFlowStart runs, which is where you hit it.

Permission tables

Three permission tables had been copied per driver and had drifted, which is precisely how Appium ended up with the permission values but no mapping for shortcut names like notifications. They're now one table each for Android and iOS.

Consolidating them turned up three errors in the iOS map that have been wrong for a while:

• medialibrary is rejected by simctl outright — the service is media-library
• notifications and faceid aren't privacy services at all; iOS exposes no host-side control over either

All three were being sent to simctl and failing silently on every permission reset. They now report that iOS can't set them, rather than failing a step over something no driver can deliver.

Undeclared permissions

Testing your flow on a real device turned up one more thing worth mentioning, since it will affect you directly. Our test app doesn't declare RECORD_AUDIO, so pm grant answered with a SecurityException — and UIAutomator2 failed the step while DeviceLab passed, because it was batching grants with 2>/dev/null and discarding the result. Same request, opposite verdicts.

A permission the app never declared is now a warning on both, not a failure: Maestro ignores these, and it has to, since all: allow will always name permissions a given app never wanted. It's reported rather than swallowed, though — quietly dropping things is what let this ship broken in the first place. So if microphone: allow appears to do nothing, check the manifest declares it; you'll see a line in the log saying so.

On Android, unset revokes and says so, because pm reset-permissions resets the whole app rather than one permission — pretending otherwise seemed worse than naming it.

Verified with your flow on a Pixel 4a and an iOS simulator — it aborted before on all four drivers, and passes now. This will be in 1.1.26.

[yesiamdaniel]

Thanks so much for the quick response and fix!