ios-device-qa

iOS device QA

Contract

Inputs

• --source <dir>: the app source directory on disk. Required.
• USB-connected, paired, trusted iPhone; macOS host with Xcode and Swift >= 5.9.
• App manifest is SwiftPM (Package.swift); at least one file-scope @Observable class with // @Snapshotable-marked writable instance var fields of JSON-native types.
• Optional --tailnet: expose the device to remote agents over Tailscale (requires tailscaled running and /var/run/tailscale.sock readable).
• Optional --recording: render an "AGENT DEMO" watermark on screencasts.
• Optional demo request ("demo", "show me", "I want to see it working"): drive every action through visible UI only.

Procedure

1. Verify bridge compatibility before mutating the app. The generator supports file-scope @Observable classes only; ObservableObject, @StateObject, and other observation models produce no accessors. The documented dependency wiring assumes a SwiftPM manifest; for an .xcodeproj or .xcworkspace do not invent package or target wiring. If either requirement is unmet, stop the bridge bootstrap without modifying the app. Preserve any installed production or TestFlight build; when a separate QA build is needed, use an isolated bundle identifier and non-production entitlements so it coexists with the production app. Report fixture-driven state, provider UI, and actual external-provider success as distinct evidence tiers.
2. Walk --source and identify every file-scope @Observable class. A property immediately preceded by the marker comment // @Snapshotable is snapshot-eligible: it must be a writable instance var with an explicit type and an internal or public setter, of a JSON-native scalar (String, Bool, integer widths, Float, Double, CGFloat), array, String-keyed dictionary, or Optional composition. Keys must be unique across observable classes. Stop with a source diagnostic instead of emitting a broken or lossy harness when any constraint is violated.
3. Show the accessor list and ask the user whether to install the DebugBridge SPM dependency into Package.swift.
4. Generate the local bridge package, typed accessors, and installed version marker with one deterministic command: gstack-ios-qa-regen --app-source "<source-dir>" --bridge-dir "<source-dir>/DebugBridge". The regenerator also removes the obsolete flat-file set from older ios-sync versions so no stale second harness remains in the app target.
5. Add the generated DebugBridge local SPM dependency to Package.swift. It ships three Debug-config-only products: DebugBridgeCore (StateServer + bridge protocols), DebugBridgeTouch (in-process touch synthesis with iOS 18+ _UIHitTestContext SwiftUI hit-testing), and DebugBridgeUI (screenshot, elements, and mutation bridges). The app target depends on DebugBridgeUI with .when(configuration: .debug), transitively pulling in Core and Touch; Release builds refuse to link these targets.
6. Wire the bridges from the @main App init, gated on #if DEBUG: call DebugBridgeUIWiring.installAll() before the StateServer opens its listener, then DebugBridgeManager.shared.start(appState: appState, register: AppStateAccessor.register) with the type discovered in step 2.
7. Build and deploy: xcodebuild -scheme <SchemeName> -destination 'platform=iOS,id=<UDID>' build install. Launch via devicectl device process launch --device <UDID> --console <bundle-id> and capture the boot token printed to os_log on first run.
8. Spawn the Mac-side daemon gstack-ios-qa-daemon. It acquires an exclusive flock on ~/.gstack/ios-qa-daemon.pid; a second invocation discovers the live daemon's port and connects rather than double-binding. The daemon immediately calls POST /auth/rotate on the iOS StateServer with a fresh in-memory-only token, so the boot token becomes useless ~5s later and anything scraping os_log past this point sees a dead credential. If a fresh daemon finds the app running after another daemon consumed that one-use token, it verifies the bundle owner, relaunches the target once, waits for the new token, verifies ownership again, then rotates. The app's StateServer binds loopback only (::1 + 127.0.0.1); tailnet ingress is exclusively the daemon's job.
9. Run the vision-driven agent loop. Each iteration: GET /screenshot and save the PNG; GET /elements for the accessibility tree; GET /state/snapshot for only the // @Snapshotable fields; decide the next action against the test goal; POST /session/acquire to grab the device lock; execute POST /tap, /swipe, /type, or POST /state/<key> write; re-screenshot and compare; record a finding if buggy; POST /session/release once the iteration is done.
10. In demo mode, drive every action through visible UI (/tap, /swipe, /type) and never use POST /state/* writes to skip steps; bump the screencap rate to 4fps so the recording shows each action as it happens. This override takes precedence over all other rules; viewers see the agent type every key and tap every button.
11. In tailnet mode (--tailnet), the daemon also binds the Tailscale interface (never 0.0.0.0), fails closed if /var/run/tailscale.sock is missing, permission-denied, or returns an unparseable WhoIs response, and mints short-lived session tokens (default 1h, max 24h) for allowlisted remote identities. Capability tiers are ordered observe < interact < mutate < restore; granting restore implies all lower tiers. Observe covers /screenshot, /elements, GET /state/*, /healthz, /session/heartbeat; interact adds /tap, /swipe, /type; mutate adds POST /state/<key>; restore adds POST /state/restore. Every authenticated mutating tailnet request writes an audit row to ~/.gstack/security/ios-qa-audit.jsonl; rejections write to `attemp…
12. Before a Release build, remove the DebugBridge SPM dependency and all #if DEBUG wiring. The structural guard (.when(configuration: .debug) plus a CI swift build -c release check) is the safety-critical path; this cleanup is a convenience flow.