agent-device 0.17.1 → 0.17.3

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

@@ -0,0 +1,328 @@
+import XCTest
+
+extension RunnerTests {
+  private static let privateAXSnapshotMaxNodes = 5_000
+  /// Deep React Native trees make the AX server reject bulk snapshot requests outright with
+  /// kAXErrorIllegalArgument once the requested depth crosses a tree-size-dependent limit
+  /// (observed between depth 56 and 64 on the Bluesky Home feed; the limit moves with live
+  /// content). Retrying the same request at a shallower depth succeeds, so on failure we walk
+  /// this ladder instead of giving up. Capped at 4 attempts to bound worst-case latency on
+  /// apps where the AX surface is genuinely unavailable.
+  static let privateAXSnapshotDepthLadder = [56, 40, 24, 12]
+
+  func privateAXSnapshotCapture(
+    app: XCUIApplication,
+    options: SnapshotOptions
+  ) -> SnapshotBackendCapture? {
+    #if os(iOS) && targetEnvironment(simulator)
+      let requestedDepth = options.depth ?? 64
+      var attemptDepths = [requestedDepth]
+      attemptDepths.append(
+        contentsOf: Self.privateAXSnapshotDepthLadder.filter { $0 < requestedDepth }
+      )
+      var response: [String: Any] = [:]
+      var effectiveDepth = requestedDepth
+      var lastError = "unknown private AX snapshot failure"
+      for depth in attemptDepths {
+        response = RunnerAXSnapshotBridge.snapshotTree(
+          for: app,
+          maxDepth: depth,
+          maxNodes: Self.privateAXSnapshotMaxNodes
+        )
+        if response["ok"] as? Bool == true {
+          effectiveDepth = depth
+          break
+        }
+        lastError = response["error"] as? String ?? lastError
+        NSLog(
+          "AGENT_DEVICE_RUNNER_PRIVATE_AX_SNAPSHOT_DEPTH_RETRY depth=%ld error=%@",
+          depth,
+          lastError
+        )
+      }
+      guard response["ok"] as? Bool == true else {
+        NSLog("AGENT_DEVICE_RUNNER_PRIVATE_AX_SNAPSHOT_FAILED=%@", lastError)
+        return nil
+      }
+      guard let root = response["root"] as? [String: Any] else {
+        NSLog("AGENT_DEVICE_RUNNER_PRIVATE_AX_SNAPSHOT_FAILED=missing root")
+        return nil
+      }
+
+      // The public windows query backing safeSnapshotViewport can fail on the same apps that
+      // need this fallback, degrading to an infinite viewport that marks off-screen content
+      // (e.g. closed drawer menus at negative x) as visible and tappable. The private root's
+      // own frame is the reliable screen rect here.
+      var viewport = safeSnapshotViewport(app: app)
+      let rootFrame = privateAXRect(root["frame"])
+      if viewport.isInfinite || viewport.isNull || viewport.isEmpty, !rootFrame.isEmpty {
+        viewport = rootFrame
+      }
+      var nodes: [SnapshotNode] = []
+      appendPrivateAXNode(
+        root,
+        to: &nodes,
+        options: options,
+        viewport: viewport,
+        depth: 0,
+        parentIndex: nil,
+        insideMatchedScope: false
+      )
+      if nodes.count <= 1 {
+        NSLog("AGENT_DEVICE_RUNNER_PRIVATE_AX_SNAPSHOT_SPARSE=%ld", nodes.count)
+        return nil
+      }
+
+      let depthLimited = effectiveDepth < requestedDepth
+      NSLog(
+        "AGENT_DEVICE_RUNNER_PRIVATE_AX_SNAPSHOT_USED nodes=%ld depth=%ld",
+        nodes.count,
+        effectiveDepth
+      )
+      return SnapshotBackendCapture(
+        payload: DataPayload(nodes: nodes, truncated: (response["truncated"] as? Bool) == true),
+        effectiveDepth: depthLimited ? effectiveDepth : nil
+      )
+    #else
+      return nil
+    #endif
+  }
+
+  private func appendPrivateAXNode(
+    _ rawNode: [String: Any],
+    to nodes: inout [SnapshotNode],
+    options: SnapshotOptions,
+    viewport: CGRect,
+    depth: Int,
+    parentIndex: Int?,
+    insideMatchedScope: Bool
+  ) {
+    if let limit = options.depth, depth > limit { return }
+
+    let rect = privateAXRect(rawNode["frame"])
+    let label = privateAXString(rawNode["label"])
+    let identifier = privateAXString(rawNode["identifier"])
+    let value = privateAXString(rawNode["value"])
+    let rawType = privateAXInt(rawNode["type"]) ?? 0
+    let typeName = elementTypeName(rawElementType: rawType)
+    let enabled = privateAXBool(rawNode["enabled"]) ?? true
+    let visible = isVisibleInViewport(rect, viewport)
+    let interactiveCandidate = privateAXInteractiveCandidate(rawElementType: rawType)
+    let filterDecision = flatSnapshotFilterDecision(
+      FlatSnapshotFilterNode(
+        isRoot: parentIndex == nil,
+        label: label,
+        identifier: identifier,
+        valueText: value.isEmpty ? nil : value,
+        visible: visible
+      ),
+      options: options,
+      insideMatchedScope: insideMatchedScope
+    )
+    let include = filterDecision.include
+    let nowInsideScope = filterDecision.insideMatchedScope
+
+    let currentIndex: Int?
+    if include {
+      currentIndex = nodes.count
+      nodes.append(
+        SnapshotNode(
+          index: nodes.count,
+          type: typeName,
+          label: label.isEmpty ? nil : label,
+          identifier: identifier.isEmpty ? nil : identifier,
+          value: value.isEmpty ? nil : value,
+          rect: snapshotRect(from: rect),
+          enabled: enabled,
+          focused: privateAXBool(rawNode["focused"]) == true ? true : nil,
+          selected: privateAXBool(rawNode["selected"]) == true ? true : nil,
+          hittable: visible && enabled && interactiveCandidate,
+          depth: depth,
+          parentIndex: parentIndex,
+          hiddenContentAbove: nil,
+          hiddenContentBelow: nil
+        )
+      )
+    } else {
+      currentIndex = parentIndex
+    }
+
+    guard let children = rawNode["children"] as? [[String: Any]] else {
+      return
+    }
+    for child in children {
+      appendPrivateAXNode(
+        child,
+        to: &nodes,
+        options: options,
+        viewport: viewport,
+        depth: depth + 1,
+        parentIndex: currentIndex,
+        insideMatchedScope: nowInsideScope
+      )
+    }
+  }
+
+  private func elementTypeName(rawElementType: Int) -> String {
+    if let type = flatSnapshotElementType(rawElementType: rawElementType) {
+      return elementTypeName(type)
+    }
+    return "Element(\(rawElementType))"
+  }
+
+  private func privateAXString(_ value: Any?) -> String {
+    guard let value else { return "" }
+    if let string = value as? String {
+      return string.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+    return String(describing: value).trimmingCharacters(in: .whitespacesAndNewlines)
+  }
+
+  private func privateAXInt(_ value: Any?) -> Int? {
+    if let value = value as? Int { return value }
+    if let value = value as? NSNumber { return value.intValue }
+    return nil
+  }
+
+  private func privateAXBool(_ value: Any?) -> Bool? {
+    if let value = value as? Bool { return value }
+    if let value = value as? NSNumber { return value.boolValue }
+    return nil
+  }
+
+  private func privateAXRect(_ value: Any?) -> CGRect {
+    guard let frame = value as? [String: Any] else {
+      return .zero
+    }
+    return CGRect(
+      x: privateAXDouble(frame["x"]) ?? 0,
+      y: privateAXDouble(frame["y"]) ?? 0,
+      width: privateAXDouble(frame["width"]) ?? 0,
+      height: privateAXDouble(frame["height"]) ?? 0
+    )
+  }
+
+  private func privateAXDouble(_ value: Any?) -> Double? {
+    if let value = value as? Double { return value }
+    if let value = value as? NSNumber { return value.doubleValue }
+    return nil
+  }
+}
+
+// MARK: - In-bundle unit tests
+
+extension RunnerTests {
+  func testPrivateAXScopeSelectsSubtreeNotMatchingLabels() {
+    let tree: [String: Any] = [
+      "type": 1, "label": "App",
+      "children": [
+        [
+          "type": 9, "identifier": "homeScreen",
+          "children": [
+            ["type": 48, "label": "Post body without the scope text", "children": []]
+          ],
+        ],
+        ["type": 9, "label": "unrelated sibling", "children": []],
+      ],
+    ]
+    var nodes: [SnapshotNode] = []
+    appendPrivateAXNode(
+      tree,
+      to: &nodes,
+      options: SnapshotOptions(interactiveOnly: false, depth: nil, scope: "homeScreen", raw: false),
+      viewport: .infinite,
+      depth: 0,
+      parentIndex: nil,
+      insideMatchedScope: false
+    )
+
+    let labels = nodes.compactMap { $0.label ?? $0.identifier }
+    XCTAssertTrue(labels.contains("homeScreen"))
+    // Descendants of the matched scope are included even when they do not contain the text.
+    XCTAssertTrue(labels.contains("Post body without the scope text"))
+    XCTAssertFalse(labels.contains("unrelated sibling"))
+  }
+
+  func testPrivateAXInteractiveFiltersLoginLikeHiddenDrawer() {
+    let tree: [String: Any] = [
+      "type": Int(XCUIElement.ElementType.application.rawValue),
+      "label": "Blue Sky",
+      "frame": ["x": 0, "y": 0, "width": 390, "height": 844],
+      "children": [
+        [
+          "type": Int(XCUIElement.ElementType.scrollView.rawValue),
+          "frame": ["x": 0, "y": 0, "width": 390, "height": 844],
+          "children": [
+            [
+              "type": Int(XCUIElement.ElementType.image.rawValue),
+              "label": "Callstack",
+              "frame": ["x": 145, "y": 104, "width": 100, "height": 100],
+              "children": [],
+            ],
+            [
+              "type": Int(XCUIElement.ElementType.staticText.rawValue),
+              "label": "Welcome back",
+              "frame": ["x": 32, "y": 260, "width": 326, "height": 32],
+              "children": [],
+            ],
+            [
+              "type": Int(XCUIElement.ElementType.textField.rawValue),
+              "label": "Email",
+              "identifier": "login.email",
+              "frame": ["x": 32, "y": 348, "width": 326, "height": 48],
+              "children": [],
+            ],
+            [
+              "type": Int(XCUIElement.ElementType.secureTextField.rawValue),
+              "label": "Password",
+              "identifier": "login.password",
+              "frame": ["x": 32, "y": 412, "width": 326, "height": 48],
+              "children": [],
+            ],
+            [
+              "type": Int(XCUIElement.ElementType.button.rawValue),
+              "label": "Sign in",
+              "identifier": "login.submit",
+              "frame": ["x": 32, "y": 492, "width": 326, "height": 52],
+              "children": [],
+            ],
+            [
+              "type": Int(XCUIElement.ElementType.link.rawValue),
+              "label": "Forgot password?",
+              "frame": ["x": 128, "y": 568, "width": 134, "height": 32],
+              "children": [],
+            ],
+            [
+              "type": Int(XCUIElement.ElementType.button.rawValue),
+              "label": "Admin settings",
+              "frame": ["x": -260, "y": 184, "width": 220, "height": 44],
+              "children": [],
+            ],
+            [
+              "type": Int(XCUIElement.ElementType.other.rawValue),
+              "frame": ["x": 16, "y": 184, "width": 220, "height": 44],
+              "children": [],
+            ],
+          ],
+        ]
+      ],
+    ]
+    var nodes: [SnapshotNode] = []
+    appendPrivateAXNode(
+      tree,
+      to: &nodes,
+      options: SnapshotOptions(interactiveOnly: true, depth: nil, scope: nil, raw: false),
+      viewport: CGRect(x: 0, y: 0, width: 390, height: 844),
+      depth: 0,
+      parentIndex: nil,
+      insideMatchedScope: false
+    )
+
+    let labels = nodes.compactMap { $0.label }
+    XCTAssertEqual(
+      labels,
+      ["Blue Sky", "Callstack", "Welcome back", "Email", "Password", "Sign in", "Forgot password?"]
+    )
+    XCTAssertFalse(labels.contains("Admin settings"))
+  }
+}

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

@@ -17,7 +17,7 @@ extension RunnerTests {
     min(max((durationMs / 5.0) / 1000.0, 0.016), 0.120)
   }
 
-  private func coordinateDragHoldDuration() -> TimeInterval {
+  func coordinateDragHoldDuration() -> TimeInterval {
     0.050
   }
 
@@ -55,27 +55,6 @@ extension RunnerTests {
     }
   }
 
-  private func performDragSeries(
-    count: Int,
-    pauseMs: Double,
-    pattern: String,
-    points: DragPoints,
-    _ drag: (_ x: Double, _ y: Double, _ x2: Double, _ y2: Double) -> RunnerInteractionOutcome
-  ) -> RunnerInteractionOutcome {
-    var outcome = RunnerInteractionOutcome.performed
-    runSeries(count: count, pauseMs: pauseMs) { idx in
-      guard case .performed = outcome else {
-        return
-      }
-      let reverse = pattern == "ping-pong" && (idx % 2 == 1)
-      let startX = reverse ? points.x2 : points.x
-      let startY = reverse ? points.y2 : points.y
-      let endX = reverse ? points.x : points.x2
-      let endY = reverse ? points.y : points.y2
-      outcome = drag(startX, startY, endX, endY)
-    }
-    return outcome
-  }
 
   /// Runs a gesture action with uniform timing capture. Touch gestures pass `idleTimeout: true`
   /// (the default) to run inside the scroll idle-timeout + quiescence-skip wrapper; synthesis
@@ -84,7 +63,7 @@ extension RunnerTests {
   ///
   /// NOTE: a new SYNTHESIS gesture must pass `idleTimeout: false` — the default `true` would wrap
   /// it in the scroll idle-timeout/quiescence-skip path and change its runtime behavior.
-  private func performGesture(
+  func performGesture(
     _ app: XCUIApplication,
     idleTimeout: Bool = true,
     _ action: () -> RunnerInteractionOutcome
@@ -244,6 +223,8 @@ extension RunnerTests {
   }
 
   func executeUptime() -> Response {
+    // Placeholder value: the transport layer (jsonResponse) overwrites currentUptimeMs with a
+    // fresher send-time stamp on every ok response; kept so direct callers still get a value.
     Response(
       ok: true,
       data: DataPayload(currentUptimeMs: currentUptimeMs())
@@ -580,42 +561,6 @@ extension RunnerTests {
       } catch {
         return Response(ok: false, error: ErrorPayload(message: error.localizedDescription))
       }
-    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
-      let touchFrame = resolvedTouchVisualizationFrame(app: activeApp, x: x, y: y)
-      if doubleTap {
-        let (timing, outcome) = performGesture(activeApp) {
-          var outcome = RunnerInteractionOutcome.performed
-          runSeries(count: count, pauseMs: intervalMs) { _ in
-            if case .performed = outcome {
-              outcome = doubleTapAt(app: activeApp, x: x, y: y)
-            }
-          }
-          return outcome
-        }
-        if let response = unsupportedResponse(for: outcome) {
-          return response
-        }
-        return gestureResponse(message: "tap series", timing: timing, frame: .touch(touchFrame))
-      }
-      let (timing, outcome) = performGesture(activeApp) {
-        var outcome = RunnerInteractionOutcome.performed
-        runSeries(count: count, pauseMs: intervalMs) { _ in
-          if case .performed = outcome {
-            outcome = tapAt(app: activeApp, x: x, y: y)
-          }
-        }
-        return outcome
-      }
-      if let response = unsupportedResponse(for: outcome) {
-        return response
-      }
-      return gestureResponse(message: "tap series", timing: timing, frame: .touch(touchFrame))
     case .longPress:
       guard let x = command.x, let y = command.y else {
         return Response(ok: false, error: ErrorPayload(message: "longPress requires x and y"))
@@ -633,114 +578,63 @@ extension RunnerTests {
       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 dragPoints = keyboardAvoidingDragPoints(app: activeApp, x: x, y: y, x2: x2, y2: y2)
-      let dragFrame = resolvedDragVisualizationFrame(
-        app: activeApp,
-        x: dragPoints.x,
-        y: dragPoints.y,
-        x2: dragPoints.x2,
-        y2: dragPoints.y2
+      return executeDragGesture(
+        activeApp: activeApp,
+        x: x,
+        y: y,
+        x2: x2,
+        y2: y2,
+        durationMs: command.durationMs,
+        synthesized: command.synthesized == true,
+        message: "dragged"
       )
-      var fallback: GestureFallback?
-      if command.synthesized == true {
-        let durationMs = min(max(command.durationMs ?? 250, 16), 10000)
-        let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
-          synthesizedDragAt(
-            app: activeApp,
-            x: dragPoints.x,
-            y: dragPoints.y,
-            x2: dragPoints.x2,
-            y2: dragPoints.y2,
-            durationMs: durationMs
+    case .scroll:
+      // Fused frame-resolve + drag scroll for non-tvOS. Resolves the interaction frame via
+      // resolvedTouchReferenceFrame, computes drag endpoints with the Swift port of
+      // buildScrollGesturePlan, then runs the same non-synthesized drag path scroll's drag used.
+      guard let direction = command.direction,
+        direction == "up" || direction == "down" || direction == "left" || direction == "right"
+      else {
+        return Response(
+          ok: false,
+          error: ErrorPayload(
+            code: "INVALID_ARGS",
+            message: "scroll requires direction up|down|left|right"
           )
-        }
-        if case .performed = outcome {
-          return gestureResponse(message: "dragged", timing: timing, frame: .drag(dragFrame))
-        }
-        fallback = gestureFallback(strategy: "xctest-coordinate-drag", from: outcome)
-      }
-      let holdDuration = command.synthesized == true
-        ? synthesizedSwipeFallbackHoldDuration(durationMs: command.durationMs ?? 250)
-        : coordinateDragHoldDuration()
-      let (timing, outcome) = performGesture(activeApp) {
-        dragAt(
-          app: activeApp,
-          x: dragPoints.x,
-          y: dragPoints.y,
-          x2: dragPoints.x2,
-          y2: dragPoints.y2,
-          holdDuration: holdDuration
         )
       }
-      if let response = unsupportedResponse(for: outcome) {
-        return response
-      }
-      return gestureResponse(
-        message: "dragged",
-        timing: timing,
-        frame: .drag(dragFrame),
-        fallback: fallback
-      )
-    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 dragPoints = keyboardAvoidingDragPoints(app: activeApp, x: x, y: y, x2: x2, y2: y2)
-      var fallback: GestureFallback?
-      if command.synthesized == true {
-        let durationMs = min(max(command.durationMs ?? 250, 16), 10000)
-        let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
-          performDragSeries(
-            count: count,
-            pauseMs: pauseMs,
-            pattern: pattern,
-            points: dragPoints
-          ) { startX, startY, endX, endY in
-            synthesizedDragAt(
-              app: activeApp,
-              x: startX,
-              y: startY,
-              x2: endX,
-              y2: endY,
-              durationMs: durationMs
-            )
-          }
-        }
-        if case .performed = outcome {
-          return gestureResponse(message: "drag series", timing: timing)
-        }
-        fallback = gestureFallback(strategy: "xctest-coordinate-drag-series", from: outcome)
+      let frame = resolvedTouchReferenceFrame(app: activeApp, appFrame: activeApp.frame)
+      guard frame.width > 0, frame.height > 0 else {
+        return Response(
+          ok: false,
+          error: ErrorPayload(message: "scroll could not resolve a usable interaction frame")
+        )
       }
-      let holdDuration = command.synthesized == true
-        ? synthesizedSwipeFallbackHoldDuration(durationMs: command.durationMs ?? 250)
-        : coordinateDragHoldDuration()
-      let (timing, outcome) = performGesture(activeApp) {
-        performDragSeries(
-          count: count,
-          pauseMs: pauseMs,
-          pattern: pattern,
-          points: dragPoints
-        ) { startX, startY, endX, endY in
-          dragAt(
-            app: activeApp,
-            x: startX,
-            y: startY,
-            x2: endX,
-            y2: endY,
-            holdDuration: holdDuration
+      guard let plan = runnerScrollGesturePlan(
+        direction: direction,
+        amount: command.amount,
+        pixels: command.pixels,
+        referenceWidth: frame.width,
+        referenceHeight: frame.height
+      ) else {
+        return Response(
+          ok: false,
+          error: ErrorPayload(
+            code: "INVALID_ARGS",
+            message: "scroll could not compute a gesture plan"
           )
-        }
-      }
-      if let response = unsupportedResponse(for: outcome) {
-        return response
+        )
       }
-      return gestureResponse(message: "drag series", timing: timing, fallback: fallback)
+      return executeDragGesture(
+        activeApp: activeApp,
+        x: frame.minX + plan.x1,
+        y: frame.minY + plan.y1,
+        x2: frame.minX + plan.x2,
+        y2: frame.minY + plan.y2,
+        durationMs: nil,
+        synthesized: false,
+        message: "scrolled"
+      )
     case .remotePress:
       guard let button = tvRemoteButton(from: command.remoteButton) else {
         return Response(ok: false, error: ErrorPayload(message: "remotePress requires remoteButton"))
@@ -759,17 +653,6 @@ extension RunnerTests {
         response = executeTypeCommand(activeApp: activeApp, command: command)
       }
       return response ?? Response(ok: false, error: ErrorPayload(message: "type produced no response"))
-    case .interactionFrame:
-      let frame = resolvedTouchReferenceFrame(app: activeApp, appFrame: activeApp.frame)
-      return Response(
-        ok: true,
-        data: DataPayload(
-          x: frame.minX,
-          y: frame.minY,
-          referenceWidth: frame.width,
-          referenceHeight: frame.height
-        )
-      )
     case .swipe:
       guard let direction = command.direction else {
         return Response(ok: false, error: ErrorPayload(message: "swipe requires direction"))
@@ -808,7 +691,6 @@ extension RunnerTests {
     case .snapshot:
       let options = SnapshotOptions(
         interactiveOnly: command.interactiveOnly ?? false,
-        compact: command.compact ?? false,
         depth: command.depth,
         scope: command.scope,
         raw: command.raw ?? false
@@ -960,6 +842,8 @@ extension RunnerTests {
         return response
       }
       return gestureResponse(message: "pinched", timing: timing)
+    case .sequence:
+      return executeSequence(command: command, activeApp: activeApp)
     case .rotateGesture:
       guard let degrees = command.degrees, degrees.isFinite else {
         return Response(ok: false, error: ErrorPayload(message: "rotateGesture requires degrees"))
@@ -1023,6 +907,71 @@ extension RunnerTests {
     }
   }
 
+  /// Shared drag execution for `.drag` and the fused `.scroll`. Mirrors the original `.drag` body
+  /// exactly: keyboardAvoidingDragPoints -> resolvedDragVisualizationFrame -> synthesized branch
+  /// (16-10000ms clamp) or non-synthesized dragAt with coordinateDragHoldDuration ->
+  /// gestureResponse(.drag). `.scroll` always passes synthesized: false, pinning the same
+  /// non-synthesized drag path scroll's drag used today.
+  private func executeDragGesture(
+    activeApp: XCUIApplication,
+    x: Double,
+    y: Double,
+    x2: Double,
+    y2: Double,
+    durationMs: Double?,
+    synthesized: Bool,
+    message: String
+  ) -> Response {
+    let dragPoints = keyboardAvoidingDragPoints(app: activeApp, x: x, y: y, x2: x2, y2: y2)
+    let dragFrame = resolvedDragVisualizationFrame(
+      app: activeApp,
+      x: dragPoints.x,
+      y: dragPoints.y,
+      x2: dragPoints.x2,
+      y2: dragPoints.y2
+    )
+    var fallback: GestureFallback?
+    if synthesized {
+      let durationMs = min(max(durationMs ?? 250, 16), 10000)
+      let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
+        synthesizedDragAt(
+          app: activeApp,
+          x: dragPoints.x,
+          y: dragPoints.y,
+          x2: dragPoints.x2,
+          y2: dragPoints.y2,
+          durationMs: durationMs
+        )
+      }
+      if case .performed = outcome {
+        return gestureResponse(message: message, timing: timing, frame: .drag(dragFrame))
+      }
+      fallback = gestureFallback(strategy: "xctest-coordinate-drag", from: outcome)
+    }
+    let holdDuration = synthesized
+      ? synthesizedSwipeFallbackHoldDuration(durationMs: durationMs ?? 250)
+      : coordinateDragHoldDuration()
+    let (timing, outcome) = performGesture(activeApp) {
+      dragAt(
+        app: activeApp,
+        x: dragPoints.x,
+        y: dragPoints.y,
+        x2: dragPoints.x2,
+        y2: dragPoints.y2,
+        holdDuration: holdDuration
+      )
+    }
+    if let response = unsupportedResponse(for: outcome) {
+      return response
+    }
+    return gestureResponse(
+      message: message,
+      timing: timing,
+      frame: .drag(dragFrame),
+      fallback: fallback
+    )
+  }
+
   private func currentXCTestFailureCount() -> Int {
     return testRun?.failureCount ?? 0
   }