In Appium, what does `appium:printPageSourceOnFindFailure` do, and what does it cost?

## What the capability switches on `appium:printPageSourceOnFindFailure` is a **diagnostic**, not a timing control. When it is set and a find command fails, the Appium server writes the current page source — the whole XML rendering of the screen's element hierarchy — into **its own log**, next to the failure. Nothing about the search itself changes: the same query runs for the same length of time and fails the same way. All the capability buys is evidence. It is one of the small set of capabilities Appium's base driver declares rather than a driver-specific one, so it applies whichever platform driver is handling the session — the Android drivers and the XCUITest driver alike. It is not a W3C standard capability name, so it is sent prefixed, as `appium:printPageSourceOnFindFailure`, in the session's capabilities. Two things about *when* the dump happens are worth being precise about. A find in Appium is not a single instantaneous lookup: while the session's find window is open the server re-issues the query on a roughly **500 ms** cadence, so a failed find represents repeated attempts rather than one. And the hierarchy that lands in the log is the screen as it stood **at the point the command reported failure**, not as it stood when the command was first issued. If the app moved on during the search, the dump shows where it ended up. ## The dump is not the same document on Android and on iOS | | Android, via the UiAutomator2 driver | iOS, via the XCUITest driver | |---|---|---| | Where the XML comes from | the driver's rendering of the current view hierarchy | XML derived from WebDriverAgent's element snapshot | | What the nodes are called | Android widget class names | `XCUIElementType` names | | What you scan for | `resource-id`, `content-desc`, `text` | `name`, `label`, `value` | So the capability is portable and its output is not. A helper that greps an Android dump for a `resource-id` finds nothing in an Apple one, and a locator inferred by eye from one platform's dump does not transfer to the other. That matters most when the same test runs on both: the failure looks identical in the report and the evidence underneath it does not. ## What it costs - Every failed find pays for a **full hierarchy traversal**, on top of the search that already failed. - The deeper and busier the screen, the more that costs — a dense list, or a screen with many nodes off-view, is the expensive case on either platform. - Each dump writes a large block of XML into the server log, so log volume grows with the number of misses, not with the number of tests. - A step that deliberately checks something is **absent** ends on a failed find too, so it pays for a dump every time it does the right thing. - On a suite that is currently red in many places the cost compounds exactly when you can least afford the run to be slower. That is why it is opt-in. A session that does not set the capability never dumps, and the usual pattern is off for routine runs and on deliberately. ## Using it well 1. Turn it on for a **targeted re-run** of the failing test, on the same platform and the same device where the failure happened — a hierarchy from a different device is a different screen. 2. Collect the **server** log for that run. The XML is not attached to the exception the client raises, so a test report on its own will never show it. 3. Read the dump as evidence about the screen, not about the locator: it says what was present at failure time, which separates *the element was never there* from *the element was there under a different name*. 4. Turn it back off, or confine it to a debugging profile, once you have what you need. ## What it does not give you It does not say why the element was missing, only what the hierarchy held instead. It does not make the find wait longer or try harder, and it does not change the outcome of the command in any way. It does not travel back to the client, so nothing in a test can assert on it. And it is faithful only to what the driver could reach: on a screen the driver cannot fully see, the dump describes the driver's view, which is not always what a person holding the device would describe. Treat it as the first artefact to reach for on an unexplained find failure, and as something you switch on, use, and switch off again — a capability with a real running cost that happens to be cheap in the one situation where you actually need it.