In an Appium iOS Safari session, what does `appium:nativeWebTap` change about a tap on a web element?

## Two ways to press something in a mobile browser When a test clicks a button on a page there are two fundamentally different things that could happen. 1. **A page-level click.** The web bridge dispatches the click against the element inside the document. It is fast, it is reliable, and it is not what a finger does. 2. **A native tap.** The automation works out where the element sits on the physical screen and taps that point, exactly as a person would. It is slower, it can miss, and it is much closer to reality. On **iOS**, XCUITest exposes that choice as `appium:nativeWebTap`. On **Android**, the choice does not surface as a capability at all, because Chrome's clicks are answered by a Chromedriver process working inside Chrome. ## What `appium:nativeWebTap` switches on (iOS only) With the preference enabled, an iOS Safari session stops dispatching the click into the document and instead: - reads where the element is inside the page, - translates that page position into a coordinate on the device screen, - performs an ordinary native tap there through XCUITest. The consequence is that everything a real touch triggers gets triggered: focus behaviour, the on-screen keyboard, gesture handlers that only fire for genuine touches, and anything that reacts to the tap landing on whatever is topmost at that point. That last part is also the danger — a native tap hits whatever is actually on screen, so an overlay or a sticky header intercepts it exactly as it would intercept a farmhand's thumb. ## Why the translation is the hard part A page coordinate is not a screen coordinate. Safari draws its own furniture around the page, and that furniture moves the page's origin. - The tab bar occupies screen space and shifts the viewport down or up depending on where it sits. - A smart app banner, when the site advertises a native app, pushes the page content down further. - Scroll position, zoom and the visible viewport all change the mapping between a page point and a screen point. That is why the XCUITest driver carries a whole family around this single feature: `nativeWebTapStrict`, `nativeWebTapTabBarVisibility` and `nativeWebTapSmartAppBannerVisibility` as settings, `safariTabBarPosition` as a related Safari-layout setting, and `mobile: calibrateWebToRealCoordinatesTranslation` as an execute method for calibrating the translation itself. A driver does not grow that much machinery around a feature that works out of the box; the surface area is the honest signal that coordinate translation is genuinely difficult. ## Capability at start, setting during the run The preference has two faces, and knowing both is the mid-to-senior tell: - As a **capability**, `appium:nativeWebTap`, it is part of the capability set and applies from the moment the Safari session exists — before your first page has been interacted with. - As a **setting**, `nativeWebTap`, it can be changed while the session runs, so a suite can keep page-level clicks as the default and switch to native taps only for the handful of controls that need one. That second form is what makes it practical. Turning native taps on globally makes an entire suite pay the translation cost and inherit its failure modes; turning it on for one control is a targeted fix. ## Android does not have a twin, and that is not an oversight | | iOS Safari session | Android Chrome session | |---|---|---| | Who performs a click | XCUITest, or the page, depending on the preference | Chromedriver, inside Chrome | | Coordinate translation exposed | yes, with `nativeWebTap` and companions | not as an `appium:` preference | | Calibration command | `mobile: calibrateWebToRealCoordinatesTranslation` | none in this family | The divergence follows from the bridges. On Android the web commands are proxied to Chromedriver, which performs the click inside the browser it is attached to; there is no page-to-screen translation for Appium to expose. On iOS the driver is XCUITest, which is fundamentally a native automation agent, so "tap the screen where that element is" is a natural thing for it to be asked to do — and a natural thing to get wrong. ## When to reach for it on the farm dashboard On the livestock-weighing web dashboard, most steps — typing a weight, choosing an animal tag, submitting the record — are perfectly served by page-level clicks. Reach for a native tap when the behaviour under test genuinely depends on a real touch: - a control that only responds to a genuine touch sequence rather than a dispatched click, - a case where you must prove the keyboard actually appears when the weight field is tapped, - a case where you are asserting that nothing is covering the submit button, since a native tap will hit the overlay and fail honestly. And resist it elsewhere. A suite that taps natively everywhere spends its time on coordinate translation and reports overlay problems as mysterious wrong-element clicks. The judgement being tested is not "do you know the capability name" — it is whether you know that a native tap buys fidelity and pays for it in fragility, and that the whole trade-off exists on one platform only.