ios-uat

iOS UAT

Input: phone acceptance criteria, source revision, the page under test (hosted app, local preview, or a probe page), and a session scratch directory.

Compose generic UAT. Use ios_simulator for simulator observation and interaction. Start with simulator list, boot one shutdown iPhone when needed, and open the Simulator frontend before anything else so the person can watch. A missing full Xcode install, iOS runtime, pinned XcodeBuildMCP backend, or bundled AXe support is blocked; return the exact tool failure and the remediation it gives. Never click the Simulator through host-window coordinates, macOS Accessibility, or desktop mouse automation.

Use the schema action for a workflow before an unfamiliar call; it returns every allowlisted action and the pinned backend's exact argument schema. Before an interaction, capture a semantic snapshot with ui-automation snapshot-ui. Pass each action's parameters in the arguments object and pass the returned top-level snapshotToken with every action that can consume an element ref. Act only on an element ref whose target lists the requested action. After any UI action, every old token and element ref is stale: capture a fresh semantic snapshot before the next element-ref action. Use ui-automation tap, type-text, swipe, and wait-for-ui for ordinary semantic input. If a web surface is absent from the semantic tree, capture a simulator screenshot and use ui-automation tap-point with device-point coordinates from that screenshot. Device points are not host-window coordinates. Use simulator screenshot or ui-automation screenshot after the resulting state settles; screenshots are the visual record, while semantic snapshots establish which accessible control received a semantic action.

The Simulator shares the host's loopback, so a server on localhost is reachable from Safari and no tunnel is needed. Navigate through Safari's semantic controls, including its address field, instead of injecting host clicks. A pairing link opened in Safari pairs that tab; the Home Screen app is a separate origin with its own device store and pairs again, which is the same fact the install guide states. Use the allowlisted simulator-management actions for appearance and keyboard display. Install to the Home Screen through Safari's own semantic controls: More, Share, View More, Add to Home Screen, Add. Web clips run under com.apple.webapp; relaunch through visible UI when a criterion must load new code. Facts an installed app must be judged against on iOS 26: display-mode: standalone is false and navigator.standalone is true; the layout viewport is the screen minus the status bar and is anchored at the top, so 100%, dvh, and svh stop a status bar short of the bottom while lvh is the whole screen; the visual viewport shrinks to the area above the keyboard; a focused field below 16px zooms the page and the zoom outlives the blur. When a layout question is open, measure before fixing: write a probe page under the session scratch that prints screen, innerHeight, the viewport units, visualViewport, the safe-area insets, and the rectangles of the elements in question, serve it on loopback, install it beside the app, and read the numbers with the keyboard closed and open.

For any change to the phone's keyboard handling, composer, or chat layout, run scripts/uat/phone-soft-keyboard.ts; its header states the setup. It serves the hosted phone page with a per-frame layout sampler, focuses and dismisses the composer through AXe touches, and judges each change from the trace and from a screen recording. Only the recording sees motion that iOS adds outside the page's layout, such as the page sliding while the keyboard rises. One hardware key event, including an AXe type or a Cmd+V paste after simctl pbcopy, makes iOS show only the keyboard's accessory bar on focus. Before a keyboard run, set HardwareKeyboardLastSeen and AutomaticMinimizationEnabled to false in com.apple.keyboard.preferences and reboot the device. Only one host recording can run on a machine, so a live simulator panel in another session makes the recording fail.