Build-Time Runs

## The still image is the one thing that does not diverge Appium is a W3C WebDriver server, so the screenshot command is inherited from the protocol rather than invented per platform. A test issues `GET /session/:sessionId/screenshot` and the server answers with a JSON body whose `value` is a **base64-encoded PNG** of the whole screen. That holds for an Android session driven by the UiAutomator2 driver and for an Apple session driven by the XCUITest driver: same route, same encoding, same response shape. Language clients wrap it in a helper, but underneath every one of them issues that request. This matters because almost nothing else about evidence capture in Appium is portable. Video, live streaming and audio are each answered by a **different execute method on a different driver**, and any helper that captures them has to branch on `platformName`. The still screenshot is the exception, and it is why a cross-platform suite for a cattle-auction bidding app can attach a "what the run saw" image on both platforms from one line of shared code. ## What the call actually returns - The payload is the **whole screen**, not just the application window: status bars, notification shades and any system dialog drawn over the auction lot list all appear in it. - It is a **PNG**, base64-encoded inside the JSON envelope, so a large device screen becomes a sizeable string; capturing after every step is real bytes over the wire. - It is a snapshot of the display, so an in-flight animation or a half-drawn bid list is captured mid-flight. - It carries **no element metadata**. If you need the tree, that is `GET /session/:sessionId/source`, a different command. - Appium's route tables spell the session placeholder `:sessionId`. `/session/:id/screenshot` is not the form the server documents. ## What each driver adds on top The common call is the floor, not the ceiling. Each driver declares extras in its own execute-method map or settings reference, and those are **not** shared: | Concern | Android (UiAutomator2 / the Android drivers) | Apple (XCUITest) | |---|---|---| | Standard still | `GET /session/:sessionId/screenshot` | `GET /session/:sessionId/screenshot` | | Extra still commands | `mobile: screenshots`, `mobile: viewportScreenshot` | `mobile: source` for the tree, not the image | | Named tuning settings | `mjpegServerScreenshotQuality`, `mjpegBilinearFiltering` | `screenshotQuality`, `screenshotOrientation`, `webScreenshotMode` | | Video | `mobile: startMediaProjectionRecording` | `mobile: startXCTestScreenRecording`, `mobile: startScreenRecording` | `mobile: screenshots` and `mobile: viewportScreenshot` are declared in the **UiAutomator2 driver's own** execute-method map, alongside `mobile: viewportRect`; they let an Android session ask for per-display images or for the viewport region rather than the whole display. XCUITest's settings reference declares `screenshotQuality` and `screenshotOrientation`, which change how the still is produced on Apple platforms. Attributing one of these to the wrong driver is the classic mistake here, and no spell-check catches it because every identifier involved is real. ## Where the still stops being enough A single PNG answers "what was on screen when the assertion failed". It does not answer: 1. What happened in the three seconds before the failure — that needs a recording. 2. Whether the element existed but sat off-screen — that needs the page source. 3. Why a tap landed on the wrong auction lot — that usually needs the element tree and a video together. That is why a serious Appium harness pairs the screenshot with a platform-specific recording, and why "we take screenshots" should be read as the beginning of an evidence story rather than the whole of it. ## Failure modes worth recognising - Calling the command **after** the session ends. `DELETE /session/:sessionId` invalidates the id, so the capture has to happen inside the failure handler while the session is still alive. - Writing the base64 string straight to disk without decoding it, producing a "corrupt" PNG that is really a text file. - Capturing on every step across a large parallel run and being surprised by the artefact volume; the encoding cost is paid per call. - Treating the image as proof of visibility. On Apple platforms an element can be present in the tree and rendered under another view; the picture shows the composite, not the hierarchy. - Expecting two runs of the same screen to produce byte-identical images. A clock and a battery indicator differ every time, which is why comparing images is a separate discipline from capturing them. The summary a junior should be able to give: one request, both platforms, base64 PNG of the whole screen — and everything richer than that is per driver.