agent-device 0.21.0 → 0.21.2

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift

@@ -11,7 +11,10 @@ private struct RunnerUnsupportedOperationError: LocalizedError {
   var errorDescription: String? { message }
 }
 
-private enum RunnerInterfaceOrientation {
+enum RunnerInterfaceOrientation {
+
+
+
   static let portrait = 1
   static let portraitUpsideDown = 2
   static let landscapeRight = 3
@@ -191,11 +194,11 @@ extension RunnerTests {
     }
   }
 
-  // Maestro-compat gate for the non-hittable coordinate fallback: an element
-  // with no frame at all cannot be coordinate-tapped, otherwise the decision
-  // is the shared TapPointPolicy center-in-frame rule (golden parity table
-  // with the TS twin). app.frame is the frame source here — replay taps
-  // resolved bounds Maestro-style, so the union frame is intentional.
+
+
+
+
+
   private func hasTappableFrame(app: XCUIApplication, element: XCUIElement) -> Bool {
     let frame = element.frame
     if frame.isEmpty {
@@ -204,10 +207,10 @@ extension RunnerTests {
     return TapPointPolicy.isAllowed(elementFrame: frame, windowFrame: app.frame)
   }
 
-  // The tappable on-screen viewport. app.frame is unsuitable: it unions
-  // transformed subtrees, so a closed drawer at negative x inflates it and
-  // out-of-window coordinates still pass containment. Falls back to app.frame
-  // when no window frame is readable.
+
+
+
+
   func onScreenWindowFrame(app: XCUIApplication) -> CGRect {
     let window = app.windows.element(boundBy: 0)
     if window.exists {
@@ -220,11 +223,11 @@ extension RunnerTests {
   }
 
   func queryElement(app: XCUIApplication, selectorKey: String, selectorValue: String) -> Response {
-    // querySelector is a read — it backs get/is/wait and the offscreen-refusal
-    // double-check, none of which mutate. The fail-closed raw-match rule exists
-    // to stop a mutation acting on an unseen duplicate; applying it here would
-    // instead turn a decorative non-hittable duplicate into an AMBIGUOUS_MATCH
-    // for readers that previously resolved the hittable element.
+
+
+
+
+
     let match = findElement(
       app: app,
       selectorKey: selectorKey,
@@ -270,8 +273,8 @@ extension RunnerTests {
     )
   }
 
-  /// Shared ordering for point-hit candidates: smallest area wins, then top-to-bottom,
-  /// left-to-right, then stable element-type order for ties.
+
+
   func smallestElementFirst(_ left: XCUIElement, _ right: XCUIElement) -> Bool {
     let leftArea = max(1, left.frame.width * left.frame.height)
     let rightArea = max(1, right.frame.width * right.frame.height)
@@ -315,37 +318,6 @@ extension RunnerTests {
     return nil
   }
 
-  func textInputAt(app: XCUIApplication, x: Double, y: Double) -> XCUIElement? {
-    return textInputCandidatesAt(app: app, point: CGPoint(x: x, y: y)).first
-  }
-
-  private func textInputCandidatesAt(app: XCUIApplication, point: CGPoint) -> [XCUIElement] {
-    safely("TEXT_INPUT_AT_POINT", []) {
-      // Query the text-input element types directly instead of enumerating the entire tree
-      // (app.descendants(.any).allElementsBoundByIndex snapshots every element and is ~10x
-      // slower — it dominated fill latency because resolveTextEntryElement re-runs this on
-      // each verify/repair poll once the focused field reference goes stale).
-      // Prefer the smallest matching field so nested editable controls win over large containers.
-      [
-        app.textFields,
-        app.secureTextFields,
-        app.searchFields,
-        app.textViews,
-      ]
-        .flatMap { $0.allElementsBoundByIndex }
-        .filter { element in
-          guard element.exists else { return false }
-          let frame = element.frame
-          return isCoordinateTextInputCandidate(
-            enabled: element.isEnabled,
-            frame: frame,
-            point: point
-          )
-        }
-        .sorted(by: smallestElementFirst)
-    }
-  }
-
   private func readableText(for element: XCUIElement) -> String? {
     let label = element.label.trimmingCharacters(in: .whitespacesAndNewlines)
     let identifier = element.identifier.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -417,8 +389,8 @@ extension RunnerTests {
     let coordinate = interactionCoordinate(app: app, x: x, y: y)
     let interval = desktopScrollEventIntervalSeconds(durationMs: durationMs, eventCount: events.count)
     for (index, deltas) in events.enumerated() {
-      // Keep desktop scrolling on XCTest's coordinate API so macOS owns wheel synthesis, natural
-      // scrolling preference handling, and cursor placement instead of posting raw CGEvents.
+
+
       coordinate.scroll(
         byDeltaX: CGFloat(deltas.horizontal),
         deltaY: CGFloat(deltas.vertical)
@@ -513,7 +485,7 @@ extension RunnerTests {
     y2: Double,
     holdDuration: TimeInterval
   ) -> RunnerInteractionOutcome {
-    // tvOS has no coordinate drag. Preserve the direction as a focus move.
+
     let dx = x2 - x
     let dy = y2 - y
     let button: TvRemoteButton = abs(dx) > abs(dy)
@@ -525,9 +497,9 @@ extension RunnerTests {
     return performCoordinateDrag(app: app, x: x, y: y, x2: x2, y2: y2, holdDuration: holdDuration)
   }
 
-  /// Rotates an interface-oriented point into the device-native (portrait) space the
-  /// synthesized event path consumes — synthesized events skip XCTest's orientation
-  /// handling, so without this a landscape tap lands in the wrong place.
+
+
+
   func nativeSynthesizedPoint(
     orientedX x: Double,
     orientedY y: Double,
@@ -545,13 +517,13 @@ extension RunnerTests {
       return CGPoint(x: localY, y: width - localX)
     case RunnerInterfaceOrientation.portraitUpsideDown:
       return CGPoint(x: width - localX, y: height - localY)
-    default:  // portrait or unknown
+    default:
       return CGPoint(x: localX, y: localY)
     }
   }
 
-  /// Rotates an interface-oriented translation vector into the same native
-  /// coordinate space as `nativeSynthesizedPoint`.
+
+
   func nativeSynthesizedVector(
     orientedDx dx: Double,
     orientedDy dy: Double,
@@ -564,7 +536,7 @@ extension RunnerTests {
       return CGVector(dx: dy, dy: -dx)
     case RunnerInterfaceOrientation.portraitUpsideDown:
       return CGVector(dx: -dx, dy: -dy)
-    default:  // portrait or unknown
+    default:
       return CGVector(dx: dx, dy: dy)
     }
   }
@@ -910,8 +882,8 @@ extension RunnerTests {
     screenshotSize: CGSize,
     interfaceOrientation: Int
   ) -> CGRect? {
-    // Physical iOS screenshots can retain portrait dimensions after the interface rotates,
-    // while accessibility frames remain in the logical landscape coordinate space.
+
+
     guard screenshotSize.width.isFinite, screenshotSize.height.isFinite,
       screenshotSize.width > 0,
       screenshotSize.height > 0
@@ -937,18 +909,6 @@ extension RunnerTests {
     return CGRect(x: 0, y: 0, width: width, height: height)
   }
 
-  func synthesizedFrameAvoidingKeyboardWhenAllowed(
-    app: XCUIApplication,
-    context: SynthesizedCoordinateContext
-  ) -> CGRect {
-#if os(iOS)
-    guard context.allowsKeyboardProbe else { return context.referenceFrame }
-    return frameAvoidingKeyboard(app: app, frame: context.referenceFrame)
-#else
-    return context.referenceFrame
-#endif
-  }
-
   func keyboardAvoidingSynthesizedDragPoints(
     app: XCUIApplication,
     x: Double,
@@ -1085,8 +1045,8 @@ extension RunnerTests {
   ) -> RunnerInteractionOutcome {
 #if os(iOS)
     let orientation = Int(RunnerSynthesizedGesture.interfaceOrientation(forApplication: app))
-    // The portable planner and validation use this exact viewport. Using app.frame here can
-    // diverge when XCTest unions transformed/off-screen descendants into the application frame.
+
+
     let frame = CGRect(
       x: plan.viewport.x,
       y: plan.viewport.y,
@@ -1217,4 +1177,220 @@ extension RunnerTests {
   }
 #endif
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 }

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Keyboard.swift

@@ -2,30 +2,30 @@ import XCTest
 
 private enum KeyboardDismissObservationTiming {
   static let timeout: TimeInterval = 2
-  // #1542: dismissing the keyboard can trigger the host app's own content-offset
-  // adjustment (e.g. a ScrollView correcting the inset it grew to keep a focused
-  // field above the keyboard). That adjustment is a separate, unsynchronized
-  // animation the keyboard's own `waitForNonExistence` above knows nothing about:
-  // the keyboard AX element can vanish well before the app settles. The very next
-  // command is frequently a synthesized, AX-free drag (scroll/gesture — kept
-  // AX-free so it still works under #1105-family AX degradation), which has no
-  // XCTest quiescence wait of its own, so it can land mid-animation and net to
-  // zero. These bounds cap the settle wait this trades in.
-  // A spring-driven content-offset correction can pass through a near-zero-
-  // velocity inflection (the top of an overshoot) that two adjacent samples
-  // alone cannot distinguish from true rest. Requiring 3 consecutive matching
-  // samples demands ~2 full sample intervals of actual stillness before
-  // stopping early, so a momentary pause mid-animation cannot look settled.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
   static let settleTimeout: TimeInterval = 2.0
   static let settleSampleInterval: TimeInterval = 0.15
   static let settleRequiredConsecutiveMatches: Int = 3
 }
 
-// The mechanism that actually resigned the keyboard, disclosed to the caller
-// (#1598) so a response never claims "dismissed" without saying how — a
-// safe-area tap has a very different reliability/side-effect profile than
-// tapping the keyboard's own Done key, and callers need to know which one
-// fired.
+
+
+
+
+
 enum RunnerKeyboardDismissMechanism: String {
   case dismissKey
 }
@@ -61,25 +61,25 @@ extension RunnerTests {
       return (wasVisible: true, dismissed: !visible, visible: visible, mechanism: visible ? nil : .dismissKey)
     }
 
-    // #1606 review P1 (twice): generic background-tap dismissal is
-    // deliberately UNSUPPORTED. No geometry or role query can prove a
-    // coordinate is side-effect-free — a full-screen unlabeled Pressable is
-    // indistinguishable from an inert backdrop, so a "safe-area" tap can
-    // navigate or submit while reporting a successful dismiss. The dismiss
-    // key is the only mechanism the runner can vouch for.
+
+
+
+
+
+
     return (wasVisible: true, dismissed: false, visible: isKeyboardVisible(app: app), mechanism: nil)
 #endif
   }
 
 
-  // AX-free on purpose (screenshot bytes, not the accessibility tree) so it holds
-  // under the same AX degradation the synthesized gesture lane is built to survive.
-  // Bounded and self-terminating: returns as soon as `requiredConsecutiveMatches`
-  // consecutive samples match, so an already-settled screen (the common case)
-  // pays close to nothing. The stopping decision itself
-  // (`runnerScreenshotStabilitySettled`) is a pure function of the samples taken
-  // so far, so it is unit-testable without a real screenshot pipeline; this loop
-  // is the thin, untestable I/O shell around it.
+
+
+
+
+
+
+
+
   private func waitForScreenshotStability(
     timeout: TimeInterval,
     sampleInterval: TimeInterval,
@@ -252,15 +252,15 @@ extension RunnerTests {
   }
 }
 
-/// True once the `requiredConsecutiveMatches` most recent samples are all present
-/// and byte-identical — i.e. the screen held still across that whole run of
-/// polls, not just the last two. A spring-driven content-offset correction can
-/// pass through a near-zero-velocity inflection that two adjacent samples alone
-/// cannot distinguish from true rest; requiring a longer run of matches demands
-/// real elapsed stillness before stopping early. `nil` entries (a screenshot
-/// capture that failed) never count toward a match, so a flaky capture cannot
-/// look like stability; the caller's bounded loop still terminates on its
-/// deadline regardless.
+
+
+
+
+
+
+
+
+
 func runnerScreenshotStabilitySettled(
   _ samples: [Data?],
   requiredConsecutiveMatches: Int
@@ -273,3 +273,62 @@ func runnerScreenshotStabilitySettled(
   return window.allSatisfy { $0 == firstData }
 }
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift

@@ -22,7 +22,7 @@ func runnerCGImage(from image: RunnerImage) -> CGImage? {
 }
 
 extension RunnerTests {
-  // MARK: - Recording
+
 
   func captureRunnerFrame() -> RunnerImage? {
     var image: RunnerImage?
@@ -70,7 +70,7 @@ extension RunnerTests {
     return (NSTemporaryDirectory() as NSString).appendingPathComponent(safeFileName)
   }
 
-  // MARK: - Target Activation
+
 
   func ensureRunnerHostAppActive(reason: String) {
     NSLog(
@@ -103,9 +103,9 @@ extension RunnerTests {
 
   func resetTargetAfterExternalRelaunch() -> Response {
     invalidateCachedTarget(reason: "external_app_relaunch")
-    // The app process is replaced, but the retained runner survives. Clear
-    // process-bound capture state explicitly because invalidation drops the
-    // old PID before refreshCachedTargetIfProcessChanged can observe it.
+
+
+
     clearSnapshotXCTestChannelPenalty(reason: "external_app_relaunch")
     clearPrivateAXAcceptedDepth(reason: "external_app_relaunch")
     beginFirstInteractionStabilization()
@@ -191,7 +191,7 @@ extension RunnerTests {
       initialState.rawValue,
       reason
     )
-    // activate avoids terminating and relaunching the target app
+
     if initialState == .runningForeground {
       NSLog(
         "AGENT_DEVICE_RUNNER_ACTIVATE_SKIPPED bundle=%@ reason=already_foreground",
@@ -229,7 +229,7 @@ extension RunnerTests {
     performWithQuiescenceSkippedIfSupported(target, operation: operation)
   }
 
-  // Some apps never report post-gesture quiescence, even after XCTest has synthesized the event.
+
   private func performWithQuiescenceSkippedIfSupported(
     _ target: XCUIApplication,
     operation: () -> Void
@@ -285,7 +285,7 @@ extension RunnerTests {
     return false
   }
 
-  // MARK: - Command Classification
+
 
   func isReadOnlyCommand(_ command: Command) -> Bool {
     switch command.command.traits.readOnly {
@@ -294,7 +294,7 @@ extension RunnerTests {
     case .never:
       return false
     case .conditional:
-      // Today only `alert` is conditional: read-only when getting, mutating otherwise.
+
       return (command.action ?? "get").lowercased() == "get"
     }
   }
@@ -313,7 +313,7 @@ extension RunnerTests {
     return command.traits.isLifecycle
   }
 
-  // MARK: - Interaction Stabilization
+
 
   func applyInteractionStabilizationIfNeeded() {
     if needsPostSnapshotInteractionDelay {
@@ -326,8 +326,8 @@ extension RunnerTests {
     }
   }
 
-  /// Start the post-activation settling window. Measured from now, so the time the caller spends
-  /// getting back to us counts towards it instead of being charged twice.
+
+
   func beginFirstInteractionStabilization() {
     firstInteractionReadyUptime =
       ProcessInfo.processInfo.systemUptime + firstInteractionAfterActivateDelay
@@ -335,7 +335,7 @@ extension RunnerTests {
 
   func sleepFor(_ delay: TimeInterval) {
     guard delay > 0 else { return }
-    // Keep XCTest/UI sources moving during command-local pauses such as delayed typing.
+
     if Thread.isMainThread {
       let deadline = Date().addingTimeInterval(delay)
       while Date() < deadline {