Granting Permissions

## What the capability actually switches on `appium:autoGrantPermissions` is a **capability**, not an execute method, and that single fact explains most of its behaviour. Capabilities are supplied in the `POST /session` request and fixed for the lifetime of the session; they configure the driver before any test code runs. So this one cannot express a per-case intent, cannot be toggled mid-run, and cannot be aimed at a single permission. It is a session-wide switch. What it switches on is a step the Android drivers perform **as part of installing the application**: once the package is on the device, the driver grants every permission that package declares. The practical effect a learner sees is that the system never draws a runtime prompt, because there is nothing left to ask about. The capability belongs to the Android side — `appium-android-driver` declares it, so a UiAutomator2 session and an Espresso session both honour it. The XCUITest driver has **no install-time permission-grant capability** at all; the Apple way to start a Simulator session with a permission already decided is the execute method `mobile: setPermission`. ## The install-time trap The most common surprise is that the capability appears to do nothing. Almost always the reason is that **no install happened**. The grant is bolted onto the install step, so if the session skips the install the grant goes with it. Situations where that occurs: - `appium:noReset` is true and the build is already on the device, so the driver leaves it in place. - The driver decides the installed build already matches the artifact named by `app` and does not replace it. - The session attaches to an app that something other than this session installed. - A permission was explicitly revoked on the device by an earlier run and the app was never reinstalled between them. The diagnostic is straightforward: read the state back with `mobile: getPermissions` at the start of the case rather than assuming the capability took. A setup step that verifies its own work turns a mysterious mid-run modal into a clear failure in setup. ## Blanket versus surgical The capability and the execute method solve different problems, and a healthy suite usually uses both: | Concern | `appium:autoGrantPermissions` | `mobile: changePermissions` | |---|---|---| | Kind | session capability | execute method | | Timing | at install, before any test code | any time during the session | | Reach | every permission the app declares | one or more named permissions | | Direction | grant only | grant or revoke | | Target | the app the session installs | any installed package | | Per-case control | none | full | So the honest framing is that the capability clears the prompts out of the way for the **happy-path majority** of a suite, and the execute method is how one specific case dissents from that default. ## The vineyard harvest-log app in practice A **vineyard harvest-log app** photographs each bin at the press house and records the block it came from, so it declares camera and location access. Nearly every case in its suite wants both already granted — nobody wants forty cases each fighting a modal — so the session profile sets `appium:autoGrantPermissions` and the flows run clean. Then a handful of cases need the camera missing so the app falls back to a typed bin note. Those cases do not get their own session profile; they run in the same session and call `mobile: changePermissions` with the revoke action on the harvest-log package before the photo screen opens. What those cases then assert about the degraded experience is test-design work and lives elsewhere; the driver's part ends once the state is seeded. ## Ordering and hygiene 1. Set the capability in the session profile, not per case, because that is the only place a capability can live. 2. Let the session install the app when you rely on the grant — a reset policy that skips the install skips the grant. 3. Revoke, rather than un-grant, when a single case wants a permission absent; the capability has no exclusion list. 4. Do the revoke while the app is backgrounded or before it is activated, since changing a permission a running app already holds can restart its process. 5. Verify with `mobile: getPermissions` if a run has ever surprised you; it is cheap and it makes setup failures loud. ## What it is not It is not a modal handler. It removes the reason a permission prompt would appear on Android; it does nothing about any other system dialog, and it has no Apple counterpart that behaves the same way. It is also not a substitute for `mobile: changePermissions`: it can only add permissions, never take one away, and it acts once, at install, for the whole application.