In Appium, what happens on the device between POST /session and the first command?

## The handshake is not one round trip From the client's side, creating a session is a single HTTP call: one request out, one response back carrying a session id. Between those two moments the driver does real work on a real device, and on a cold machine that work can dominate a birdwatching sightings suite's wall clock. Knowing what it is explains two things at once — why session creation is slow, and why a session can fail before your test has issued a single command. ## What the Android drivers do The UiAutomator2 driver does not reach into an Android device directly. It puts its own helper server there: `io.appium.uiautomator2.server`, installed and started on the device alongside the `io.appium.settings` helper application, with the driver then making requests to that on-device server over host-side forwarding. Before your first find, the driver has: - confirmed the device is reachable and identified it, - put its helper packages on the device and started them, - opened the host-side plumbing that lets it reach the on-device server, - dealt with the app under test, if the session named one. The Espresso driver sits in the same slot on Android and fills it differently: it builds and installs its own instrumentation server, which is why an Espresso session can spend a build inside `POST /session` the first time round. ## What the XCUITest driver does on Apple platforms On Apple platforms the equivalent agent is **WebDriverAgent**, and it is not pushed — it is built. The XCUITest driver drives `xcodebuild` to build WebDriverAgent, install it on the target and launch it, and only then can the session answer a command. That has consequences the Android side does not have: - building WebDriverAgent needs macOS with Xcode, and running simulators needs macOS at all; - a non-macOS host can drive a recent real Apple device, but only with an agent that was built elsewhere and is already installed, and not through the default `xcodebuild` startup path; - the first session after a clean checkout pays for a build that later sessions inherit rather than repeat. ## Not every driver installs something "The driver installs an agent" is true of the two native drivers and is not a universal law. The official Flutter driver attaches to the app's already-running Dart VM Service over a WebSocket and puts nothing on the device. When you reason about handshake cost, reason about the driver you named in `appium:automationName` rather than about Appium in general. ## Why one request costs different amounts of time | | Android drivers | XCUITest on Apple platforms | |---|---|---| | The agent | a helper server pushed and started | WebDriverAgent built, installed, launched | | Host toolchain | the Android tooling, including `adb` | macOS with Xcode to build the agent | | First-run cost | putting packages on the device | a full build of the agent | | Later-run cost | starting an installed helper | launching an installed agent | Both columns end in the same place: an agent running on the device, reachable from the driver, ready to answer. Neither column is the other's story, and a sentence that describes one of them without naming its platform is wrong by omission the moment a suite runs on both. ## What the birdwatching suite should conclude 1. **Session creation is a device operation, not a network operation.** Budget it as such when you estimate how long a run takes to start producing results. 2. **A handshake failure surfaces as a failed `POST /session`.** The session id comes back only once the device-side work succeeded, so a broken agent is visible before any command is sent, rather than as a mysterious failure in the first step. 3. **The cost is per session.** How often you pay it is a function of how often the suite opens one — a separate decision from what the handshake itself does. 4. **Measure rather than guess.** The core `appium:eventTimings` capability asks the driver to record timings for session events, which is how you find out where the seconds actually went. 5. **Separate one-off costs from recurring ones.** On Apple platforms, a WebDriverAgent build is a different line item from an agent launch, and confusing the two makes hosts look slower than they are. ## Where the handshake's boundary sits The handshake ends when the session id is returned and your first command can be sent. The app under test is the one part of it that is not purely the driver's own business: the session may name an artifact, and what happens to an already-installed build — replaced, cleared, or left exactly as it was — is decided by the session's reset capabilities rather than by the handshake mechanics described here. Everything else in this window is the driver preparing the ground so that a `findElement` has somewhere to go, on Android through its pushed helper server and on Apple platforms through WebDriverAgent.