Crate smix_sdk

Expand description

smix-sdk — user-facing public surface for the smix Rust library.

Wraps SimctlDriver + SimctlClient + HttpRunnerClient with an ergonomic Rust API.

use smix_sdk::{App, text};
use std::time::Duration;

let app = App::connect_to_runner(22087).await?;
app.launch("com.example.app").await?;
app.wait_for(&text("Login"), Duration::from_secs(5)).await?;
app.tap(&text("Login")).await?;
app.fill(&text("Email"), "user@example.com").await?;
app.press_key(smix_sdk::KeyName::Return).await?;

Re-exports§

pub use issued_ledger::IssuedAction;
pub use issued_ledger::IssuedKind;
pub use issued_ledger::IssuedLedger;
pub use device_control::DeviceControl;
pub use device_control::Permission;
pub use ios_device::IosDeviceControl;
pub use android_device::AndroidDeviceControl;
pub use capsule::CapsuleReconciliation;
pub use capsule::DEFAULT_RECONCILE_WINDOW_MS;
pub use capsule::FOCUS_CHANGE_RAW_CODE;
pub use capsule::reconcile;

Modules§

android_device: Android DeviceControl impl backed by smix_adb::AdbClient.
capsule: Capsule reconciliation (pure function).
device_control: v6.0 c1b — DeviceControl trait: cross-platform sim/host control.
ios_device: v6.0 c1b — iOS DeviceControl impl backed by SimctlClient.
issued_ledger: v5.1 c3 — SDK 内部 issued-action 账本(Capsule 软胶囊 G angle 主线)。

Structs§

A11yNode: Single-node accessibility snapshot returned by /tree. Fields mirror the Swift-side TreeRoute.nodeToDict shape.
AnchorBox: Anchor base form’s spatial keys. Identical shape to the spatial half of Modifiers but without nth/first/last (Anchor stacks IndexModifiers separately).
App
ElementSummary: Element summary — projected view of an A11yNode used in AI-readable failure prompts and driver.describe() output.
ExpectationFailure: Structured failure thrown by SDK matchers and driver calls. Shape is AI-feed-back-ready.
FailureInit: Builder/Init form for ergonomic construction.
HttpRunnerClient: HTTP client to the swift-side SmixRunnerCore. Async (tokio-based). Constructed once per Cell; ensure_reachable memoizes a successful /health probe so subsequent calls don’t re-probe.
IndexModifiers: IndexModifiers — the subset BaseAnchor can stack. Kept separate from Modifiers so anchor callers can’t accidentally write the top-level spatial form (which would be two surfaces for the same intent).
LaunchAppOptions: Typed shape of maestro yaml launchApp: mapping. Adapter assembles this from yaml fields; SDK consumes it in App::launch_app_with_options. Covers maestro launchApp.permissions / arguments / stopApp.
LaunchResult: Launched-app result.
Modifiers: Modifier set stackable on Text / Id / Label / Role base forms. Spatial keys (near/below/above/leftOf/rightOf/inside) carry recursive selectors that resolve to an anchor node; index keys (nth/first/last) pick from the surviving candidate list.
OcrFrame: Normalized OCR bounding box returned by HttpRunnerClient::find_text_by_ocr. Coordinates are normalized to [0, 1] in UIKit coord space (top-left origin, y-down). Apple Vision’s native bbox is bottom-left origin + y-up — the swift handler converts before returning so all consumers see UIKit coords.
Rect: Logical-points rectangle (origin top-left, +x right, +y down — matches UIKit / XCUITest coordinate space). All fields f64 because the runner /tree route emits floating-point points (sub-pixel scale factors).
ScreenDescription: Aggregate screen description. elements is a DFS-collected ordered list of visible+enabled ElementSummary entries; screenshot is an optional base64 PNG; frontApp / summary / captured_at are caller-populated metadata.
Session: App::open_session; drop the value or call Session::close to release. While a session is open the wrapped App sends the Session-Id header on every request, and the runner uses the session’s cached XCUIApplication binding — no per-request activation storm.
SimctlClient: Stateless wrapper around xcrun simctl. Methods are free functions in spirit (no instance state beyond optionally-cached xcrun path); kept as a struct for API ergonomics + future caching.
SystemPopup: One system-popup discovered on the screen (alert / sheet / banner).
True: Newtype around true — used as the Selector::Focused discriminator. Serializes/deserializes as the JSON literal true.

Enums§

Appearance: UI appearance mode for xcrun simctl ui <udid> appearance.
AssertScreenshotOutcome: Outcome of App::assert_screenshot. Distinguishes the first-run “auto-record baseline” path (which writes the captured PNG to disk and treats as Ok) from the steady-state diff path (which compares dhash hamming distance against the recorded baseline).
FailureCode: All failure codes smix surfaces back to the SDK / MCP / CLI (SCREAMING_SNAKE_CASE wire).
IncludeScope: include scope literal — currently only all-windows (system popups pierce the app frame).
KeyName: Keyboard key name for press_key / record (camelCase serde 1:1 跟 TS).
LaunchFreshOp: Atomic op in the App::launch_fresh orchestration plan. Exposed so the plan is testable as a pure function (no SimctlClient stub — and a stub wouldn’t help much since SimctlClient is a ZST).
MaestroOrientation: Maestro setOrientation: <variant> literal enum. landscape yaml alias normalizes to LandscapeLeft at the parser layer (same as maestro default). 1:1 mirrors smix_driver::Orientation.
Pattern: String-or-regex pattern. Wire-compatible: plain JSON string ↔ Pattern::Text; tagged object {regex, flags} ↔ Pattern::Regex.
PermissionAction: Maestro yaml permissions: action — controls iOS privacy state per bundle. Maestro yaml parity:
ResetAppDataWaitFor: v1.0.14 Cluster A — completion-signal wait strategy for the resetAppData verb (URL-scheme JS-wipe). See .claude/rfcs/1.0.14-*.md §Cluster A. The runtime executor (smix-adapter-maestro) is responsible for interpreting these variants; smix-sdk owns the type so the adapter’s Step and the runtime’s dispatch stay in agreement.
Role: Accessibility role enum (29 variants).
RunnerScrollSelector: Reduced selector shape used by /scroll (text-or-id only; complex selectors are host-side-resolved before reaching the runner).
RunnerTransportError: Transport-level failure (network, non-2xx, malformed body). Mirrors TS RunnerTransportError 1:1.
Selector: Selector — 6 mutually exclusive base forms.
SessionState: Top-level surface for test authors. Mirrors Playwright’s page deliberately — AI authoring quality is highest when names overlap with corpus the AI was trained on.
SimctlError: Failure variants for any xcrun simctl invocation.
SimctlPermission: Permission names accepted by xcrun simctl privacy <udid> grant <name>.
SwipeDirection: Maestro yaml direction: semantic (per [[smix-must-be-superset-of-maestro]]): the direction names what content the caller wants to see (navigation through content), NOT the finger gesture direction. Down = “navigate down through content” = reveal what’s BELOW the current viewport (visually content moves up, finger gestures up). Mirrors maestro CLI direction: DOWN semantics.
TapMode: POST /tap mode discriminator.

Functions§

assert_screenshot_inner: Nucleus of App::assert_screenshot. Wraps fs IO + the dhash algorithm without any App dependency, so it can be exercised in host-side unit tests. Helper fn — not a user-facing capability.
build_suggestions: Generate “Did you mean …?” suggestions from the current visible element list. Contract: threshold > 0.5, top 3, score desc → field (name > text) → DFS index asc.
collect_visible_summaries: Collect up to limit visible+enabled nodes (DFS pre-order), projecting each via summarize_node. Default limit = 1000.
describe_selector: Human / AI-readable rendering of a Selector for error prompts and logs. Stable enough that AI can pattern-match against past failures. Mirrors TS describeSelector in src/core/selector.ts:118-160 1:1.
edit_distance: Levenshtein edit distance (Wagner-Fischer).
focused: focused() shortcut.
id: id("btn-x") shortcut.
is_visible_enough: Visibility check.
label: label("Settings") shortcut.
match_text: Match a Pattern against the six text-bearing fields of a node (label, title, value, placeholderValue, identifier, text) — OR semantics, case-insensitive. SDK convenience wrapper that compiles the pattern on every call; for hot loops prefer Pattern::compile once + match_text_compiled per node.
match_text_compiled: Text matching against an A11yNode. 1:1 with TS src/core/resolve-selector.ts:153-184 (matchText).
plan_launch_fresh_calls: Pure planner for App::launch_fresh — computes the simctl op sequence + warnings from (clear_state, clear_keychain, app_path).
plan_launch_fresh_calls_v2: v1.0.4 §D12 — extended planner with an explicit force_reinstall switch. When false (the new default), clear_state=true runs the in-place sandbox clear + privacy reset instead of simctl uninstall + install. This avoids the iOS 26.5 XCUITest binding loss (feedback §F) and the ReportCrash “Insight quit unexpectedly” system dialog (feedback §H) — both of which stem from the uninstall+install sequence.
role: role(Role::Button) shortcut.
role_named: role_named(Role::Button, "Submit") shortcut.
similarity: Normalized [0, 1] string similarity. 1 = identical, 0 = completely different.
summarize_node: Project an A11yNode to an ElementSummary.
text: text("Login") shortcut. Mirrors TS { text: 'Login' } shorthand.
text_regex: text_regex("^Lo") shortcut.
visible_area: Intersection area in logical points².

Type Aliases§

Bounds: Bounds alias — Bounds and Rect are used interchangeably. Downstream code may prefer one name or the other.
SimctlDriver: Back-compat alias. SimctlDriver was renamed to IosDriver for cross-platform naming; this alias keeps existing imports use smix_driver::SimctlDriver compiling.

Crate smix_sdk

Crate smix_sdk Copy item path

Re-exports§

Modules§

Structs§

Enums§

Functions§

Type Aliases§

Crate smix_sdk