Protocol Lineage

## The one request the whole run hangs on Every Appium run opens with a single HTTP request: `POST /session`, sent to the server's base path — for a server running locally that is `http://127.0.0.1:4723/session`. Nothing else can happen until it succeeds, because the response is what hands back the **session id** that every later command is addressed under. Getting the body's shape wrong is not a subtle bug: there is no session at all, and a birdwatching sightings suite dies before it has seen one screen of the app. ## The envelope Appium 3 accepts The body has exactly one top-level member, `capabilities`. Inside it sit two optional members: - **`alwaysMatch`** — one object of requirements the created session must satisfy. - **`firstMatch`** — an array of alternative objects, any one of which may satisfy the remainder. Both are W3C WebDriver negotiation inputs, and the rules for combining them belong to the protocol rather than to Appium. What belongs to Appium is what it no longer takes: **`desiredCapabilities` and `requiredCapabilities` are gone.** Appium 3 accepts `capabilities` and nothing else. A client binding old enough to post a flat `desiredCapabilities` map is not negotiating badly — it is sending a body with no member the server recognises as the request, and the repair belongs in the client library, not in a server flag that restores the old shape. ## Two vocabularies inside one object | Kind of key | How it is written | Birdwatching example | |---|---|---| | W3C standard names | bare | `platformName: "Android"` | | Everything Appium-specific | `appium:` prefixed | `appium:automationName: "UiAutomator2"` | Only the W3C standard names — `platformName`, `browserName`, `timeouts`, `webSocketUrl` and the rest of that short set — may travel unprefixed. Every vendor key carries `appium:` or is nested under `appium:options`, and that includes keys that feel like core Appium concepts rather than extensions: `appium:app`, `appium:udid`, `appium:newCommandTimeout`. ## The same envelope, two platform families The shape of the request does not change between platforms; only the values do. - **Android**: `platformName` is `Android`, and `appium:automationName` names an Android driver such as `UiAutomator2` or `Espresso`. - **Apple platforms**: `platformName` names the Apple target you mean, and `appium:automationName` is `XCUITest`. That symmetry is worth saying out loud, because it is close to the last thing about a session that is symmetric. Once the request lands, what the driver has to do on the device diverges sharply: the Android drivers push a helper server onto the device, while the XCUITest driver has to have WebDriverAgent built, installed and running before it will answer a command. The request looks the same on both; the seconds it takes do not. ## What comes back A successful `POST /session` answers with the session id and the set of capabilities the server actually matched. Log the matched set. It is what the driver ran with, and it is not guaranteed to be key-for-key what you sent, because which keys mean anything depends on which driver answered — `appium:deviceName`, for instance, is declared by the Android drivers and by the XCUITest driver rather than by Appium's core. The session id itself is minted for this session and is meaningless afterwards: it is not a device identifier, not a run identifier, and not stable between runs. ## Where a birdwatching suite gets this wrong 1. **Sending `desiredCapabilities`.** Almost always an unupgraded client binding rather than hand-written JSON, and the symptom is total: no session is created, on any device. 2. **Hoisting `alwaysMatch` or `firstMatch` to the top level.** They live inside `capabilities`, not beside it. 3. **Dropping the `appium:` prefix on a vendor key.** The server does not quietly accept an unprefixed vendor name and carry on regardless. 4. **Assuming the response echoes the request.** It reports what was matched, which is the more useful of the two things to read. 5. **Hand-rolling the request when a client binding exists.** The bindings build this envelope for you; the value in knowing its shape is that you can read a rejected new-session request in a server log and see immediately which half is wrong. ## Why the shape matters beyond the first request The new-session body is the only place a run gets to say what it wants. There is no later negotiation and no second chance to add a key: everything the session does afterwards — which driver answers, which device it drives, how long it may sit idle before the server ends it — was fixed by this one object. So triage of a strange run starts here rather than at the failing command. If the capabilities the server logged are not the capabilities you believed the suite sent, nothing downstream will make sense, and the fastest way to find that out is to compare the two before reading another line of the log.