In Appium, which capabilities choose the driver and which choose the device under test?

A new Appium session begins with one HTTP request carrying a flat map of capabilities. The map is flat, but Appium reads it along two independent axes: one answers *which driver runs this session*, the other answers *which machine that driver attaches to*. Keeping the axes apart is the whole skill here, and confusing them is why a dental-recall booking app suite can start a session cleanly and still never touch the handset the engineer meant. ## The driver axis Two capabilities decide which code will run the session. - `platformName` — the only W3C standard name in this group, so it is written bare, with no vendor prefix. It carries `Android` or `iOS`. - `appium:automationName` — a vendor capability, so it carries the `appium:` prefix. It names an installed driver: `UiAutomator2` or `Espresso` on Android, `XCUITest` on Apple platforms, or one of the Flutter drivers. Since Appium 2 turned drivers into separately installed extensions, `platformName` on its own cannot identify a driver. `Android` is served by UiAutomator2, by Espresso and by a Flutter driver, and those three declare different locator strategies, different `mobile:` execute methods and different on-device agents. `appium:automationName` is the key that says which of them you asked for. Installing that driver in the first place is a separate subject. ## The machine axis, and it does not look the same on both platforms The driver axis is symmetrical: the same two keys, different values. The machine axis is not. Each platform has its own way of naming a target, and this is where a capability map stops being portable. | what you want to reach | Android | Apple platforms | | --- | --- | --- | | a real attached device | `appium:udid` — the serial adb reports | `appium:udid` — the device UDID | | a virtual device | `appium:avd` — the AVD name | `appium:deviceName` with `appium:platformVersion` | | `appium:deviceName` itself | accepted, but not what selects | genuinely selects a simulator | `appium:udid` is the one selection key spelled the same on both platforms — it is a core capability rather than a driver's own — but even it carries a different kind of identifier on each side: an adb serial on Android, an Apple UDID on the other. ## What a dental-recall capability map actually looks like For the dental-recall booking app the lanes come out like this. 1. Android, real handset in the lab: `platformName` set to Android, `appium:automationName` set to UiAutomator2, and `appium:udid` holding that handset's serial. 2. Android, emulator on a build machine: the same first two keys, and `appium:avd` naming the AVD instead of a serial. 3. Apple, simulator on a Mac: `platformName` set to iOS, `appium:automationName` set to XCUITest, `appium:deviceName` naming the model and `appium:platformVersion` naming the runtime. 4. Apple, real device: the same first two keys, and `appium:udid` naming the device. Note what does **not** appear in lanes 1 and 2. `appium:deviceName` is declared by the Android drivers, so the server accepts it and it shows up in logs and in whatever a report copies out of the capability map, but it takes no part in choosing which attached device or emulator the session drives. An Android request whose only device-ish key is `appium:deviceName` has named nothing the driver acts on. ## Why the split is worth holding in your head - A driver-axis mistake fails loudly. Ask for a driver that is not installed and the session does not start. - A machine-axis mistake fails quietly. The session starts, the app installs, the test runs, and the result belongs to a device nobody chose. - The keys that fail quietly are exactly the ones that read most like plain English, which is why `appium:deviceName` is the one people reach for first. - Reports inherit the confusion. A report that prints `appium:deviceName` as the device is quoting the request, not the machine, unless the platform was one where that key selects. ## Reading the axes off a session that went wrong When a session lands somewhere unexpected, ask the two questions in order. First: did I name a driver, and is it the driver whose behaviour I am seeing? A `mobile:` method that is not recognised, or a locator strategy that is refused, usually means the answer is no. Second: did I name a machine, with a key that platform actually selects on? On Android that means `appium:udid` or `appium:avd` were present and correct; on an Apple simulator it means `appium:deviceName` and `appium:platformVersion` were both present, since a model name alone can match more than one installed runtime. Answer both and the session is pinned. Leave either to inference and you have a suite whose results are about a machine you cannot name afterwards.