In Appium, which requests list a session's contexts and switch into one on Android and iOS?

## Contexts are the session's surface selector An Appium session drives one surface at a time. On both Android and iOS a session starts on the native one, whose handle is `NATIVE_APP`. When the app under test also renders web content — the pharmacy refill-reminder app's insurance co-pay page inside an embedded web view — that content is reachable only through a second handle. Choosing between them is exactly what the two context requests do, and they are ordinary protocol commands: not capabilities sent at session start, and not driver execute methods. ## The plural path lists, the singular path switches - `GET /session/:sessionId/contexts` returns the handles available at this moment, as a list of strings. It changes nothing and is cheap enough to call at any screen boundary. - `POST /session/:sessionId/context` carries one handle as `name`. From the moment it returns, finds, source reads and element interactions are answered from that surface. The plural-versus-singular pairing is worth memorising, because mixing them is the commonest beginner mistake: a POST to the plural path is not a switch, and reading the singular path is not a listing. Both routes are spelled with `:sessionId`, the session identifier the server handed back when the session was created. ## What the list actually contains The first entry a healthy session shows is `NATIVE_APP`. After that come the web views the driver has detected, each named with the `WEBVIEW_` prefix. The list is a snapshot: a web view that the refill-reminder app has not opened yet is not in it, and one that has been destroyed drops out. That is why the list is read at the point of use rather than once at session start. ## The richer read: mobile: getContexts `mobile: getContexts` is an execute method declared by the Android drivers — UiAutomator2 and Espresso inherit it from `appium-android-driver` — and by the XCUITest driver. It answers the same question with more detail, including each view's title and URL, which is what you need when several web views are listed and their names alone cannot tell you which is the co-pay page. It does not replace the plain listing; it is the detailed form of the same question, and it travels as an execute method rather than as its own route. ## Where the platforms diverge, and where they do not | | Android (UiAutomator2 or Espresso) | Apple (XCUITest) | |---|---|---| | listing request | `GET /session/:sessionId/contexts` | `GET /session/:sessionId/contexts` | | switching request | `POST /session/:sessionId/context` | `POST /session/:sessionId/context` | | native handle | `NATIVE_APP` | `NATIVE_APP` | | web handle suffix | the package of the process hosting the view | a numeric page id assigned at runtime | The routes are identical; the values are not. A test that hardcodes an Android-shaped handle and runs on an Apple device fails at the switch, not at the find, and the error is much easier to read for it. ## A refill-reminder flow that reads correctly 1. Drive the native reminder list and tap **Refill now** — still on `NATIVE_APP`. 2. List the contexts and keep the result; it is the evidence for whatever happens next. 3. Choose the `WEBVIEW_` handle that belongs to the co-pay page. 4. Post that handle to the singular context route. 5. Assert the page's fields, complete the co-pay step, and read whatever the page confirms. 6. Post `NATIVE_APP` to return, then continue with the native confirmation screen. ## Mistakes worth naming - Posting to the plural path, or expecting the listing to change the current surface. - Assuming the endpoints differ between Android and iOS; they do not, only the handles do. - Treating `mobile: getContexts` as a replacement for the listing route rather than its detailed sibling. - Listing once at session start and reusing the result later, when the web view of interest did not exist yet. - Forgetting the return trip, so later native steps run against a page that has no such elements. A junior who can name both requests, say which is which, and add that the pair is identical on Android and iOS while the handle values are not, has given the complete answer to this question.