agent-device 0.7.4 → 0.7.5

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

@@ -0,0 +1,381 @@
+import XCTest
+
+extension RunnerTests {
+  // MARK: - Main Thread Dispatch
+
+  func execute(command: Command) throws -> Response {
+    if Thread.isMainThread {
+      return try executeOnMainSafely(command: command)
+    }
+    var result: Result<Response, Error>?
+    let semaphore = DispatchSemaphore(value: 0)
+    DispatchQueue.main.async {
+      do {
+        result = .success(try self.executeOnMainSafely(command: command))
+      } catch {
+        result = .failure(error)
+      }
+      semaphore.signal()
+    }
+    let waitResult = semaphore.wait(timeout: .now() + mainThreadExecutionTimeout)
+    if waitResult == .timedOut {
+      // The main queue work may still be running; we stop waiting and report timeout.
+      throw NSError(
+        domain: RunnerErrorDomain.general,
+        code: RunnerErrorCode.mainThreadExecutionTimedOut,
+        userInfo: [NSLocalizedDescriptionKey: "main thread execution timed out"]
+      )
+    }
+    switch result {
+    case .success(let response):
+      return response
+    case .failure(let error):
+      throw error
+    case .none:
+      throw NSError(
+        domain: RunnerErrorDomain.general,
+        code: RunnerErrorCode.noResponseFromMainThread,
+        userInfo: [NSLocalizedDescriptionKey: "no response from main thread"]
+      )
+    }
+  }
+
+  // MARK: - Command Handling
+
+  private func executeOnMainSafely(command: Command) throws -> Response {
+    var hasRetried = false
+    while true {
+      var response: Response?
+      var swiftError: Error?
+      let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
+        do {
+          response = try self.executeOnMain(command: command)
+        } catch {
+          swiftError = error
+        }
+      })
+
+      if let exceptionMessage {
+        currentApp = nil
+        currentBundleId = nil
+        if !hasRetried, shouldRetryException(command, message: exceptionMessage) {
+          NSLog(
+            "AGENT_DEVICE_RUNNER_RETRY command=%@ reason=objc_exception",
+            command.command.rawValue
+          )
+          hasRetried = true
+          sleepFor(retryCooldown)
+          continue
+        }
+        throw NSError(
+          domain: RunnerErrorDomain.exception,
+          code: RunnerErrorCode.objcException,
+          userInfo: [NSLocalizedDescriptionKey: exceptionMessage]
+        )
+      }
+      if let swiftError {
+        throw swiftError
+      }
+      guard let response else {
+        throw NSError(
+          domain: RunnerErrorDomain.general,
+          code: RunnerErrorCode.commandReturnedNoResponse,
+          userInfo: [NSLocalizedDescriptionKey: "command returned no response"]
+        )
+      }
+      if !hasRetried, shouldRetryCommand(command), shouldRetryResponse(response) {
+        NSLog(
+          "AGENT_DEVICE_RUNNER_RETRY command=%@ reason=response_unavailable",
+          command.command.rawValue
+        )
+        hasRetried = true
+        currentApp = nil
+        currentBundleId = nil
+        sleepFor(retryCooldown)
+        continue
+      }
+      return response
+    }
+  }
+
+  private func executeOnMain(command: Command) throws -> Response {
+    var activeApp = currentApp ?? app
+    if !isRunnerLifecycleCommand(command.command) {
+      let normalizedBundleId = command.appBundleId?
+        .trimmingCharacters(in: .whitespacesAndNewlines)
+      let requestedBundleId = (normalizedBundleId?.isEmpty == true) ? nil : normalizedBundleId
+      if let bundleId = requestedBundleId {
+        if currentBundleId != bundleId || currentApp == nil {
+          _ = activateTarget(bundleId: bundleId, reason: "bundle_changed")
+        }
+      } else {
+        // Do not reuse stale bundle targets when the caller does not explicitly request one.
+        currentApp = nil
+        currentBundleId = nil
+      }
+
+      activeApp = currentApp ?? app
+      if let bundleId = requestedBundleId, targetNeedsActivation(activeApp) {
+        activeApp = activateTarget(bundleId: bundleId, reason: "stale_target")
+      } else if requestedBundleId == nil, targetNeedsActivation(activeApp) {
+        app.activate()
+        activeApp = app
+      }
+
+      if !activeApp.waitForExistence(timeout: appExistenceTimeout) {
+        if let bundleId = requestedBundleId {
+          activeApp = activateTarget(bundleId: bundleId, reason: "missing_after_wait")
+          guard activeApp.waitForExistence(timeout: appExistenceTimeout) else {
+            return Response(ok: false, error: ErrorPayload(message: "app '\(bundleId)' is not available"))
+          }
+        } else {
+          return Response(ok: false, error: ErrorPayload(message: "runner app is not available"))
+        }
+      }
+
+      if isInteractionCommand(command.command) {
+        if let bundleId = requestedBundleId, activeApp.state != .runningForeground {
+          activeApp = activateTarget(bundleId: bundleId, reason: "interaction_foreground_guard")
+        } else if requestedBundleId == nil, activeApp.state != .runningForeground {
+          app.activate()
+          activeApp = app
+        }
+        if !activeApp.waitForExistence(timeout: 2) {
+          if let bundleId = requestedBundleId {
+            return Response(ok: false, error: ErrorPayload(message: "app '\(bundleId)' is not available"))
+          }
+          return Response(ok: false, error: ErrorPayload(message: "runner app is not available"))
+        }
+        applyInteractionStabilizationIfNeeded()
+      }
+    }
+
+    switch command.command {
+    case .shutdown:
+      stopRecordingIfNeeded()
+      return Response(ok: true, data: DataPayload(message: "shutdown"))
+    case .recordStart:
+      guard
+        let requestedOutPath = command.outPath?.trimmingCharacters(in: .whitespacesAndNewlines),
+        !requestedOutPath.isEmpty
+      else {
+        return Response(ok: false, error: ErrorPayload(message: "recordStart requires outPath"))
+      }
+      let hasAppBundleId = !(command.appBundleId?
+        .trimmingCharacters(in: .whitespacesAndNewlines)
+        .isEmpty ?? true)
+      guard hasAppBundleId else {
+        return Response(ok: false, error: ErrorPayload(message: "recordStart requires appBundleId"))
+      }
+      if activeRecording != nil {
+        return Response(ok: false, error: ErrorPayload(message: "recording already in progress"))
+      }
+      if let requestedFps = command.fps, (requestedFps < minRecordingFps || requestedFps > maxRecordingFps) {
+        return Response(ok: false, error: ErrorPayload(message: "recordStart fps must be between \(minRecordingFps) and \(maxRecordingFps)"))
+      }
+      do {
+        let resolvedOutPath = resolveRecordingOutPath(requestedOutPath)
+        let fpsLabel = command.fps.map(String.init) ?? "max"
+        NSLog(
+          "AGENT_DEVICE_RUNNER_RECORD_START requestedOutPath=%@ resolvedOutPath=%@ fps=%@",
+          requestedOutPath,
+          resolvedOutPath,
+          fpsLabel
+        )
+        let recorder = ScreenRecorder(outputPath: resolvedOutPath, fps: command.fps.map { Int32($0) })
+        try recorder.start { [weak self] in
+          return self?.captureRunnerFrame()
+        }
+        activeRecording = recorder
+        return Response(ok: true, data: DataPayload(message: "recording started"))
+      } catch {
+        activeRecording = nil
+        return Response(ok: false, error: ErrorPayload(message: "failed to start recording: \(error.localizedDescription)"))
+      }
+    case .recordStop:
+      guard let recorder = activeRecording else {
+        return Response(ok: false, error: ErrorPayload(message: "no active recording"))
+      }
+      do {
+        try recorder.stop()
+        activeRecording = nil
+        return Response(ok: true, data: DataPayload(message: "recording stopped"))
+      } catch {
+        activeRecording = nil
+        return Response(ok: false, error: ErrorPayload(message: "failed to stop recording: \(error.localizedDescription)"))
+      }
+    case .tap:
+      if let text = command.text {
+        if let element = findElement(app: activeApp, text: text) {
+          element.tap()
+          return Response(ok: true, data: DataPayload(message: "tapped"))
+        }
+        return Response(ok: false, error: ErrorPayload(message: "element not found"))
+      }
+      if let x = command.x, let y = command.y {
+        tapAt(app: activeApp, x: x, y: y)
+        return Response(ok: true, data: DataPayload(message: "tapped"))
+      }
+      return Response(ok: false, error: ErrorPayload(message: "tap requires text or x/y"))
+    case .tapSeries:
+      guard let x = command.x, let y = command.y else {
+        return Response(ok: false, error: ErrorPayload(message: "tapSeries requires x and y"))
+      }
+      let count = max(Int(command.count ?? 1), 1)
+      let intervalMs = max(command.intervalMs ?? 0, 0)
+      let doubleTap = command.doubleTap ?? false
+      if doubleTap {
+        runSeries(count: count, pauseMs: intervalMs) { _ in
+          doubleTapAt(app: activeApp, x: x, y: y)
+        }
+        return Response(ok: true, data: DataPayload(message: "tap series"))
+      }
+      runSeries(count: count, pauseMs: intervalMs) { _ in
+        tapAt(app: activeApp, x: x, y: y)
+      }
+      return Response(ok: true, data: DataPayload(message: "tap series"))
+    case .longPress:
+      guard let x = command.x, let y = command.y else {
+        return Response(ok: false, error: ErrorPayload(message: "longPress requires x and y"))
+      }
+      let duration = (command.durationMs ?? 800) / 1000.0
+      longPressAt(app: activeApp, x: x, y: y, duration: duration)
+      return Response(ok: true, data: DataPayload(message: "long pressed"))
+    case .drag:
+      guard let x = command.x, let y = command.y, let x2 = command.x2, let y2 = command.y2 else {
+        return Response(ok: false, error: ErrorPayload(message: "drag requires x, y, x2, and y2"))
+      }
+      let holdDuration = min(max((command.durationMs ?? 60) / 1000.0, 0.016), 10.0)
+      withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+        dragAt(app: activeApp, x: x, y: y, x2: x2, y2: y2, holdDuration: holdDuration)
+      }
+      return Response(ok: true, data: DataPayload(message: "dragged"))
+    case .dragSeries:
+      guard let x = command.x, let y = command.y, let x2 = command.x2, let y2 = command.y2 else {
+        return Response(ok: false, error: ErrorPayload(message: "dragSeries requires x, y, x2, and y2"))
+      }
+      let count = max(Int(command.count ?? 1), 1)
+      let pauseMs = max(command.pauseMs ?? 0, 0)
+      let pattern = command.pattern ?? "one-way"
+      if pattern != "one-way" && pattern != "ping-pong" {
+        return Response(ok: false, error: ErrorPayload(message: "dragSeries pattern must be one-way or ping-pong"))
+      }
+      let holdDuration = min(max((command.durationMs ?? 60) / 1000.0, 0.016), 10.0)
+      withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+        runSeries(count: count, pauseMs: pauseMs) { idx in
+          let reverse = pattern == "ping-pong" && (idx % 2 == 1)
+          if reverse {
+            dragAt(app: activeApp, x: x2, y: y2, x2: x, y2: y, holdDuration: holdDuration)
+          } else {
+            dragAt(app: activeApp, x: x, y: y, x2: x2, y2: y2, holdDuration: holdDuration)
+          }
+        }
+      }
+      return Response(ok: true, data: DataPayload(message: "drag series"))
+    case .type:
+      guard let text = command.text else {
+        return Response(ok: false, error: ErrorPayload(message: "type requires text"))
+      }
+      if command.clearFirst == true {
+        guard let focused = focusedTextInput(app: activeApp) else {
+          return Response(ok: false, error: ErrorPayload(message: "no focused text input to clear"))
+        }
+        clearTextInput(focused)
+        focused.typeText(text)
+        return Response(ok: true, data: DataPayload(message: "typed"))
+      }
+      if let focused = focusedTextInput(app: activeApp) {
+        focused.typeText(text)
+      } else {
+        activeApp.typeText(text)
+      }
+      return Response(ok: true, data: DataPayload(message: "typed"))
+    case .swipe:
+      guard let direction = command.direction else {
+        return Response(ok: false, error: ErrorPayload(message: "swipe requires direction"))
+      }
+      withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+        swipe(app: activeApp, direction: direction)
+      }
+      return Response(ok: true, data: DataPayload(message: "swiped"))
+    case .findText:
+      guard let text = command.text else {
+        return Response(ok: false, error: ErrorPayload(message: "findText requires text"))
+      }
+      let found = findElement(app: activeApp, text: text) != nil
+      return Response(ok: true, data: DataPayload(found: found))
+    case .snapshot:
+      let options = SnapshotOptions(
+        interactiveOnly: command.interactiveOnly ?? false,
+        compact: command.compact ?? false,
+        depth: command.depth,
+        scope: command.scope,
+        raw: command.raw ?? false,
+      )
+      if options.raw {
+        needsPostSnapshotInteractionDelay = true
+        return Response(ok: true, data: snapshotRaw(app: activeApp, options: options))
+      }
+      needsPostSnapshotInteractionDelay = true
+      return Response(ok: true, data: snapshotFast(app: activeApp, options: options))
+    case .screenshot:
+      // If a target app bundle ID is provided, activate it first so the screenshot
+      // captures the target app rather than the AgentDeviceRunner itself.
+      if let bundleId = command.appBundleId, !bundleId.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+        let targetApp = XCUIApplication(bundleIdentifier: bundleId)
+        targetApp.activate()
+        // Brief wait for the app transition animation to complete
+        Thread.sleep(forTimeInterval: 0.5)
+      }
+      let screenshot = XCUIScreen.main.screenshot()
+      guard let pngData = screenshot.image.pngData() else {
+        return Response(ok: false, error: ErrorPayload(message: "Failed to encode screenshot as PNG"))
+      }
+      let fileName = "screenshot-\(Int(Date().timeIntervalSince1970 * 1000)).png"
+      let filePath = (NSTemporaryDirectory() as NSString).appendingPathComponent(fileName)
+      do {
+        try pngData.write(to: URL(fileURLWithPath: filePath))
+      } catch {
+        return Response(ok: false, error: ErrorPayload(message: "Failed to write screenshot: \(error.localizedDescription)"))
+      }
+      // Return path relative to app container root (tmp/ maps to NSTemporaryDirectory)
+      return Response(ok: true, data: DataPayload(message: "tmp/\(fileName)"))
+    case .back:
+      if tapNavigationBack(app: activeApp) {
+        return Response(ok: true, data: DataPayload(message: "back"))
+      }
+      performBackGesture(app: activeApp)
+      return Response(ok: true, data: DataPayload(message: "back"))
+    case .home:
+      pressHomeButton()
+      return Response(ok: true, data: DataPayload(message: "home"))
+    case .appSwitcher:
+      performAppSwitcherGesture(app: activeApp)
+      return Response(ok: true, data: DataPayload(message: "appSwitcher"))
+    case .alert:
+      let action = (command.action ?? "get").lowercased()
+      let alert = activeApp.alerts.firstMatch
+      if !alert.exists {
+        return Response(ok: false, error: ErrorPayload(message: "alert not found"))
+      }
+      if action == "accept" {
+        let button = alert.buttons.allElementsBoundByIndex.first
+        button?.tap()
+        return Response(ok: true, data: DataPayload(message: "accepted"))
+      }
+      if action == "dismiss" {
+        let button = alert.buttons.allElementsBoundByIndex.last
+        button?.tap()
+        return Response(ok: true, data: DataPayload(message: "dismissed"))
+      }
+      let buttonLabels = alert.buttons.allElementsBoundByIndex.map { $0.label }
+      return Response(ok: true, data: DataPayload(message: alert.label, items: buttonLabels))
+    case .pinch:
+      guard let scale = command.scale, scale > 0 else {
+        return Response(ok: false, error: ErrorPayload(message: "pinch requires scale > 0"))
+      }
+      pinch(app: activeApp, scale: scale, x: command.x, y: command.y)
+      return Response(ok: true, data: DataPayload(message: "pinched"))
+    }
+  }
+}

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

@@ -0,0 +1,30 @@
+import Foundation
+
+// MARK: - Environment
+
+enum RunnerEnv {
+  static func resolvePort() -> UInt16 {
+    if let env = ProcessInfo.processInfo.environment["AGENT_DEVICE_RUNNER_PORT"], let port = UInt16(env) {
+      return port
+    }
+    for arg in CommandLine.arguments {
+      if arg.hasPrefix("AGENT_DEVICE_RUNNER_PORT=") {
+        let value = arg.replacingOccurrences(of: "AGENT_DEVICE_RUNNER_PORT=", with: "")
+        if let port = UInt16(value) { return port }
+      }
+    }
+    return 0
+  }
+
+  static func isTruthy(_ name: String) -> Bool {
+    guard let raw = ProcessInfo.processInfo.environment[name] else {
+      return false
+    }
+    switch raw.trimmingCharacters(in: .whitespacesAndNewlines).lowercased() {
+    case "1", "true", "yes", "on":
+      return true
+    default:
+      return false
+    }
+  }
+}

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

@@ -0,0 +1,258 @@
+import XCTest
+
+extension RunnerTests {
+  // MARK: - Navigation Gestures
+
+  func tapNavigationBack(app: XCUIApplication) -> Bool {
+    let buttons = app.navigationBars.buttons.allElementsBoundByIndex
+    if let back = buttons.first(where: { $0.isHittable }) {
+      back.tap()
+      return true
+    }
+    return pressTvRemoteMenuIfAvailable()
+  }
+
+  func performBackGesture(app: XCUIApplication) {
+    if pressTvRemoteMenuIfAvailable() {
+      return
+    }
+    let target = app.windows.firstMatch.exists ? app.windows.firstMatch : app
+    let start = target.coordinate(withNormalizedOffset: CGVector(dx: 0.05, dy: 0.5))
+    let end = target.coordinate(withNormalizedOffset: CGVector(dx: 0.8, dy: 0.5))
+    start.press(forDuration: 0.05, thenDragTo: end)
+  }
+
+  func performAppSwitcherGesture(app: XCUIApplication) {
+    if performTvRemoteAppSwitcherIfAvailable() {
+      return
+    }
+    let target = app.windows.firstMatch.exists ? app.windows.firstMatch : app
+    let start = target.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.99))
+    let end = target.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.7))
+    start.press(forDuration: 0.6, thenDragTo: end)
+  }
+
+  func pressHomeButton() {
+    if pressTvRemoteHomeIfAvailable() {
+      return
+    }
+    XCUIDevice.shared.press(.home)
+  }
+
+  private func pressTvRemoteMenuIfAvailable() -> Bool {
+#if os(tvOS)
+    XCUIRemote.shared.press(.menu)
+    return true
+#else
+    return false
+#endif
+  }
+
+  private func pressTvRemoteHomeIfAvailable() -> Bool {
+#if os(tvOS)
+    XCUIRemote.shared.press(.home)
+    return true
+#else
+    return false
+#endif
+  }
+
+  private func performTvRemoteAppSwitcherIfAvailable() -> Bool {
+#if os(tvOS)
+    XCUIRemote.shared.press(.home)
+    sleepFor(resolveTvRemoteDoublePressDelay())
+    XCUIRemote.shared.press(.home)
+    return true
+#else
+    return false
+#endif
+  }
+
+  private func resolveTvRemoteDoublePressDelay() -> TimeInterval {
+    guard
+      let raw = ProcessInfo.processInfo.environment["AGENT_DEVICE_TV_REMOTE_DOUBLE_PRESS_DELAY_MS"],
+      !raw.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+    else {
+      return tvRemoteDoublePressDelayDefault
+    }
+    guard let parsedMs = Double(raw), parsedMs >= 0 else {
+      return tvRemoteDoublePressDelayDefault
+    }
+    return min(parsedMs, 1000) / 1000.0
+  }
+
+  func findElement(app: XCUIApplication, text: String) -> XCUIElement? {
+    let predicate = NSPredicate(format: "label CONTAINS[c] %@ OR identifier CONTAINS[c] %@ OR value CONTAINS[c] %@", text, text, text)
+    let element = app.descendants(matching: .any).matching(predicate).firstMatch
+    return element.exists ? element : nil
+  }
+
+  func clearTextInput(_ element: XCUIElement) {
+    moveCaretToEnd(element: element)
+    let count = estimatedDeleteCount(for: element)
+    let deletes = String(repeating: XCUIKeyboardKey.delete.rawValue, count: count)
+    element.typeText(deletes)
+  }
+
+  func focusedTextInput(app: XCUIApplication) -> XCUIElement? {
+    let focused = app
+      .descendants(matching: .any)
+      .matching(NSPredicate(format: "hasKeyboardFocus == 1"))
+      .firstMatch
+    guard focused.exists else { return nil }
+
+    switch focused.elementType {
+    case .textField, .secureTextField, .searchField, .textView:
+      return focused
+    default:
+      return nil
+    }
+  }
+
+  private func moveCaretToEnd(element: XCUIElement) {
+    let frame = element.frame
+    guard !frame.isEmpty else {
+      element.tap()
+      return
+    }
+    let origin = element.coordinate(withNormalizedOffset: CGVector(dx: 0, dy: 0))
+    let target = origin.withOffset(
+      CGVector(dx: max(2, frame.width - 4), dy: max(2, frame.height / 2))
+    )
+    target.tap()
+  }
+
+  private func estimatedDeleteCount(for element: XCUIElement) -> Int {
+    let valueText = String(describing: element.value ?? "")
+      .trimmingCharacters(in: .whitespacesAndNewlines)
+    let base = valueText.isEmpty ? 24 : (valueText.count + 8)
+    return max(24, min(120, base))
+  }
+
+  func findScopeElement(app: XCUIApplication, scope: String) -> XCUIElement? {
+    let predicate = NSPredicate(
+      format: "label CONTAINS[c] %@ OR identifier CONTAINS[c] %@",
+      scope,
+      scope
+    )
+    let element = app.descendants(matching: .any).matching(predicate).firstMatch
+    return element.exists ? element : nil
+  }
+
+  func tapAt(app: XCUIApplication, x: Double, y: Double) {
+    let origin = app.coordinate(withNormalizedOffset: CGVector(dx: 0, dy: 0))
+    let coordinate = origin.withOffset(CGVector(dx: x, dy: y))
+    coordinate.tap()
+  }
+
+  func doubleTapAt(app: XCUIApplication, x: Double, y: Double) {
+    let origin = app.coordinate(withNormalizedOffset: CGVector(dx: 0, dy: 0))
+    let coordinate = origin.withOffset(CGVector(dx: x, dy: y))
+    coordinate.doubleTap()
+  }
+
+  func longPressAt(app: XCUIApplication, x: Double, y: Double, duration: TimeInterval) {
+    let origin = app.coordinate(withNormalizedOffset: CGVector(dx: 0, dy: 0))
+    let coordinate = origin.withOffset(CGVector(dx: x, dy: y))
+    coordinate.press(forDuration: duration)
+  }
+
+  func dragAt(
+    app: XCUIApplication,
+    x: Double,
+    y: Double,
+    x2: Double,
+    y2: Double,
+    holdDuration: TimeInterval
+  ) {
+    let origin = app.coordinate(withNormalizedOffset: CGVector(dx: 0, dy: 0))
+    let start = origin.withOffset(CGVector(dx: x, dy: y))
+    let end = origin.withOffset(CGVector(dx: x2, dy: y2))
+    start.press(forDuration: holdDuration, thenDragTo: end)
+  }
+
+  func runSeries(count: Int, pauseMs: Double, operation: (Int) -> Void) {
+    let total = max(count, 1)
+    let pause = max(pauseMs, 0)
+    for idx in 0..<total {
+      operation(idx)
+      if idx < total - 1 && pause > 0 {
+        Thread.sleep(forTimeInterval: pause / 1000.0)
+      }
+    }
+  }
+
+  func swipe(app: XCUIApplication, direction: SwipeDirection) {
+    if performTvRemoteSwipeIfAvailable(direction: direction) {
+      return
+    }
+    let target = app.windows.firstMatch.exists ? app.windows.firstMatch : app
+    let start = target.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.2))
+    let end = target.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.8))
+    let left = target.coordinate(withNormalizedOffset: CGVector(dx: 0.2, dy: 0.5))
+    let right = target.coordinate(withNormalizedOffset: CGVector(dx: 0.8, dy: 0.5))
+
+    switch direction {
+    case .up:
+      end.press(forDuration: 0.1, thenDragTo: start)
+    case .down:
+      start.press(forDuration: 0.1, thenDragTo: end)
+    case .left:
+      right.press(forDuration: 0.1, thenDragTo: left)
+    case .right:
+      left.press(forDuration: 0.1, thenDragTo: right)
+    }
+  }
+
+  private func performTvRemoteSwipeIfAvailable(direction: SwipeDirection) -> Bool {
+#if os(tvOS)
+    switch direction {
+    case .up:
+      XCUIRemote.shared.press(.up)
+    case .down:
+      XCUIRemote.shared.press(.down)
+    case .left:
+      XCUIRemote.shared.press(.left)
+    case .right:
+      XCUIRemote.shared.press(.right)
+    }
+    return true
+#else
+    return false
+#endif
+  }
+
+  func pinch(app: XCUIApplication, scale: Double, x: Double?, y: Double?) {
+    let target = app.windows.firstMatch.exists ? app.windows.firstMatch : app
+
+    // Use double-tap + drag gesture for reliable map zoom
+    // Zoom in (scale > 1): tap then drag UP
+    // Zoom out (scale < 1): tap then drag DOWN
+
+    // Determine center point (use provided x/y or screen center)
+    let centerX = x.map { $0 / target.frame.width } ?? 0.5
+    let centerY = y.map { $0 / target.frame.height } ?? 0.5
+    let center = target.coordinate(withNormalizedOffset: CGVector(dx: centerX, dy: centerY))
+
+    // Calculate drag distance based on scale (clamped to reasonable range)
+    // Larger scale = more drag distance
+    let dragAmount: CGFloat
+    if scale > 1.0 {
+      // Zoom in: drag up (negative Y direction in normalized coords)
+      dragAmount = min(0.4, CGFloat(scale - 1.0) * 0.2)
+    } else {
+      // Zoom out: drag down (positive Y direction)
+      dragAmount = min(0.4, CGFloat(1.0 - scale) * 0.4)
+    }
+
+    let endY = scale > 1.0 ? (centerY - Double(dragAmount)) : (centerY + Double(dragAmount))
+    let endPoint = target.coordinate(withNormalizedOffset: CGVector(dx: centerX, dy: max(0.1, min(0.9, endY))))
+
+    // Tap first (first tap of double-tap)
+    center.tap()
+
+    // Immediately press and drag (second tap + drag)
+    center.press(forDuration: 0.05, thenDragTo: endPoint)
+  }
+
+}