In Appium, what does DELETE /session/:sessionId actually tear down on the device?

## The request, and what sends it `DELETE /session/:sessionId` is the W3C WebDriver command that ends a session. It carries no body, it names the session in its URL, and in practice you never type it — a client binding sends it when your code quits the driver. Its job is narrower than most suites assume, and the gap between what it does and what people believe it does is exactly where "the device was dirty" bugs come from. ## What the driver unwinds The delete ends **the driver's session**, and the driver undoes the setup it performed during the handshake: - **The session with the device-side agent.** On Android the UiAutomator2 driver ends its conversation with the helper server it started on the device; on Apple platforms the XCUITest driver ends the WebDriverAgent session it was driving. - **The host-side plumbing opened for this session**, including the per-session ports the session was given. - **The server-side slot**, so a new session can be created against the same device. That list is the driver's own footprint. Notice what is not on it: anything your test did. ## What survives the delete | What survives | Why it survives | |---|---| | The app under test's installation | The delete says nothing about the app; the session's reset capabilities decide whether a build is replaced or its data cleared | | Permissions the run granted | A granted permission is device state held by the operating system, not session state held by the driver | | A simulated location, altered connectivity, changed system settings | Same reason — the driver changed the device, and it does not journal those changes in order to reverse them | | The agent on the device | Nothing in the delete promises that WebDriverAgent or the Android helper packages are uninstalled afterwards | | Files the run produced | Screenshots, recordings and pulled logs stay wherever they were written | ## Why Appium cannot simply roll the device back To restore a device, something would have to record every change made during the session and know how to reverse each one — including changes the app under test made on its own, which no driver observed. That is not a session's job and no driver claims it. The delete promises only that the automation session is over and that the resources the driver itself acquired are released. ## The device is shared even when the session is not Picture the birdwatching sightings suite on a pooled phone. It grants location permission so the sightings map can centre itself, sets a simulated location at a nature reserve, records a video of a tricky scroll, then quits. The delete returns the phone to the pool. The next suite gets a phone with location permission already granted for that app and a simulated location still applied. Nothing has failed. The second suite simply did not start where it assumed it would — and if one of its cases depends on being *asked* for permission, it fails in a way that reads like a product bug. The discipline that follows is short: 1. **A session may only assume what it seeds itself.** If a case needs a permission denied, it seeds that state; if it needs a real location, it clears the simulated one. 2. **If a case needs a genuinely fresh app, the session's capabilities say so.** That decision lives in the capabilities the handshake sent, not in how the previous session ended. 3. **Treat the device as shared inventory.** Write down what your run leaves behind, so the next team is not debugging your side effects as if they were their own. ## When the delete never arrives If the client process dies — killed by a pipeline timeout, crashed, or simply stopped — no delete is sent, and the server keeps holding that session until its idle budget expires and the server ends it. The device comes back either way. It comes back later, and the run learns nothing on the way out. ## Reading a delete in a log The ending of a session is one of the more informative lines in a server log, because there are only a few shapes it can take: - A clean run shows the delete arriving right after the last command. - A run with no delete at all was killed rather than finished — look at the runner, not at the app. - A delete arriving long after the last command means the session sat idle in that gap, which is device time nobody used and is worth explaining. - A delete that fails because the session id is unknown means something already ended that session before the client got there. None of those four is a device problem, and telling them apart takes seconds once you hold on to the one fact that governs the command: its scope is the driver, and nothing else.