@devicelab/maestro-runner-darwin-arm64 1.1.25 → 1.1.28

package/drivers/ios/DevicelabIOSRunner/DevicelabIOSRunnerUITests/RunnerTests+Lifecycle.swift

@@ -136,6 +136,65 @@ extension RunnerTests {
     currentBundleId = nil
   }
 
+  /// The app to snapshot when the caller named none: `target` while it is
+  /// still in front, otherwise whatever is in front now. The target was
+  /// chosen when the command arrived; an app that has since left the screen
+  /// (Home, the app switcher, a crash) stops answering accessibility
+  /// queries, and XCTest then waits 30s to find it, and retries twice,
+  /// holding every later command behind it.
+  func foregroundTarget(_ target: XCUIApplication) -> XCUIApplication {
+    if target.state == .runningForeground {
+      return target
+    }
+    guard let front = frontmostApplication() else {
+      return target
+    }
+    NSLog("AGENT_DEVICE_RUNNER_RETARGET from_state=%d", target.state.rawValue)
+    currentApp = front
+    return front
+  }
+
+  /// The command's appBundleId, trimmed; nil when absent or blank.
+  func normalizedBundleId(_ command: Command) -> String? {
+    let trimmed = command.appBundleId?.trimmingCharacters(in: .whitespacesAndNewlines)
+    return (trimmed?.isEmpty ?? true) ? nil : trimmed
+  }
+
+  /// Where a read-only command (see isPassiveReadCommand) reads from.
+  enum PassiveReadTarget {
+    case app(XCUIApplication)
+    /// No app could be named without launching one; this is the reply.
+    case refused(Response)
+  }
+
+  /// Resolves the app a read-only command reads without activating,
+  /// launching or waiting for anything. A named app is read in whatever
+  /// state it is in — the command reports that state rather than changing
+  /// it; bringing it forward would make every settle poll yank a
+  /// backgrounded app back on screen. With no name, the frontmost app is
+  /// read. If that cannot be resolved the command fails: the old fallback,
+  /// launching the placeholder host app, would cover the real screen.
+  func passiveReadTarget(requestedBundleId: String?) -> PassiveReadTarget {
+    if let bundleId = requestedBundleId {
+      if currentBundleId == bundleId, let current = currentApp {
+        return .app(current)
+      }
+      return .app(XCUIApplication(bundleIdentifier: bundleId))
+    }
+    if let front = frontmostApplication() {
+      return .app(front)
+    }
+    return .refused(
+      Response(
+        ok: false,
+        error: ErrorPayload(
+          code: "NO_TARGET_APP",
+          message: "no appBundleId given and the frontmost app could not be resolved"
+        )
+      )
+    )
+  }
+
   func targetNeedsActivation(_ target: XCUIApplication) -> Bool {
     let state = target.state
 #if os(macOS)
@@ -266,7 +325,7 @@ extension RunnerTests {
 
   func isReadOnlyCommand(_ command: Command) -> Bool {
     switch command.command {
-    case .interactionFrame, .findText, .readText, .snapshot, .screenshot:
+    case .interactionFrame, .findText, .readText, .snapshot, .screenshot, .idle:
       return true
     case .alert:
       let action = (command.action ?? "get").lowercased()
@@ -282,6 +341,14 @@ extension RunnerTests {
     return message.contains("is not available")
   }
 
+  /// Commands that only observe the target app. They never activate or
+  /// launch it (see passiveReadTarget): a caller polls them many times a
+  /// second while a screen settles, and an observation that moves the app
+  /// changes the thing it observes.
+  func isPassiveReadCommand(_ command: CommandType) -> Bool {
+    command == .snapshot || command == .idle
+  }
+
   func isInteractionCommand(_ command: CommandType) -> Bool {
     switch command {
     case
@@ -306,20 +373,49 @@ extension RunnerTests {
 
   func isRunnerLifecycleCommand(_ command: CommandType) -> Bool {
     switch command {
-    case .shutdown, .recordStop, .screenshot, .uptime, .idleCheck, .awaitIdle:
+    case .shutdown, .recordStop, .screenshot, .uptime, .idleCheck, .awaitIdle, .settle:
       return true
     default:
       return false
     }
   }
 
+  // MARK: - Idle
+
+  /// Runs the idle command against `app` (already resolved without
+  /// activation). The wait happens only for a foreground app: XCTest skips
+  /// its quiescence check for any other and leaves the flags stale, so there
+  /// is nothing honest to report but idle: false.
+  func executeIdle(app: XCUIApplication, command: Command) -> Response {
+    let capMs = min(max(command.timeoutMs ?? Self.idleDefaultTimeoutMs, 0), Self.idleMaxTimeoutMs)
+    let state = app.state
+    if capMs == 0 || state != .runningForeground {
+      let reason = capMs == 0 ? "not waited: timeoutMs is 0" : "not waited: app is not in the foreground"
+      return idleResponse(idle: false, waitedMs: 0, app: app, message: reason)
+    }
+    let started = ProcessInfo.processInfo.systemUptime
+    let outcome = RunnerXCTestTimeouts.waitForQuiescence(of: app, timeout: capMs / 1000)
+    let waitedMs = (ProcessInfo.processInfo.systemUptime - started) * 1000
+    switch outcome {
+    case .idle:
+      return idleResponse(idle: true, waitedMs: waitedMs, app: app, message: "quiescent")
+    case .busy:
+      return idleResponse(idle: false, waitedMs: waitedMs, app: app, message: "not quiescent within timeoutMs")
+    default:
+      return idleResponse(idle: false, waitedMs: waitedMs, app: app, message: "quiescence API unavailable")
+    }
+  }
+
+  private func idleResponse(idle: Bool, waitedMs: Double, app: XCUIApplication, message: String) -> Response {
+    Response(
+      ok: true,
+      data: DataPayload(message: message, appState: appStateString(app), idle: idle, waitedMs: waitedMs)
+    )
+  }
+
   // MARK: - Interaction Stabilization
 
   func applyInteractionStabilizationIfNeeded() {
-    if needsPostSnapshotInteractionDelay {
-      sleepFor(postSnapshotInteractionDelay)
-      needsPostSnapshotInteractionDelay = false
-    }
     if needsFirstInteractionDelay {
       sleepFor(firstInteractionAfterActivateDelay)
       needsFirstInteractionDelay = false

package/drivers/ios/DevicelabIOSRunner/DevicelabIOSRunnerUITests/RunnerTests+Models.swift

@@ -57,6 +57,17 @@ enum CommandType: String, Codable {
   // Local extension: set the device's light/dark appearance. Takes
   // `appearance` as "dark" or "light".
   case setAppearance
+  // Local extension (DeviceDeck): wait, capped by `timeoutMs`, for the
+  // target app to go quiescent including animations — the check XCTest runs
+  // around every synthesized event, on demand. Read-only: it never
+  // activates the app. Returns `idle` and `waitedMs`.
+  case idle
+  // Local extension: wait, capped by `timeoutMs` (default 3000), until the
+  // screen stops changing — two consecutive small grayscale thumbnails of
+  // the screen agree. Maestro's static-screen test, done on the device so a
+  // settle costs one round trip. Never activates the app. Returns `idle`
+  // (true = settled) and `waitedMs`.
+  case settle
 }
 
 struct Command: Codable {
@@ -86,6 +97,10 @@ struct Command: Codable {
   // default drag velocity, which keeps the pre-existing swipe/scroll wire
   // shape byte-for-byte compatible.
   let moveDurationMs: Double?
+  // restMs — local extension for drag: how long the finger rests at the end
+  // point before lifting (Maestro's swipe shape). A short rest lets the
+  // content fling; a long one stops it where the swipe ends.
+  let restMs: Double?
   let direction: String?
   let orientation: String?
   let scale: Double?
@@ -97,17 +112,29 @@ struct Command: Codable {
   let depth: Int?
   let scope: String?
   let raw: Bool?
+  // visibleOnly — local extension for snapshot: serialize only elements at
+  // least 10% on screen (Maestro's filterOutOfBounds). The walk still covers
+  // the whole tree, but a web page's off-screen document stays on device.
+  let visibleOnly: Bool?
   let fullscreen: Bool?
   let mediaName: String?
   let mimeType: String?
   let mediaData: String?  // base64-encoded file bytes (addMedia)
   let appearance: String?  // "dark" or "light" (setAppearance)
+  let timeoutMs: Double?  // idle: the cap on the wait; absent = 1000, 0 = do not wait
+  // Local extension (eraseText): with an empty replace, delete this many
+  // characters from the end. Absent, or at least the field's length, clears
+  // the whole field.
+  let deleteCount: Int?
 }
 
 struct Response: Codable {
   let ok: Bool
   let data: DataPayload?
   let error: ErrorPayload?
+  // Time the runner spent executing the command, stamped by the transport,
+  // so the host can split a slow step into runner work and round trip.
+  var serverMs: Double?
 
   init(ok: Bool, data: DataPayload? = nil, error: ErrorPayload? = nil) {
     self.ok = ok
@@ -156,6 +183,30 @@ struct DataPayload: Codable {
   // this is the app's true state, which no signal in the node tree
   // reports reliably (hittable oscillates while a screen backgrounds).
   let appState: String?
+  // Local extension (DeviceDeck): the outcome of a type command's read-back.
+  // `verified` is true when the field's value read back as expected, false
+  // on a mismatch, and absent (null) when the value could not be read (a
+  // secure field, or an element that no longer resolves) — typing that was
+  // never checked is not reported as checked. `repaired` is true when the
+  // first attempt read back wrong and the runner cleared and retyped the
+  // field; the text on screen then came from the second attempt.
+  let verified: Bool?
+  let repaired: Bool?
+  // Local extension (DeviceDeck): which reader produced a snapshot's nodes —
+  // SnapshotSource.xctest (XCTest's public snapshot) or
+  // SnapshotSource.privateAX (the private accessibility client, used when
+  // the public path failed or came back with only the root on a deep React
+  // Native tree). The two differ in coverage and in how hittable is
+  // computed, so a caller comparing trees across snapshots needs to know.
+  let source: String?
+  // Local extension (DeviceDeck): the idle command's answer. `idle` is true
+  // only when XCTest reported the event loop idle and animations finished
+  // within the cap; false when the cap passed first, when the app is not in
+  // the foreground, when no wait was asked for, or when the quiescence API
+  // is missing — an unknown is never reported as idle. `waitedMs` is the
+  // time actually spent.
+  let idle: Bool?
+  let waitedMs: Double?
 
   init(
     message: String? = nil,
@@ -181,7 +232,12 @@ struct DataPayload: Codable {
     diffFraction: Double? = nil,
     identifier: String? = nil,
     appearance: String? = nil,
-    appState: String? = nil
+    appState: String? = nil,
+    verified: Bool? = nil,
+    repaired: Bool? = nil,
+    source: String? = nil,
+    idle: Bool? = nil,
+    waitedMs: Double? = nil
   ) {
     self.message = message
     self.text = text
@@ -207,9 +263,20 @@ struct DataPayload: Codable {
     self.identifier = identifier
     self.appearance = appearance
     self.appState = appState
+    self.verified = verified
+    self.repaired = repaired
+    self.source = source
+    self.idle = idle
+    self.waitedMs = waitedMs
   }
 }
 
+/// Values of DataPayload.source.
+enum SnapshotSource {
+  static let xctest = "xctest"
+  static let privateAX = "privateAX"
+}
+
 struct ErrorPayload: Codable {
   let code: String?
   let message: String
@@ -255,4 +322,10 @@ struct SnapshotOptions {
   let depth: Int?
   let scope: String?
   let raw: Bool
+  /// The caller named no app: the snapshot is of whatever is on screen, so
+  /// it may move to the app in front if the one chosen earlier has left it.
+  var followsScreen = false
+  /// Serialize only elements at least 10% on screen, as Maestro's
+  /// filterOutOfBounds does; the walk still visits the whole tree.
+  var visibleOnly = false
 }

package/drivers/ios/DevicelabIOSRunner/DevicelabIOSRunnerUITests/RunnerTests+Settle.swift

@@ -0,0 +1,89 @@
+import XCTest
+#if canImport(UIKit)
+import UIKit
+#endif
+
+// Screen settle: wait until the screen stops changing, the way Maestro's
+// iOS driver decides a screen is static (two consecutive identical
+// screenshots, 3s cap). The comparison runs on the device over small
+// grayscale thumbnails, so one settle is one round trip and each sample
+// costs a screen capture plus a ~5k-pixel compare — not two full PNGs
+// shipped to the host.
+extension RunnerTests {
+  static let settleDefaultTimeoutMs: Double = 3000
+  static let settleMaxTimeoutMs: Double = 10000
+  // Thumbnail size. Large enough that a list moving by a row or a sheet
+  // sliding in changes it; small enough that a blinking caret or a
+  // sub-pixel shimmer rarely does.
+  static let settleThumbWidth = 48
+  static let settleThumbHeight = 104
+  // A thumbnail pixel "differs" when it moves by more than this many gray
+  // levels, and the screen counts as still when at most this share of
+  // pixels differ.
+  static let settlePixelTolerance = 6
+  static let settleMaxDifferingShare = 0.002
+
+  func executeSettle(command: Command) -> Response {
+    let capMs = min(max(command.timeoutMs ?? Self.settleDefaultTimeoutMs, 0), Self.settleMaxTimeoutMs)
+    let started = CACurrentMediaTime()
+    var previous = settleThumbnail()
+    var settled = false
+    while (CACurrentMediaTime() - started) * 1000 < capMs {
+      let current = settleThumbnail()
+      if let prev = previous, let cur = current, thumbnailsMatch(prev, cur) {
+        settled = true
+        break
+      }
+      previous = current
+    }
+    let waitedMs = ((CACurrentMediaTime() - started) * 1000).rounded()
+    return Response(
+      ok: true,
+      data: DataPayload(
+        message: settled ? "settled" : "screen still changing at the cap",
+        idle: settled,
+        waitedMs: waitedMs
+      )
+    )
+  }
+
+  /// A small grayscale thumbnail of the whole screen, or nil when the
+  /// capture could not be drawn.
+  func settleThumbnail() -> [UInt8]? {
+    guard let image = runnerCGImage(from: XCUIScreen.main.screenshot().image) else {
+      return nil
+    }
+    let width = Self.settleThumbWidth
+    let height = Self.settleThumbHeight
+    var pixels = [UInt8](repeating: 0, count: width * height)
+    let drawn = pixels.withUnsafeMutableBytes { buffer -> Bool in
+      guard let context = CGContext(
+        data: buffer.baseAddress,
+        width: width,
+        height: height,
+        bitsPerComponent: 8,
+        bytesPerRow: width,
+        space: CGColorSpaceCreateDeviceGray(),
+        bitmapInfo: CGImageAlphaInfo.none.rawValue
+      ) else {
+        return false
+      }
+      context.interpolationQuality = .low
+      context.draw(image, in: CGRect(x: 0, y: 0, width: width, height: height))
+      return true
+    }
+    return drawn ? pixels : nil
+  }
+
+  /// Whether two thumbnails show the same still screen.
+  func thumbnailsMatch(_ a: [UInt8], _ b: [UInt8]) -> Bool {
+    guard a.count == b.count, !a.isEmpty else { return false }
+    let allowed = Int(Double(a.count) * Self.settleMaxDifferingShare)
+    var differing = 0
+    for i in 0..<a.count where abs(Int(a[i]) - Int(b[i])) > Self.settlePixelTolerance {
+      differing += 1
+      if differing > allowed { return false }
+    }
+    return true
+  }
+}