Struct IosDriver 

pub struct IosDriver { /* private fields */ }

Driver wrapping HttpRunnerClient with host-side resolve dispatch.

Called IosDriver to make the platform explicit in the cross-platform Driver trait architecture. The type alias pub type SimctlDriver = IosDriver (in lib.rs) keeps existing callers working without source edits.

Implementations

impl IosDriver

pub fn new(runner: HttpRunnerClient) -> Self

pub fn runner(&self) -> &HttpRunnerClient

pub fn runner_mut(&mut self) -> &mut HttpRunnerClient

Mutable accessor for the wrapped client. Used by the Driver-trait pass-through (set_target_bundle_id / set_auto_activate) so the client’s per-request context can be mutated after driver construction.

pub fn with_target_bundle_id<S: Into<String>>(self, bundle: S) -> Self

Set the target bundle id sent to the runner on every request. Threads --bundle-id from the CLI down to the wire so the runner’s per-request rebind logic can resolve to the right XCUIApplication.

pub fn with_auto_activate(self, activate: bool) -> Self

Enable App-Activate: true on every request. Forces the runner to call .activate() on the resolved target before each operation. Wired from smix run --activate.

pub async fn tree( &self, include: Option<IncludeScope>, ) -> Result<A11yNode, ExpectationFailure>

Fetch full a11y tree (passthru to GET /tree).

pub async fn describe(&self) -> Result<ScreenDescription, ExpectationFailure>

Aggregate ScreenDescription (DFS visible summaries; no screenshot here — caller adds when needed).

pub async fn find_one( &self, selector: &Selector, include: Option<IncludeScope>, ) -> Result<Option<A11yNode>, ExpectationFailure>

Resolve selector → single node (passthru-ish: driver.tree + resolver).

pub async fn find_norm_coord( &self, selector: &Selector, ) -> Result<Option<(f64, f64)>, ExpectationFailure>

Resolve selector → its centroid as viewport-normalized (nx, ny) in [0, 1]. None when selector resolves no node OR the matched node has an empty / offscreen frame. Used by adapter AnchorRelative dispatch to find an anchor’s center before adding a (dx, dy) shift.

pub async fn find_all( &self, selector: &Selector, include: Option<IncludeScope>, ) -> Result<Vec<A11yNode>, ExpectationFailure>

Resolve selector → all matching nodes.

pub async fn find( &self, selector: &Selector, include: Option<IncludeScope>, ) -> Result<bool, ExpectationFailure>

Boolean existence quick-probe.

Selector-type dispatch:

• Text selectors with no spatial / index modifiers → runner /find route (Apple element query, no full-tree snapshot — the fast path).
• Id / Label / Role / Focused / Anchor selectors, and Text with spatial (below / near / …) or index (nth / first / last) modifiers → host-resolve fallback: tree() + resolve_selector_all() client-side. The runner /find route only knows how to query by text predicate, so anything richer has to ride on the full tree snapshot.

Both dispatch branches poll within TOTAL_TIMEOUT_MS on /find 500 or /tree 500 (sim still launching, runner re-attach, etc.), matching the wait_for transient-retry pattern.

pub async fn system_popups( &self, include: Option<IncludeScope>, ) -> Result<Vec<SystemPopup>, ExpectationFailure>

GET /system-popups passthru.

pub async fn system_popup_action( &self, popup_id: &str, button_id: &str, ) -> Result<bool, ExpectationFailure>

POST /system-popup-action passthru. Returns Ok(true) when the runner matched and tapped, Ok(false) on 404 not_found. Transport errors map to ExpectationFailure.

pub async fn tap( &self, selector: &Selector, include: Option<IncludeScope>, ) -> Result<ActOutcome, ExpectationFailure>

Tap a selector. Host-side resolve → centroid → runner.tap_at_norm_coord (Apple native event chain), with a 5s implicit wait + retry loop.

The resolve+centroid+normalize pipeline lives in the smix_host_coord_resolver stone; this method orchestrates the smix-specific 5s implicit-wait loop plus AI-readable failure rendering + runner injection. Tap a selector, and report what the touch landed on.

Returns an outcome rather than unit: “the touch was synthesised” and “the element was tapped” are different claims, and this used to make the first while callers read the second.

pub async fn tap_burst( &self, selector: &Selector, times: u32, interval_ms: Option<u32>, hold_ms: Option<u32>, include: Option<IncludeScope>, ) -> Result<(), ExpectationFailure>

Tap a selector several times in a row.

Resolves once, then hands the runner a burst: one synthesise carrying times touches spaced by interval_ms. The spacing is the number given, not the round-trip latency it used to be — ten separate taps cost ten ~400 ms synthesises, and a gesture gated on a 500 ms window sat right on that boundary.

No hit verdict: after the first touch the screen is expected to react, so what the later ones land on is the app’s business rather than evidence about aim.

pub async fn tap_with_mode( &self, selector: &Selector, mode: TapMode, include: Option<IncludeScope>, ) -> Result<(), ExpectationFailure>

Tap a selector via an explicit dispatch mode. Used to opt into the runner-side daemonProxySynthesize path for RN Pressable buttons whose RCTTouchHandler gesture recognizer does not fire onPress when the host-side tap_at_norm_coord Apple native event chain is used.

TapMode::DaemonProxySynthesize routes through POST /tap (runner resolves selector + synthesizes via XCTRunnerDaemonSession.daemonProxy ._XCT_synthesizeEvent:completion:). The existing SimctlDriver::tap method keeps the host-resolve + tap_at_norm_coord default for callers that don’t need the daemonProxy alternative.

pub async fn double_tap( &self, selector: &Selector, include: Option<IncludeScope>, ) -> Result<(), ExpectationFailure>

Double-tap a selector via swift sim-side XCUIElement.doubleTap(). 5s implicit-wait + retry on transport (mirrors Self::tap_with_mode). Same as Maestro doubleTapOn.

pub async fn long_press( &self, selector: &Selector, duration: Duration, include: Option<IncludeScope>, ) -> Result<PressTiming, ExpectationFailure>

Long-press a selector for duration via swift sim-side XCUIElement.press(forDuration:). 5s implicit-wait + retry on transport. Same as Maestro longPressOn.

Returns when the touch was held, anchored to this host’s clock, so a caller capturing frames alongside can tell whether they fall inside the press. See press_frame_placement.

pub async fn set_orientation( &self, orientation: Orientation, ) -> Result<(), ExpectationFailure>

Rotate sim via swift XCUIDevice.shared.orientation. Routes to the runner-client set_orientation → POST /set-orientation.

pub async fn fill( &self, selector: &Selector, text: &str, include: Option<IncludeScope>, ) -> Result<(), ExpectationFailure>

Fill text into the focused / matched input.

chunked-fill: the swift runner’s daemon _XCT_sendString path bursts every keystroke at up to 200 chars/sec, which on real-sim outraces React Native’s onChangeText debounce on the main thread — only the leading 2-3 keystrokes commit before later ones are dropped by the JS thread reconciler. The fix is host-side: split text into 1-char chunks and post each to runner /fill separately, with an INTER_CHAR_PAUSE_MS gap so the JS thread can flush its onChangeText callback before the next keystroke fires.

selector-type dispatch (mirrors find()): runner /fill only accepts text selectors (selector.text field or the _focused_ magic). For Id / Label / Role / Anchor / Text-with-modifiers selectors, host-resolve + tap the target first to give it keyboard focus, then fill via the _focused_ magic. Text-without-modifiers selectors take the fast path (direct chunked fill).

pub async fn clear( &self, selector: &Selector, include: Option<IncludeScope>, ) -> Result<(), ExpectationFailure>

Clear the focused / matched input.

Selector-type dispatch (mirrors fill()).

The runner /clear route only accepts text selectors (selector.text field) or the _focused_ magic. For Id / Label / Role / Anchor / Text-with-modifiers selectors, host-resolve + tap the target first so it owns keyboard focus, then clear via the _focused_ magic (single round-trip — clear is not chunked like fill).

pub async fn press_key(&self, key: KeyName) -> Result<(), ExpectationFailure>

POST /press-key passthru.

pub async fn scroll( &self, selector: &Selector, direction: SwipeDirection, ) -> Result<(), ExpectationFailure>

Host-side scroll-until-visible loop. Alternates driver.tree + resolve_selector (host-side probe) with runner.swipe_once (single-swipe runner gesture). Up to 30 swipes or 20s timeout.

pub async fn swipe_once( &self, direction: SwipeDirection, ) -> Result<(), ExpectationFailure>

POST /swipe-once passthru.

pub async fn hide_keyboard(&self) -> Result<(), ExpectationFailure>

POST /hide-keyboard passthru.

pub async fn back(&self) -> Result<(), ExpectationFailure>

POST /back passthru.

pub async fn tap_at_norm_coord( &self, nx: f64, ny: f64, ) -> Result<(), ExpectationFailure>

Tap at normalized (nx, ny) coordinates — escape hatch for coord-based maestro yaml ports.

(nx, ny) must be in [0, 1] (normalized to viewport). The runner converts to device pixels via the Apple native event chain (same path as the regular tap() centroid pipeline).

Escape hatch only — the selector path (tap(&selector)) is the canonical surface. This bypasses a11y resolve entirely.

pub async fn tap_by_id(&self, id: &str) -> Result<(), ExpectationFailure>

POST /tap-by-id {id} passthru — XCUIElement.tap() via the XCTest gesture-recognizer chain. SwiftUI .sheet / .alert / .confirmationDialog / .fullScreenCover dismiss buttons need this path because the default host-HID-at-coord injects an IOKit-level touch that doesn’t fire the modal’s SwiftUI binding closure. Returns ElementNotFound when the runner reports ok=false.

pub async fn webview_eval(&self, js: &str) -> Result<Value, ExpectationFailure>

Eval JS via the app-side WKWebView bridge. Direct HTTP POST to 127.0.0.1:28080/eval (iOS sim shares host loopback) — does NOT use the XCUITest runner. Returns the parsed JS result as a JSON Value; surfaces bridge error / transport failure as DriverError.

pub async fn find_text_by_ocr( &self, text: &str, locales: &[String], recognition_level: &str, ) -> Result<Option<OcrFrame>, ExpectationFailure>

POST /find-text-by-ocr passthru — Apple Vision OCR over the current XCUIScreen screenshot. Returns the matching text observation’s bounding box (UIKit normalized) or None.

pub async fn swipe_at_norm_coord( &self, from: (f64, f64), to: (f64, f64), ) -> Result<(), ExpectationFailure>

POST /swipe-at-norm-coord {from, to} passthru — escape hatch from-to swipe gesture sibling to Self::tap_at_norm_coord. from / to are normalized to viewport (0, 1). Escape-hatch companion to tap_at_coord.

pub async fn foreground( &self, bundle_id: &str, ) -> Result<(), ExpectationFailure>

POST /foreground {bundleId} passthru.

pub async fn wait_for( &self, selector: &Selector, timeout: Duration, include: Option<IncludeScope>, ) -> Result<A11yNode, ExpectationFailure>

Poll until the selector resolves to a node, or timeout fires. Returns the matched node (cloned). 5s default budget, 250 ms poll interval.

pub async fn dispose(&self) -> Result<(), ExpectationFailure>

Idempotent close hook. The current implementation has no sidecar / no cache to tear down; reserved for future use.

Trait Implementations

impl Driver for IosDriver

fn set_target_bundle_id(&mut self, bundle: &str)

iOS impl: mutate the wrapped HttpRunnerClient so every subsequent request carries the App-Bundle-Id header. Runner side rebinds XCUIApplication(bundleIdentifier:) per request.

fn set_auto_activate(&mut self, activate: bool)

iOS impl: mutate the wrapped client to send App-Activate: true on every request.

fn set_force_key_events(&mut self, force: bool)

iOS impl: force key-event dispatch mode on the wrapped client. Sends Input-Dispatch-Mode: key-events header on every request; runner-side dispatches via daemon key events instead of a11y-anchored XCUIElement.typeText.

fn set_session_id(&mut self, id: Option<String>)

iOS impl: attach / clear the Session-Id header on every subsequent request. When set, the runner short-circuits per-request activation and reuses the session-cached XCUIApplication binding.

fn platform(&self) -> Platform

Platform identifier — Platform::Ios or Platform::Android.

fn as_ios_driver(&self) -> Option<&IosDriver>

iOS-only escape hatch: access IosDriver’s inherent runner() for capsule recording (start_record / stop_record) + describe() aggregation. Android impl returns None. Default None so non-iOS impls don’t need to implement.

fn tree<'life0, 'async_trait>( &'life0 self, include: Option<IncludeScope>, ) -> Pin<Box<dyn Future<Output = Result<A11yNode, ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetch full a11y tree (GET /tree).

fn find<'life0, 'life1, 'async_trait>( &'life0 self, selector: &'life1 Selector, include: Option<IncludeScope>, ) -> Pin<Box<dyn Future<Output = Result<bool, ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Boolean existence quick-probe.

fn find_one<'life0, 'life1, 'async_trait>( &'life0 self, selector: &'life1 Selector, include: Option<IncludeScope>, ) -> Pin<Box<dyn Future<Output = Result<Option<A11yNode>, ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Resolve selector → single matching node.

fn find_all<'life0, 'life1, 'async_trait>( &'life0 self, selector: &'life1 Selector, include: Option<IncludeScope>, ) -> Pin<Box<dyn Future<Output = Result<Vec<A11yNode>, ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Resolve selector → all matching nodes.

fn find_norm_coord<'life0, 'life1, 'async_trait>( &'life0 self, selector: &'life1 Selector, ) -> Pin<Box<dyn Future<Output = Result<Option<(f64, f64)>, ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Resolve selector → centroid as viewport-normalized (nx, ny).

fn find_text_by_ocr<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, text: &'life1 str, locales: &'life2 [String], recognition_level: &'life3 str, ) -> Pin<Box<dyn Future<Output = Result<Option<OcrFrame>, ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Apple Vision / ML Kit OCR find text in current screenshot. recognition_level is "accurate" or "fast".

fn system_popups<'life0, 'async_trait>( &'life0 self, include: Option<IncludeScope>, ) -> Pin<Box<dyn Future<Output = Result<Vec<SystemPopup>, ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

List visible system-level popups (alerts, permission dialogs).

fn system_popup_action<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, popup_id: &'life1 str, button_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<bool, ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Tap a button on a system popup by id.

fn wait_for<'life0, 'life1, 'async_trait>( &'life0 self, selector: &'life1 Selector, timeout: Duration, include: Option<IncludeScope>, ) -> Pin<Box<dyn Future<Output = Result<A11yNode, ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Wait until selector resolves (returns matched node when ready).

fn tap<'life0, 'life1, 'async_trait>( &'life0 self, selector: &'life1 Selector, include: Option<IncludeScope>, ) -> Pin<Box<dyn Future<Output = Result<ActOutcome, ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Tap a selector, and report what the touch landed on.

fn tap_burst<'life0, 'life1, 'async_trait>( &'life0 self, selector: &'life1 Selector, times: u32, interval_ms: Option<u32>, hold_ms: Option<u32>, include: Option<IncludeScope>, ) -> Pin<Box<dyn Future<Output = Result<(), ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Tap an element (default mode = element-anchored coord tap). Tap a selector times times, spaced on the event timeline.

fn tap_with_mode<'life0, 'life1, 'async_trait>( &'life0 self, selector: &'life1 Selector, mode: TapMode, include: Option<IncludeScope>, ) -> Pin<Box<dyn Future<Output = Result<(), ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Tap with explicit mode (Path A vs Path B).

fn tap_at_norm_coord<'life0, 'async_trait>( &'life0 self, nx: f64, ny: f64, ) -> Pin<Box<dyn Future<Output = Result<(), ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Tap at viewport-normalized coordinate (escape hatch).

fn tap_by_id<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Tap by accessibility identifier via the swift /tap-by-id route (IOHID synthesize at element-frame center).

fn double_tap<'life0, 'life1, 'async_trait>( &'life0 self, selector: &'life1 Selector, include: Option<IncludeScope>, ) -> Pin<Box<dyn Future<Output = Result<(), ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Double-tap a selector.

fn long_press<'life0, 'life1, 'async_trait>( &'life0 self, selector: &'life1 Selector, duration: Duration, include: Option<IncludeScope>, ) -> Pin<Box<dyn Future<Output = Result<PressTiming, ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Long-press a selector for duration.

fn fill<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, selector: &'life1 Selector, text: &'life2 str, include: Option<IncludeScope>, ) -> Pin<Box<dyn Future<Output = Result<(), ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Fill text into a focused / matched input.

fn clear<'life0, 'life1, 'async_trait>( &'life0 self, selector: &'life1 Selector, include: Option<IncludeScope>, ) -> Pin<Box<dyn Future<Output = Result<(), ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Clear text from a focused / matched input.

fn press_key<'life0, 'async_trait>( &'life0 self, key: KeyName, ) -> Pin<Box<dyn Future<Output = Result<(), ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Press a named key (Return / Tab / Backspace / etc).

fn scroll<'life0, 'life1, 'async_trait>( &'life0 self, selector: &'life1 Selector, direction: SwipeDirection, ) -> Pin<Box<dyn Future<Output = Result<(), ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Scroll until a selector is visible.

fn swipe_once<'life0, 'async_trait>( &'life0 self, direction: SwipeDirection, ) -> Pin<Box<dyn Future<Output = Result<(), ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

One-shot swipe in a direction (no probe loop).

fn swipe_at_norm_coord<'life0, 'async_trait>( &'life0 self, from: (f64, f64), to: (f64, f64), ) -> Pin<Box<dyn Future<Output = Result<(), ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Swipe between two viewport-normalized coords.

fn hide_keyboard<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Dismiss the keyboard.

fn back<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Trigger “back” gesture (iOS edge-swipe / Android KEYCODE_BACK).

fn set_orientation<'life0, 'async_trait>( &'life0 self, orientation: Orientation, ) -> Pin<Box<dyn Future<Output = Result<(), ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Rotate the device.

fn foreground<'life0, 'life1, 'async_trait>( &'life0 self, bundle_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Bring app to foreground.

fn webview_eval<'life0, 'life1, 'async_trait>( &'life0 self, js: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Value, ExpectationFailure>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Evaluate JavaScript in a WebView (iOS: fixture bridge :28080; Android: Chrome DevTools Protocol via adb forward).