agent-device 0.8.6 → 0.10.0

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

@@ -4,12 +4,20 @@ extension RunnerTests {
   // MARK: - Navigation Gestures
 
   func tapNavigationBack(app: XCUIApplication) -> Bool {
+#if os(macOS)
+    if let back = macOSNavigationBackElement(app: app) {
+      tapElementCenter(app: app, element: back)
+      return true
+    }
+    return false
+#else
     let buttons = app.navigationBars.buttons.allElementsBoundByIndex
     if let back = buttons.first(where: { $0.isHittable }) {
       back.tap()
       return true
     }
     return pressTvRemoteMenuIfAvailable()
+#endif
   }
 
   func performBackGesture(app: XCUIApplication) {
@@ -33,10 +41,14 @@ extension RunnerTests {
   }
 
   func pressHomeButton() {
+#if os(macOS)
+    return
+#else
     if pressTvRemoteHomeIfAvailable() {
       return
     }
     XCUIDevice.shared.press(.home)
+#endif
   }
 
   private func pressTvRemoteMenuIfAvailable() -> Bool {
@@ -140,20 +152,47 @@ extension RunnerTests {
   }
 
   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))
+    let coordinate = interactionCoordinate(app: app, x: x, y: y)
     coordinate.tap()
   }
 
+  func mouseClickAt(app: XCUIApplication, x: Double, y: Double, button: String) throws {
+    let coordinate = interactionCoordinate(app: app, x: x, y: y)
+    #if os(macOS)
+      switch button {
+      case "primary":
+        coordinate.tap()
+      case "secondary":
+        coordinate.rightClick()
+      case "middle":
+        throw NSError(
+          domain: "AgentDeviceRunner",
+          code: 1,
+          userInfo: [NSLocalizedDescriptionKey: "middle mouse button is not supported"]
+        )
+      default:
+        throw NSError(
+          domain: "AgentDeviceRunner",
+          code: 1,
+          userInfo: [NSLocalizedDescriptionKey: "unsupported mouse button: \(button)"]
+        )
+      }
+    #else
+      throw NSError(
+        domain: "AgentDeviceRunner",
+        code: 1,
+        userInfo: [NSLocalizedDescriptionKey: "mouseClick is only supported on macOS"]
+      )
+    #endif
+  }
+
   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))
+    let coordinate = interactionCoordinate(app: app, x: x, y: 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))
+    let coordinate = interactionCoordinate(app: app, x: x, y: y)
     coordinate.press(forDuration: duration)
   }
 
@@ -165,9 +204,8 @@ extension RunnerTests {
     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))
+    let start = interactionCoordinate(app: app, x: x, y: y)
+    let end = interactionCoordinate(app: app, x: x2, y: y2)
     start.press(forDuration: holdDuration, thenDragTo: end)
   }
 
@@ -255,4 +293,40 @@ extension RunnerTests {
     center.press(forDuration: 0.05, thenDragTo: endPoint)
   }
 
+  private func interactionRoot(app: XCUIApplication) -> XCUIElement {
+    let windows = app.windows.allElementsBoundByIndex
+    if let window = windows.first(where: { $0.exists && !$0.frame.isEmpty }) {
+      return window
+    }
+    return app
+  }
+
+  private func interactionCoordinate(app: XCUIApplication, x: Double, y: Double) -> XCUICoordinate {
+    let root = interactionRoot(app: app)
+    let origin = root.coordinate(withNormalizedOffset: CGVector(dx: 0, dy: 0))
+    let rootFrame = root.frame
+    let offsetX = x - Double(rootFrame.origin.x)
+    let offsetY = y - Double(rootFrame.origin.y)
+    return origin.withOffset(CGVector(dx: offsetX, dy: offsetY))
+  }
+
+  private func tapElementCenter(app: XCUIApplication, element: XCUIElement) {
+    let frame = element.frame
+    if !frame.isEmpty {
+      tapAt(app: app, x: frame.midX, y: frame.midY)
+      return
+    }
+    element.tap()
+  }
+
+  private func macOSNavigationBackElement(app: XCUIApplication) -> XCUIElement? {
+    let predicate = NSPredicate(
+      format: "identifier == %@ OR label == %@",
+      "go back",
+      "Back"
+    )
+    let element = app.descendants(matching: .any).matching(predicate).firstMatch
+    return element.exists ? element : nil
+  }
+
 }

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

@@ -1,11 +1,31 @@
 import XCTest
-import UIKit
+#if canImport(AppKit)
+import AppKit
+#endif
+
+func runnerPngData(for image: RunnerImage) -> Data? {
+#if canImport(UIKit)
+  return image.pngData()
+#elseif canImport(AppKit)
+  guard let cgImage = runnerCGImage(from: image) else { return nil }
+  let bitmap = NSBitmapImageRep(cgImage: cgImage)
+  return bitmap.representation(using: .png, properties: [:])
+#endif
+}
+
+func runnerCGImage(from image: RunnerImage) -> CGImage? {
+#if canImport(UIKit)
+  return image.cgImage
+#elseif canImport(AppKit)
+  return image.cgImage(forProposedRect: nil, context: nil, hints: nil)
+#endif
+}
 
 extension RunnerTests {
   // MARK: - Recording
 
-  func captureRunnerFrame() -> UIImage? {
-    var image: UIImage?
+  func captureRunnerFrame() -> RunnerImage? {
+    var image: RunnerImage?
     let capture = {
       let screenshot = XCUIScreen.main.screenshot()
       image = screenshot.image
@@ -29,6 +49,11 @@ extension RunnerTests {
   }
 
   func resolveRecordingOutPath(_ requestedOutPath: String) -> String {
+#if os(macOS)
+    if requestedOutPath.hasPrefix("/") {
+      return requestedOutPath
+    }
+#endif
     let fileName = URL(fileURLWithPath: requestedOutPath).lastPathComponent
     let fallbackName = "agent-device-recording-\(Int(Date().timeIntervalSince1970 * 1000)).mp4"
     let safeFileName = fileName.isEmpty ? fallbackName : fileName
@@ -38,12 +63,19 @@ extension RunnerTests {
   // MARK: - Target Activation
 
   func targetNeedsActivation(_ target: XCUIApplication) -> Bool {
-    switch target.state {
-    case .unknown, .notRunning, .runningBackground, .runningBackgroundSuspended:
+    let state = target.state
+#if os(macOS)
+    if state == .unknown || state == .notRunning || state == .runningBackground {
+      return true
+    }
+#else
+    if state == .unknown || state == .notRunning || state == .runningBackground
+      || state == .runningBackgroundSuspended
+    {
       return true
-    default:
-      return false
     }
+#endif
+    return false
   }
 
   func activateTarget(bundleId: String, reason: String) -> XCUIApplication {

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

@@ -2,6 +2,7 @@
 
 enum CommandType: String, Codable {
   case tap
+  case mouseClick
   case tapSeries
   case longPress
   case drag
@@ -36,6 +37,7 @@ struct Command: Codable {
   let action: String?
   let x: Double?
   let y: Double?
+  let button: String?
   let count: Double?
   let intervalMs: Double?
   let doubleTap: Bool?

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

@@ -1,6 +1,5 @@
 import AVFoundation
 import CoreVideo
-import UIKit
 
 extension RunnerTests {
   // MARK: - Screen Recorder
@@ -33,7 +32,7 @@ extension RunnerTests {
       self.fps = fps
     }
 
-    func start(captureFrame: @escaping () -> UIImage?) throws {
+    func start(captureFrame: @escaping () -> RunnerImage?) throws {
       let url = URL(fileURLWithPath: outputPath)
       let directory = url.deletingLastPathComponent()
       try FileManager.default.createDirectory(
@@ -46,10 +45,10 @@ extension RunnerTests {
       }
 
       var dimensions: CGSize = .zero
-      var bootstrapImage: UIImage?
+      var bootstrapImage: RunnerImage?
       let bootstrapDeadline = Date().addingTimeInterval(2.0)
       while Date() < bootstrapDeadline {
-        if let image = captureFrame(), let cgImage = image.cgImage {
+        if let image = captureFrame(), let cgImage = runnerCGImage(from: image) {
           bootstrapImage = image
           dimensions = CGSize(width: cgImage.width, height: cgImage.height)
           break
@@ -183,8 +182,8 @@ extension RunnerTests {
       }
     }
 
-    private func append(image: UIImage) {
-      guard let cgImage = image.cgImage else { return }
+    private func append(image: RunnerImage) {
+      guard let cgImage = runnerCGImage(from: image) else { return }
       lock.lock()
       defer { lock.unlock() }
       if isStopping { return }

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

@@ -1,6 +1,22 @@
 import XCTest
 
 extension RunnerTests {
+  private struct SnapshotTraversalContext {
+    let rootSnapshot: XCUIElementSnapshot
+    let viewport: CGRect
+    let flatSnapshots: [XCUIElementSnapshot]
+    let snapshotRanges: [ObjectIdentifier: (Int, Int)]
+    let maxDepth: Int
+  }
+
+  private struct SnapshotEvaluation {
+    let label: String
+    let identifier: String
+    let valueText: String?
+    let hittable: Bool
+    let visible: Bool
+  }
+
   // MARK: - Snapshot Entry
 
   func elementTypeName(_ type: XCUIElement.ElementType) -> String {
@@ -48,50 +64,19 @@ extension RunnerTests {
       return blocking
     }
 
-    var nodes: [SnapshotNode] = []
-    var truncated = false
-    let maxDepth = options.depth ?? Int.max
-    let viewport = app.frame
-    let queryRoot = options.scope.flatMap { findScopeElement(app: app, scope: $0) } ?? app
-
-    let rootSnapshot: XCUIElementSnapshot
-    do {
-      rootSnapshot = try queryRoot.snapshot()
-    } catch {
-      return DataPayload(nodes: nodes, truncated: truncated)
+    guard let context = makeSnapshotTraversalContext(app: app, options: options) else {
+      return DataPayload(nodes: [], truncated: false)
     }
 
-    let (flatSnapshots, snapshotRanges) = flattenedSnapshots(rootSnapshot)
-    let rootLaterNodes = laterSnapshots(
-      for: rootSnapshot,
-      in: flatSnapshots,
-      ranges: snapshotRanges
-    )
-    let rootLabel = aggregatedLabel(for: rootSnapshot) ?? rootSnapshot.label.trimmingCharacters(in: .whitespacesAndNewlines)
-    let rootIdentifier = rootSnapshot.identifier.trimmingCharacters(in: .whitespacesAndNewlines)
-    let rootValue = snapshotValueText(rootSnapshot)
-    let rootHittable = computedSnapshotHittable(rootSnapshot, viewport: viewport, laterNodes: rootLaterNodes)
+    var nodes: [SnapshotNode] = []
+    var truncated = false
+    let rootEvaluation = evaluateSnapshot(context.rootSnapshot, in: context)
     nodes.append(
-      SnapshotNode(
-        index: 0,
-        type: elementTypeName(rootSnapshot.elementType),
-        label: rootLabel.isEmpty ? nil : rootLabel,
-        identifier: rootIdentifier.isEmpty ? nil : rootIdentifier,
-        value: rootValue,
-        rect: SnapshotRect(
-          x: Double(rootSnapshot.frame.origin.x),
-          y: Double(rootSnapshot.frame.origin.y),
-          width: Double(rootSnapshot.frame.size.width),
-          height: Double(rootSnapshot.frame.size.height)
-        ),
-        enabled: rootSnapshot.isEnabled,
-        hittable: rootHittable,
-        depth: 0
-      )
+      makeSnapshotNode(snapshot: context.rootSnapshot, evaluation: rootEvaluation, depth: 0, index: 0)
     )
 
     var seen = Set<String>()
-    var stack: [(XCUIElementSnapshot, Int, Int)] = rootSnapshot.children.map { ($0, 1, 1) }
+    var stack: [(XCUIElementSnapshot, Int, Int)] = context.rootSnapshot.children.map { ($0, 1, 1) }
 
     while let (snapshot, depth, visibleDepth) = stack.popLast() {
       if nodes.count >= fastSnapshotLimit {
@@ -100,36 +85,24 @@ extension RunnerTests {
       }
       if let limit = options.depth, depth > limit { continue }
 
-      let label = aggregatedLabel(for: snapshot) ?? snapshot.label.trimmingCharacters(in: .whitespacesAndNewlines)
-      let identifier = snapshot.identifier.trimmingCharacters(in: .whitespacesAndNewlines)
-      let valueText = snapshotValueText(snapshot)
-      let laterNodes = laterSnapshots(
-        for: snapshot,
-        in: flatSnapshots,
-        ranges: snapshotRanges
-      )
-      let hittable = computedSnapshotHittable(snapshot, viewport: viewport, laterNodes: laterNodes)
-      let hasContent = !label.isEmpty || !identifier.isEmpty || (valueText != nil)
-      if !isVisibleInViewport(snapshot.frame, viewport) && !hasContent {
-        continue
-      }
-
+      let evaluation = evaluateSnapshot(snapshot, in: context)
       let include = shouldInclude(
         snapshot: snapshot,
-        label: label,
-        identifier: identifier,
-        valueText: valueText,
+        label: evaluation.label,
+        identifier: evaluation.identifier,
+        valueText: evaluation.valueText,
         options: options,
-        hittable: hittable
+        hittable: evaluation.hittable,
+        visible: evaluation.visible
       )
 
-      let key = "\(snapshot.elementType)-\(label)-\(identifier)-\(snapshot.frame.origin.x)-\(snapshot.frame.origin.y)"
+      let key = "\(snapshot.elementType)-\(evaluation.label)-\(evaluation.identifier)-\(snapshot.frame.origin.x)-\(snapshot.frame.origin.y)"
       let isDuplicate = seen.contains(key)
       if !isDuplicate {
         seen.insert(key)
       }
 
-      if depth < maxDepth {
+      if depth < context.maxDepth {
         let nextVisibleDepth = include && !isDuplicate ? visibleDepth + 1 : visibleDepth
         for child in snapshot.children.reversed() {
           stack.append((child, depth + 1, nextVisibleDepth))
@@ -139,21 +112,11 @@ extension RunnerTests {
       if !include || isDuplicate { continue }
 
       nodes.append(
-        SnapshotNode(
-          index: nodes.count,
-          type: elementTypeName(snapshot.elementType),
-          label: label.isEmpty ? nil : label,
-          identifier: identifier.isEmpty ? nil : identifier,
-          value: valueText,
-          rect: SnapshotRect(
-            x: Double(snapshot.frame.origin.x),
-            y: Double(snapshot.frame.origin.y),
-            width: Double(snapshot.frame.size.width),
-            height: Double(snapshot.frame.size.height)
-          ),
-          enabled: snapshot.isEnabled,
-          hittable: hittable,
-          depth: min(maxDepth, visibleDepth)
+        makeSnapshotNode(
+          snapshot: snapshot,
+          evaluation: evaluation,
+          depth: min(context.maxDepth, visibleDepth),
+          index: nodes.count
         )
       )
 
@@ -167,19 +130,12 @@ extension RunnerTests {
       return blocking
     }
 
-    let queryRoot = options.scope.flatMap { findScopeElement(app: app, scope: $0) } ?? app
-    var nodes: [SnapshotNode] = []
-    var truncated = false
-    let viewport = app.frame
-
-    let rootSnapshot: XCUIElementSnapshot
-    do {
-      rootSnapshot = try queryRoot.snapshot()
-    } catch {
-      return DataPayload(nodes: nodes, truncated: truncated)
+    guard let context = makeSnapshotTraversalContext(app: app, options: options) else {
+      return DataPayload(nodes: [], truncated: false)
     }
 
-    let (flatSnapshots, snapshotRanges) = flattenedSnapshots(rootSnapshot)
+    var nodes: [SnapshotNode] = []
+    var truncated = false
 
     func walk(_ snapshot: XCUIElementSnapshot, depth: Int) {
       if nodes.count >= maxSnapshotElements {
@@ -187,37 +143,19 @@ extension RunnerTests {
         return
       }
       if let limit = options.depth, depth > limit { return }
-      if !isVisibleInViewport(snapshot.frame, viewport) { return }
-
-      let label = aggregatedLabel(for: snapshot) ?? snapshot.label.trimmingCharacters(in: .whitespacesAndNewlines)
-      let identifier = snapshot.identifier.trimmingCharacters(in: .whitespacesAndNewlines)
-      let valueText = snapshotValueText(snapshot)
-      let laterNodes = laterSnapshots(
-        for: snapshot,
-        in: flatSnapshots,
-        ranges: snapshotRanges
-      )
-      let hittable = computedSnapshotHittable(snapshot, viewport: viewport, laterNodes: laterNodes)
+
+      let evaluation = evaluateSnapshot(snapshot, in: context)
       if shouldInclude(
         snapshot: snapshot,
-        label: label,
-        identifier: identifier,
-        valueText: valueText,
+        label: evaluation.label,
+        identifier: evaluation.identifier,
+        valueText: evaluation.valueText,
         options: options,
-        hittable: hittable
+        hittable: evaluation.hittable,
+        visible: evaluation.visible
       ) {
         nodes.append(
-          SnapshotNode(
-            index: nodes.count,
-            type: elementTypeName(snapshot.elementType),
-            label: label.isEmpty ? nil : label,
-            identifier: identifier.isEmpty ? nil : identifier,
-            value: valueText,
-            rect: snapshotRect(from: snapshot.frame),
-            enabled: snapshot.isEnabled,
-            hittable: hittable,
-            depth: depth
-          )
+          makeSnapshotNode(snapshot: snapshot, evaluation: evaluation, depth: depth, index: nodes.count)
         )
       }
 
@@ -228,7 +166,7 @@ extension RunnerTests {
       }
     }
 
-    walk(rootSnapshot, depth: 0)
+    walk(context.rootSnapshot, depth: 0)
     return DataPayload(nodes: nodes, truncated: truncated)
   }
 
@@ -249,7 +187,8 @@ extension RunnerTests {
     identifier: String,
     valueText: String?,
     options: SnapshotOptions,
-    hittable: Bool
+    hittable: Bool,
+    visible: Bool
   ) -> Bool {
     let type = snapshot.elementType
     let hasContent = !label.isEmpty || !identifier.isEmpty || (valueText != nil)
@@ -257,6 +196,11 @@ extension RunnerTests {
       if snapshot.children.count <= 1 { return false }
     }
     if options.interactiveOnly {
+      #if os(macOS)
+        if !visible && type != .application {
+          return false
+        }
+      #endif
       if interactiveTypes.contains(type) { return true }
       if hittable && type != .other { return true }
       if hasContent { return true }
@@ -287,6 +231,70 @@ extension RunnerTests {
     return true
   }
 
+  private func makeSnapshotTraversalContext(
+    app: XCUIApplication,
+    options: SnapshotOptions
+  ) -> SnapshotTraversalContext? {
+    let viewport = snapshotViewport(app: app)
+    let queryRoot = options.scope.flatMap { findScopeElement(app: app, scope: $0) } ?? app
+
+    let rootSnapshot: XCUIElementSnapshot
+    do {
+      rootSnapshot = try queryRoot.snapshot()
+    } catch {
+      return nil
+    }
+
+    let (flatSnapshots, snapshotRanges) = flattenedSnapshots(rootSnapshot)
+    return SnapshotTraversalContext(
+      rootSnapshot: rootSnapshot,
+      viewport: viewport,
+      flatSnapshots: flatSnapshots,
+      snapshotRanges: snapshotRanges,
+      maxDepth: options.depth ?? Int.max
+    )
+  }
+
+  private func evaluateSnapshot(
+    _ snapshot: XCUIElementSnapshot,
+    in context: SnapshotTraversalContext
+  ) -> SnapshotEvaluation {
+    let label = aggregatedLabel(for: snapshot) ?? snapshot.label.trimmingCharacters(in: .whitespacesAndNewlines)
+    let identifier = snapshot.identifier.trimmingCharacters(in: .whitespacesAndNewlines)
+    let valueText = snapshotValueText(snapshot)
+    let laterNodes = laterSnapshots(
+      for: snapshot,
+      in: context.flatSnapshots,
+      ranges: context.snapshotRanges
+    )
+    return SnapshotEvaluation(
+      label: label,
+      identifier: identifier,
+      valueText: valueText,
+      hittable: computedSnapshotHittable(snapshot, viewport: context.viewport, laterNodes: laterNodes),
+      visible: isVisibleInViewport(snapshot.frame, context.viewport)
+    )
+  }
+
+  private func makeSnapshotNode(
+    snapshot: XCUIElementSnapshot,
+    evaluation: SnapshotEvaluation,
+    depth: Int,
+    index: Int
+  ) -> SnapshotNode {
+    return SnapshotNode(
+      index: index,
+      type: elementTypeName(snapshot.elementType),
+      label: evaluation.label.isEmpty ? nil : evaluation.label,
+      identifier: evaluation.identifier.isEmpty ? nil : evaluation.identifier,
+      value: evaluation.valueText,
+      rect: snapshotRect(from: snapshot.frame),
+      enabled: snapshot.isEnabled,
+      hittable: evaluation.hittable,
+      depth: depth
+    )
+  }
+
   private func isOccludingType(_ type: XCUIElement.ElementType) -> Bool {
     switch type {
     case .application, .window:
@@ -339,6 +347,18 @@ extension RunnerTests {
     return text.isEmpty ? nil : text
   }
 
+  private func snapshotViewport(app: XCUIApplication) -> CGRect {
+    let windows = app.windows.allElementsBoundByIndex
+    if let window = windows.first(where: { $0.exists && !$0.frame.isNull && !$0.frame.isEmpty }) {
+      return window.frame
+    }
+    let appFrame = app.frame
+    if !appFrame.isNull && !appFrame.isEmpty {
+      return appFrame
+    }
+    return .infinite
+  }
+
   private func aggregatedLabel(for snapshot: XCUIElementSnapshot, depth: Int = 0) -> String? {
     if depth > 4 { return nil }
     let text = snapshot.label.trimmingCharacters(in: .whitespacesAndNewlines)

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

@@ -4,6 +4,9 @@ extension RunnerTests {
   // MARK: - Blocking System Modal Snapshot
 
   func blockingSystemAlertSnapshot() -> DataPayload? {
+    #if os(macOS)
+      return nil
+    #else
     guard let modal = firstBlockingSystemModal(in: springboard) else {
       return nil
     }
@@ -40,6 +43,7 @@ extension RunnerTests {
     }
 
     return DataPayload(nodes: nodes, truncated: false)
+    #endif
   }
 
   private func firstBlockingSystemModal(in springboard: XCUIApplication) -> XCUIElement? {

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

@@ -7,6 +7,13 @@
 
 import XCTest
 import Network
+#if canImport(UIKit)
+import UIKit
+typealias RunnerImage = UIImage
+#elseif canImport(AppKit)
+import AppKit
+typealias RunnerImage = NSImage
+#endif
 
 final class RunnerTests: XCTestCase {
   enum RunnerErrorDomain {
@@ -85,11 +92,7 @@ final class RunnerTests: XCTestCase {
     let queue = DispatchQueue(label: "agent-device.runner")
     let desiredPort = RunnerEnv.resolvePort()
     NSLog("AGENT_DEVICE_RUNNER_DESIRED_PORT=%d", desiredPort)
-    if desiredPort > 0, let port = NWEndpoint.Port(rawValue: desiredPort) {
-      listener = try NWListener(using: .tcp, on: port)
-    } else {
-      listener = try NWListener(using: .tcp)
-    }
+    listener = try makeRunnerListener(desiredPort: desiredPort)
     listener?.stateUpdateHandler = { [weak self] state in
       switch state {
       case .ready:
@@ -123,4 +126,18 @@ final class RunnerTests: XCTestCase {
       XCTFail("runner wait ended with \(result)")
     }
   }
+
+  private func makeRunnerListener(desiredPort: UInt16) throws -> NWListener {
+    if desiredPort > 0, let port = NWEndpoint.Port(rawValue: desiredPort) {
+      #if os(macOS)
+        let parameters = NWParameters.tcp
+        parameters.allowLocalEndpointReuse = true
+        parameters.requiredLocalEndpoint = .hostPort(host: "127.0.0.1", port: port)
+        return try NWListener(using: parameters)
+      #else
+        return try NWListener(using: .tcp, on: port)
+      #endif
+    }
+    return try NWListener(using: .tcp)
+  }
 }