agent-device 0.16.14 → 0.17.0

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.h

@@ -21,6 +21,10 @@ NS_ASSUME_NONNULL_BEGIN
                                                    y2:(double)y2
                                             durationMs:(double)durationMs;
 
++ (NSString * _Nullable)synthesizeTapWithApplication:(id)application
+                                                   x:(double)x
+                                                   y:(double)y;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.m

@@ -53,6 +53,10 @@ static id RunnerSwipePointerPath(
   CGPoint end,
   double durationMs
 );
+static id RunnerTapPointerPath(
+  const RunnerXCTestEventBridge *bridge,
+  CGPoint point
+);
 static CGPoint RunnerPointerPointAt(
   double x,
   double y,
@@ -115,6 +119,18 @@ static double RunnerSmoothStep(double t);
   }
 }
 
++ (NSString * _Nullable)synthesizeTapWithApplication:(id)application
+                                                   x:(double)x
+                                                   y:(double)y {
+  @try {
+    return [self trySynthesizeTapWithApplication:application x:x y:y];
+  } @catch (NSException *exception) {
+    NSString *name = exception.name ?: @"NSException";
+    NSString *reason = exception.reason ?: @"private XCTest event synthesis failed";
+    return [NSString stringWithFormat:@"%@: %@", name, reason];
+  }
+}
+
 + (NSString * _Nullable)trySynthesizeTransformWithApplication:(id)application
                                                             x:(double)x
                                                             y:(double)y
@@ -224,6 +240,48 @@ static double RunnerSmoothStep(double t);
   return nil;
 }
 
++ (NSString * _Nullable)trySynthesizeTapWithApplication:(id)application
+                                                      x:(double)x
+                                                      y:(double)y {
+  RunnerXCTestEventBridge bridge;
+  NSString *missing = RunnerResolveXCTestEventBridge(application, &bridge);
+  if (missing != nil) {
+    return missing;
+  }
+
+  NSInteger interfaceOrientation =
+    ((RunnerMsgSendInteger)objc_msgSend)(application, bridge.interfaceOrientationSelector);
+  NSInteger targetProcessID = ((RunnerMsgSendInteger)objc_msgSend)(application, bridge.processIDSelector);
+  if (targetProcessID <= 0) {
+    return @"private XCTest event synthesis unavailable: could not resolve target process ID";
+  }
+
+  id record = ((RunnerMsgSendInitRecord)objc_msgSend)(
+    [bridge.recordClass alloc],
+    bridge.initRecordSelector,
+    @"agent-device-tap",
+    interfaceOrientation
+  );
+  if (record == nil) {
+    return @"private XCTest event synthesis failed: could not create event record";
+  }
+  ((RunnerMsgSendSetInteger)objc_msgSend)(record, bridge.setTargetProcessIDSelector, targetProcessID);
+
+  id path = RunnerTapPointerPath(&bridge, CGPointMake(x, y));
+  if (path == nil) {
+    return @"private XCTest event synthesis failed: could not create pointer path";
+  }
+  ((RunnerMsgSendAddPath)objc_msgSend)(record, bridge.addPathSelector, path);
+
+  NSError *error = nil;
+  BOOL ok = ((RunnerMsgSendSynthesize)objc_msgSend)(record, bridge.synthesizeSelector, &error);
+  if (!ok) {
+    NSString *detail = error.localizedDescription ?: @"synthesizeWithError returned false";
+    return [NSString stringWithFormat:@"private XCTest event synthesis failed: %@", detail];
+  }
+  return nil;
+}
+
 static NSString * _Nullable RunnerResolveXCTestEventBridge(
   id application,
   RunnerXCTestEventBridge *bridge
@@ -368,6 +426,19 @@ static id RunnerSwipePointerPath(
   return path;
 }
 
+static id RunnerTapPointerPath(
+  const RunnerXCTestEventBridge *bridge,
+  CGPoint point
+) {
+  id path =
+    ((RunnerMsgSendInitPath)objc_msgSend)([bridge->pathClass alloc], bridge->initPathSelector, point, 0.0);
+  if (path == nil) {
+    return nil;
+  }
+  ((RunnerMsgSendPathOffset)objc_msgSend)(path, bridge->liftSelector, 0.05);
+  return path;
+}
+
 static CGPoint RunnerPointerPointAt(
   double x,
   double y,

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Alert.swift

@@ -8,20 +8,18 @@ extension RunnerTests {
   }
 
   func resolveAlert(app activeApp: XCUIApplication) -> RunnerAlert? {
+#if !os(macOS)
+    if let systemModal = firstBlockingSystemModal(in: springboard) {
+      return runnerAlert(root: systemModal, ownerApp: springboard)
+    }
+#endif
     if let alert = firstExistingElement(in: activeApp.alerts.allElementsBoundByIndex) {
       return runnerAlert(root: alert, ownerApp: activeApp)
     }
     if let popup = firstDismissPopupWindow(in: activeApp) {
       return runnerAlert(root: popup, ownerApp: activeApp)
     }
-#if os(macOS)
-    return nil
-#else
-    if let systemModal = firstBlockingSystemModal(in: springboard) {
-      return runnerAlert(root: systemModal, ownerApp: springboard)
-    }
     return nil
-#endif
   }
 
   func handleAlert(_ alert: RunnerAlert, action: String) -> Response {
@@ -33,6 +31,27 @@ extension RunnerTests {
       if let response = unsupportedResponse(for: outcome) {
         return response
       }
+      sleepFor(0.2)
+      if alertStillVisible(alert, actionButtonLabel: button.label) {
+        let frame = button.frame
+        if !frame.isNull && !frame.isEmpty {
+          let coordinateOutcome = tapAt(app: alert.ownerApp, x: frame.midX, y: frame.midY)
+          if let response = unsupportedResponse(for: coordinateOutcome) {
+            return response
+          }
+          sleepFor(0.2)
+        }
+      }
+      if alertStillVisible(alert, actionButtonLabel: button.label) {
+        return Response(
+          ok: false,
+          error: ErrorPayload(
+            code: "INTERACTION_FAILED",
+            message: "alert \(action) did not dismiss the visible alert",
+            hint: "The alert button was found but the system still reports the alert after tapping it."
+          )
+        )
+      }
       return Response(ok: true, data: DataPayload(message: action == "accept" ? "accepted" : "dismissed"))
     }
 
@@ -53,6 +72,21 @@ extension RunnerTests {
     return RunnerAlert(root: root, ownerApp: ownerApp, buttons: buttons)
   }
 
+  private func alertStillVisible(_ alert: RunnerAlert, actionButtonLabel: String) -> Bool {
+    guard let current = resolveAlert(app: alert.ownerApp) else {
+      return false
+    }
+    let previousTitle = preferredAlertTitle(alert.root, buttons: alert.buttons)
+    let currentTitle = preferredAlertTitle(current.root, buttons: current.buttons)
+    if previousTitle == currentTitle {
+      return true
+    }
+    let normalizedActionLabel = actionButtonLabel.trimmingCharacters(in: .whitespacesAndNewlines)
+    return current.buttons.contains { button in
+      button.label.trimmingCharacters(in: .whitespacesAndNewlines) == normalizedActionLabel
+    }
+  }
+
   private func firstExistingElement(in elements: [XCUIElement]) -> XCUIElement? {
     elements.first { isVisibleElement($0) }
   }

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift

@@ -147,10 +147,64 @@ extension RunnerTests {
     return Response(ok: true, data: data)
   }
 
+  func testGestureResponseIncludesSynthesizedTapFallbackDiagnostics() {
+    let response = gestureResponse(
+      message: "tapped",
+      timing: (gestureStartUptimeMs: 1, gestureEndUptimeMs: 2),
+      fallback: GestureFallback(
+        strategy: "xctest-coordinate-tap",
+        message: "Runner synthesized coordinate tap is unavailable",
+        hint: "Using XCTest coordinate tap fallback."
+      )
+    )
+
+    XCTAssertEqual(response.ok, true)
+    XCTAssertEqual(response.data?.gestureFallback, "xctest-coordinate-tap")
+    XCTAssertEqual(
+      response.data?.gestureFallbackMessage,
+      "Runner synthesized coordinate tap is unavailable"
+    )
+    XCTAssertEqual(response.data?.gestureFallbackHint, "Using XCTest coordinate tap fallback.")
+  }
+
+  func testXCTestRecordedFailureResponseFailsMutatingSuccesses() throws {
+    let command = try runnerCommandFixture(#"{"command":"tap","commandId":"tap-1"}"#)
+    let response = Response(ok: true, data: DataPayload(message: "tapped"))
+
+    let failureResponse = xctestRecordedFailureResponse(command: command, response: response)
+
+    XCTAssertEqual(failureResponse?.ok, false)
+    XCTAssertEqual(failureResponse?.error?.code, "XCTEST_RECORDED_FAILURE")
+    XCTAssertEqual(
+      failureResponse?.error?.message,
+      "XCTest recorded a failure while executing tap; the action may not have been performed."
+    )
+  }
+
+  func testXCTestRecordedFailureResponseDoesNotWrapReadOnlyOrRunnerFatalResponses() throws {
+    let snapshotCommand = try runnerCommandFixture(#"{"command":"snapshot","commandId":"snapshot-1"}"#)
+    let tapCommand = try runnerCommandFixture(#"{"command":"tap","commandId":"tap-1"}"#)
+    let runnerFatalResponse = Response(
+      ok: true,
+      data: DataPayload(runnerFatal: true, runnerFatalReason: "ax_snapshot_unavailable")
+    )
+
+    XCTAssertNil(
+      xctestRecordedFailureResponse(
+        command: snapshotCommand,
+        response: Response(ok: true, data: DataPayload(nodes: [], truncated: false))
+      )
+    )
+    XCTAssertNil(xctestRecordedFailureResponse(command: tapCommand, response: runnerFatalResponse))
+  }
+
   func execute(command: Command) throws -> Response {
     if command.command == .status {
       return executeStatus(command: command)
     }
+    if command.command == .uptime {
+      return executeUptime()
+    }
     commandJournal.accept(command: command)
     return try executeAccepted(command: command)
   }
@@ -185,6 +239,13 @@ extension RunnerTests {
     return Response(ok: true, data: commandJournal.status(commandId: statusCommandId))
   }
 
+  func executeUptime() -> Response {
+    Response(
+      ok: true,
+      data: DataPayload(currentUptimeMs: currentUptimeMs())
+    )
+  }
+
   private func executeDispatched(command: Command) throws -> Response {
     if Thread.isMainThread {
       return try executeOnMainSafely(command: command)
@@ -229,6 +290,7 @@ extension RunnerTests {
     while true {
       var response: Response?
       var swiftError: Error?
+      let failureCountBefore = currentXCTestFailureCount()
       let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
         do {
           response = try self.executeOnMain(command: command)
@@ -238,8 +300,7 @@ extension RunnerTests {
       })
 
       if let exceptionMessage {
-        currentApp = nil
-        currentBundleId = nil
+        invalidateCachedTarget(reason: "objc_exception")
         if !hasRetried, shouldRetryException(command, message: exceptionMessage) {
           NSLog(
             "AGENT_DEVICE_RUNNER_RETRY command=%@ reason=objc_exception",
@@ -265,14 +326,19 @@ extension RunnerTests {
           userInfo: [NSLocalizedDescriptionKey: "command returned no response"]
         )
       }
+      if didRecordXCTestFailure(since: failureCountBefore),
+        let failureResponse = xctestRecordedFailureResponse(command: command, response: response)
+      {
+        invalidateCachedTarget(reason: "xctest_recorded_failure")
+        return failureResponse
+      }
       if !hasRetried, shouldRetryCommand(command), shouldRetryResponse(response) {
         NSLog(
           "AGENT_DEVICE_RUNNER_RETRY command=%@ reason=response_unavailable",
           command.command.rawValue
         )
         hasRetried = true
-        currentApp = nil
-        currentBundleId = nil
+        invalidateCachedTarget(reason: "response_unavailable")
         sleepFor(retryCooldown)
         continue
       }
@@ -282,7 +348,9 @@ extension RunnerTests {
 
   private func executeOnMain(command: Command) throws -> Response {
     var activeApp = currentApp ?? app
-    if !isRunnerLifecycleCommand(command.command) {
+    if shouldSkipAppActivationPreflight(command) {
+      activeApp = resolveAppWithoutActivation(command: command)
+    } else if !isRunnerLifecycleCommand(command.command) {
       let normalizedBundleId = command.appBundleId?
         .trimmingCharacters(in: .whitespacesAndNewlines)
       let requestedBundleId = (normalizedBundleId?.isEmpty == true) ? nil : normalizedBundleId
@@ -408,10 +476,7 @@ extension RunnerTests {
         return Response(ok: false, error: ErrorPayload(message: "failed to stop recording: \(error.localizedDescription)"))
       }
     case .uptime:
-      return Response(
-        ok: true,
-        data: DataPayload(currentUptimeMs: currentUptimeMs())
-      )
+      return executeUptime()
     case .tap:
       if let selectorKey = command.selectorKey, let selectorValue = command.selectorValue {
         let match = findElement(
@@ -425,6 +490,7 @@ extension RunnerTests {
         }
         if let element = match.element {
           let frame = element.frame
+          let isTextEntry = isTextEntryElement(element)
           let touchFrame = frame.isEmpty
             ? nil
             : resolvedTouchVisualizationFrame(app: activeApp, x: frame.midX, y: frame.midY)
@@ -440,7 +506,9 @@ extension RunnerTests {
           if let response = unsupportedResponse(for: outcome) {
             return response
           }
-          waitForTextEntryReadinessAfterTap(app: activeApp, element: element)
+          if isTextEntry {
+            waitForTextEntryReadinessAfterTap(app: activeApp, element: element)
+          }
           return gestureResponse(
             message: match.usedNonHittableFallback ? "tapped via non-hittable coordinate fallback" : "tapped",
             timing: timing,
@@ -462,12 +530,27 @@ extension RunnerTests {
         return Response(ok: false, error: ErrorPayload(message: "element not found"))
       }
       if let x = command.x, let y = command.y {
+        var fallback: GestureFallback?
+        if command.synthesized == true {
+          let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
+            synthesizedTapAt(app: activeApp, x: x, y: y)
+          }
+          if case .performed = outcome {
+            return gestureResponse(message: "tapped", timing: timing)
+          }
+          fallback = gestureFallback(strategy: "xctest-coordinate-tap", from: outcome)
+        }
         let touchFrame = resolvedTouchVisualizationFrame(app: activeApp, x: x, y: y)
         let (timing, outcome) = performGesture(activeApp) { tapAt(app: activeApp, x: x, y: y) }
         if let response = unsupportedResponse(for: outcome) {
           return response
         }
-        return gestureResponse(message: "tapped", timing: timing, frame: .touch(touchFrame))
+        return gestureResponse(
+          message: "tapped",
+          timing: timing,
+          frame: .touch(touchFrame),
+          fallback: fallback
+        )
       }
       return Response(ok: false, error: ErrorPayload(message: "tap requires text or x/y"))
     case .mouseClick:
@@ -736,6 +819,7 @@ extension RunnerTests {
         needsPostSnapshotInteractionDelay = true
         return Response(ok: true, data: payload)
       } catch let failure as SnapshotCaptureFailure {
+        invalidateCachedTarget(reason: "ax_snapshot_failure")
         // Other thrown errors fall through to executeOnMainSafely's generic error response.
         return Response(
           ok: false,
@@ -935,6 +1019,65 @@ extension RunnerTests {
     }
   }
 
+  private func currentXCTestFailureCount() -> Int {
+    return testRun?.failureCount ?? 0
+  }
+
+  private func didRecordXCTestFailure(since failureCountBefore: Int) -> Bool {
+    return currentXCTestFailureCount() > failureCountBefore
+  }
+
+  private func xctestRecordedFailureResponse(command: Command, response: Response) -> Response? {
+    guard response.ok else { return nil }
+    if response.data?.runnerFatal == true {
+      return nil
+    }
+    guard !isReadOnlyCommand(command), !isRunnerLifecycleCommand(command.command) else {
+      return nil
+    }
+    return Response(
+      ok: false,
+      error: ErrorPayload(
+        code: "XCTEST_RECORDED_FAILURE",
+        message: "XCTest recorded a failure while executing \(command.command.rawValue); the action may not have been performed.",
+        hint: "The iOS runner session will be restarted. Retry after a fresh snapshot, or use screenshot plus coordinate commands when the accessibility tree is unavailable."
+      )
+    )
+  }
+
+  private func runnerCommandFixture(_ json: String) throws -> Command {
+    try JSONDecoder().decode(Command.self, from: Data(json.utf8))
+  }
+
+  private func shouldSkipAppActivationPreflight(_ command: Command) -> Bool {
+#if os(iOS)
+    // Coordinate-only synthesized taps can run after an AX-fatal screen because they do not need
+    // app activation, window lookup, keyboard lookup, or element resolution. Selector/text taps
+    // intentionally stay on the normal AX path because they need an element query.
+    return command.command == .tap
+      && command.synthesized == true
+      && command.x != nil
+      && command.y != nil
+      && command.text == nil
+      && command.selectorKey == nil
+#else
+    return false
+#endif
+  }
+
+  private func resolveAppWithoutActivation(command: Command) -> XCUIApplication {
+    guard let bundleId = command.appBundleId?
+      .trimmingCharacters(in: .whitespacesAndNewlines),
+      !bundleId.isEmpty
+    else {
+      return currentApp ?? app
+    }
+    if currentBundleId == bundleId, let currentApp {
+      return currentApp
+    }
+    return XCUIApplication(bundleIdentifier: bundleId)
+  }
+
   private func executeTypeCommand(activeApp: XCUIApplication, command: Command) -> Response {
     guard let text = command.text else {
       return Response(ok: false, error: ErrorPayload(message: "type requires text"))

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandJournal.swift

@@ -154,6 +154,17 @@ final class RunnerCommandJournal {
 }
 
 extension RunnerTests {
+  func testUptimeBypassesCommandJournal() throws {
+    let command = runnerJournalCommand("uptime", id: "uptime-probe")
+
+    let response = try execute(command: command)
+    let status = commandJournal.status(commandId: "uptime-probe")
+
+    XCTAssertEqual(response.ok, true)
+    XCTAssertNotNil(response.data?.currentUptimeMs)
+    XCTAssertEqual(status.lifecycleState, RunnerCommandLifecycleState.notAccepted.rawValue)
+  }
+
   func testCommandJournalRetentionPolicy() throws {
     let journal = RunnerCommandJournal()
 

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Exceptions.swift

@@ -10,10 +10,7 @@ extension RunnerTests {
   /// exception telemetry later. `RunnerObjCExceptionCatcher.catchException` takes a non-escaping
   /// block, so `block` may capture `inout` state.
   func safely<T>(_ tag: String, _ fallback: T, _ block: () -> T) -> T {
-    var result = fallback
-    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
-      result = block()
-    })
+    let (result, exceptionMessage) = catchingObjCException(fallback: fallback, block)
     if let exceptionMessage {
       NSLog("AGENT_DEVICE_RUNNER_%@_IGNORED_EXCEPTION=%@", tag, exceptionMessage)
       return fallback
@@ -21,6 +18,17 @@ extension RunnerTests {
     return result
   }
 
+  func catchingObjCException<T>(
+    fallback: T,
+    _ block: () -> T
+  ) -> (result: T, exceptionMessage: String?) {
+    var result = fallback
+    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
+      result = block()
+    })
+    return (result, exceptionMessage)
+  }
+
   /// Optional-returning convenience: returns `nil` on exception (matching the common
   /// `var x: T?` + catch-and-return-nil shape).
   func safely<T>(_ tag: String, _ block: () -> T?) -> T? {

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift

@@ -670,6 +670,32 @@ extension RunnerTests {
 #endif
   }
 
+  func synthesizedTapAt(app: XCUIApplication, x: Double, y: Double) -> RunnerInteractionOutcome {
+#if os(iOS)
+    if let message = RunnerSynthesizedGesture.synthesizeTap(
+      withApplication: app,
+      x: x,
+      y: y
+    ) {
+      return .unsupported(
+        message: message,
+        hint: "Falling back to XCTest coordinate tap may be slower and can still need a healthy accessibility tree."
+      )
+    }
+    return .performed
+#elseif os(tvOS)
+    return .unsupported(
+      message: "coordinate tap is not supported on tvOS; move focus with swipe or scroll, then select the focused element",
+      hint: "tvOS has no coordinate input; move focus with swipe/scroll to the target, then select it."
+    )
+#else
+    return .unsupported(
+      message: "synthesized coordinate tap is not supported on macOS",
+      hint: "macOS automation has no touchscreen; use mouse-driven interactions instead."
+    )
+#endif
+  }
+
   func keyboardAvoidingDragPoints(
     app: XCUIApplication,
     x: Double,

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift

@@ -87,6 +87,14 @@ extension RunnerTests {
     currentBundleId = nil
   }
 
+  func invalidateCachedTarget(reason: String) {
+    if currentApp != nil || currentBundleId != nil {
+      NSLog("AGENT_DEVICE_RUNNER_TARGET_CACHE_INVALIDATE reason=%@", reason)
+    }
+    currentApp = nil
+    currentBundleId = nil
+  }
+
   func targetNeedsActivation(_ target: XCUIApplication) -> Bool {
     let state = target.state
 #if os(macOS)

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift

@@ -193,6 +193,8 @@ struct DataPayload: Codable {
   let gestureFallback: String?
   let gestureFallbackMessage: String?
   let gestureFallbackHint: String?
+  let runnerFatal: Bool?
+  let runnerFatalReason: String?
 
   init(
     message: String? = nil,
@@ -224,7 +226,9 @@ struct DataPayload: Codable {
     orientation: String? = nil,
     gestureFallback: String? = nil,
     gestureFallbackMessage: String? = nil,
-    gestureFallbackHint: String? = nil
+    gestureFallbackHint: String? = nil,
+    runnerFatal: Bool? = nil,
+    runnerFatalReason: String? = nil
   ) {
     self.message = message
     self.text = text
@@ -256,6 +260,8 @@ struct DataPayload: Codable {
     self.gestureFallback = gestureFallback
     self.gestureFallbackMessage = gestureFallbackMessage
     self.gestureFallbackHint = gestureFallbackHint
+    self.runnerFatal = runnerFatal
+    self.runnerFatalReason = runnerFatalReason
   }
 }