@swmansion/argent 0.31.2-next.3 → 0.31.2-next.4

package/dist/ios-device-runner/ArgentRunner/ArgentRunnerUITests/ArgentExceptionGuard.h

@@ -11,6 +11,9 @@ NS_ASSUME_NONNULL_BEGIN
 /// Returns nil when the block completed, otherwise "Name: reason".
 + (NSString *_Nullable)runCatching:(NS_NOESCAPE dispatch_block_t)block;
 
+/// Returns nil when the block completed, otherwise the exception it raised.
++ (NSException *_Nullable)exceptionFrom:(NS_NOESCAPE dispatch_block_t)block;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/dist/ios-device-runner/ArgentRunner/ArgentRunnerUITests/ArgentExceptionGuard.m

@@ -3,13 +3,21 @@
 @implementation ArgentExceptionGuard
 
 + (NSString *_Nullable)runCatching:(NS_NOESCAPE dispatch_block_t)block {
+  NSException *exception = [self exceptionFrom:block];
+  if (exception == nil) {
+    return nil;
+  }
+  NSString *name = exception.name ?: @"NSException";
+  NSString *reason = exception.reason ?: @"unhandled Objective-C exception";
+  return [NSString stringWithFormat:@"%@: %@", name, reason];
+}
+
++ (NSException *_Nullable)exceptionFrom:(NS_NOESCAPE dispatch_block_t)block {
   @try {
     block();
     return nil;
   } @catch (NSException *exception) {
-    NSString *name = exception.name ?: @"NSException";
-    NSString *reason = exception.reason ?: @"unhandled Objective-C exception";
-    return [NSString stringWithFormat:@"%@: %@", name, reason];
+    return exception;
   }
 }
 

package/dist/ios-device-runner/ArgentRunner/ArgentRunnerUITests/ArgentRunnerSession+Gestures.swift

@@ -21,10 +21,10 @@ extension ArgentRunnerSession {
 
     /// Taps at the wire coordinates: one tap, the native double-tap when
     /// `numberOfTaps` is 2, or a loop of single taps above that. XCUICoordinate
-    /// has no N-tap API, and the loop is not one gesture on hardware: each tap
-    /// is its own synthesized event behind XCTest's idle wait and an XPC round
-    /// trip, hundreds of milliseconds apart, so the taps land separately and do
-    /// not trigger a multi-tap recognizer. That is documented, not refused.
+    /// has no N-tap API, and the loop is not one gesture: each tap is its own
+    /// synthesized event and XPC round trip, about 300 ms apart on a
+    /// simulator, which a double-tap recognizer can still pair. That is
+    /// documented, not refused.
     func performTap(_ request: CommandRequest, on app: XCUIApplication)
         -> Envelope
     {
@@ -39,15 +39,17 @@ extension ArgentRunnerSession {
 
         let coordinate = point(app, x, y, relativeTo: app.frame.origin)
 
-        switch taps {
-        case 1:
-            coordinate.tap()
-        case 2:
-            coordinate.doubleTap()
-        default:
-            // Separate taps, not one gesture (see the doc comment above).
-            for _ in 0..<taps {
+        skippingQuiescence(of: app) {
+            switch taps {
+            case 1:
                 coordinate.tap()
+            case 2:
+                coordinate.doubleTap()
+            default:
+                // Separate taps, not one gesture (see the doc comment above).
+                for _ in 0..<taps {
+                    coordinate.tap()
+                }
             }
         }
 
@@ -63,7 +65,11 @@ extension ArgentRunnerSession {
         }
 
         let seconds = max(0.05, (request.durationMs ?? 800) / 1000)
-        point(app, x, y, relativeTo: app.frame.origin).press(forDuration: seconds)
+        let coordinate = point(app, x, y, relativeTo: app.frame.origin)
+
+        skippingQuiescence(of: app) {
+            coordinate.press(forDuration: seconds)
+        }
 
         return .success(MessagePayload(message: "long-pressed"))
     }
@@ -112,12 +118,14 @@ extension ArgentRunnerSession {
             velocity = .default
         }
 
-        start.press(
-            forDuration: startHold,
-            thenDragTo: end,
-            withVelocity: velocity,
-            thenHoldForDuration: endHold
-        )
+        skippingQuiescence(of: app) {
+            start.press(
+                forDuration: startHold,
+                thenDragTo: end,
+                withVelocity: velocity,
+                thenHoldForDuration: endHold
+            )
+        }
 
         return .success(MessagePayload(message: "dragged"))
     }

package/dist/ios-device-runner/ArgentRunner/ArgentRunnerUITests/ArgentRunnerSession+Quiescence.swift

@@ -0,0 +1,95 @@
+import XCTest
+
+/// XCTest waits up to 60s before and after every synthesized event for the
+/// app to report idle. A screen that never does, such as one holding a paused
+/// UIViewPropertyAnimator (expo-blur), stalls each gesture for two minutes,
+/// past its watchdog budget. The runner skips those waits and runs XCTest's
+/// idle check itself under a short cap. Every API here is XCTest SPI, probed
+/// before use: when any is missing, the event runs with XCTest's own waits.
+extension ArgentRunnerSession {
+    /// The longest a gesture waits for the app to go idle before its event.
+    /// Covers a navigation transition, so a gesture sent right after the one
+    /// that started it lands on the new screen instead of mid-transition.
+    static let preEventSettleTimeout: TimeInterval = 2
+
+    private static let performWithInteractionOptions = NSSelectorFromString(
+        "_performWithInteractionOptions:block:"
+    )
+    /// Bit 1 skips the pre-event wait, bit 2 the post-event one.
+    private static let skipQuiescenceOptions: UInt32 = 0b11
+
+    private static let applicationImpl = NSSelectorFromString("applicationImpl")
+    private static let currentProcess = NSSelectorFromString("currentProcess")
+    private static let initiateQuiescenceChecks = NSSelectorFromString(
+        "_initiateQuiescenceChecksIncludingAnimationsIdle:"
+    )
+    private static let makeQuiescenceExpectation = NSSelectorFromString(
+        "_makeQuiescenceExpectation"
+    )
+
+    /// Waits at most `preEventSettleTimeout` for `app` to go idle, then runs
+    /// `body`, which synthesizes events into it, without XCTest's waits.
+    func skippingQuiescence(of app: XCUIApplication, _ body: () -> Void) {
+        let selector = Self.performWithInteractionOptions
+
+        guard app.responds(to: selector),
+            awaitQuiescence(of: app, timeout: Self.preEventSettleTimeout)
+        else {
+            body()
+            return
+        }
+
+        typealias Perform = @convention(c) (
+            NSObject, Selector, UInt32, @convention(block) () -> Void
+        ) -> Void
+        let perform = unsafeBitCast(app.method(for: selector), to: Perform.self)
+
+        // XCTest restores the prior options only when the block returns, and
+        // every XCUIApplication for this bundle id shares them, so an
+        // exception must not unwind through it.
+        var exception: NSException?
+        withoutActuallyEscaping(body) { body in
+            perform(app, selector, Self.skipQuiescenceOptions) {
+                exception = ArgentExceptionGuard.exception(from: body)
+            }
+        }
+        exception?.raise()
+    }
+
+    /// XCTest's own idle check (event loop and animations), under `timeout`.
+    /// False when any SPI it needs is missing.
+    private func awaitQuiescence(of app: XCUIApplication, timeout: TimeInterval)
+        -> Bool
+    {
+        guard
+            let impl = Self.object(app, Self.applicationImpl),
+            let process = Self.object(impl, Self.currentProcess),
+            process.responds(to: Self.initiateQuiescenceChecks)
+        else {
+            return false
+        }
+
+        typealias Initiate = @convention(c) (NSObject, Selector, Bool) -> Void
+        let initiate = unsafeBitCast(
+            process.method(for: Self.initiateQuiescenceChecks),
+            to: Initiate.self
+        )
+        initiate(process, Self.initiateQuiescenceChecks, true)
+
+        guard
+            let expectation = Self.object(process, Self.makeQuiescenceExpectation)
+                as? XCTestExpectation
+        else {
+            return false
+        }
+
+        _ = XCTWaiter.wait(for: [expectation], timeout: timeout)
+        return true
+    }
+
+    /// The object a zero-argument getter returns, or nil when `target` lacks it.
+    private static func object(_ target: NSObject, _ getter: Selector) -> NSObject? {
+        guard target.responds(to: getter) else { return nil }
+        return target.perform(getter)?.takeUnretainedValue() as? NSObject
+    }
+}

package/dist/ios-device-runner/ArgentRunner/ArgentRunnerUITests/ArgentRunnerSession+TextEntry.swift

@@ -77,7 +77,7 @@ extension ArgentRunnerSession {
                 app.keyboards.keys.matching(submitKey).firstMatch,
             ] where candidate.exists && candidate.isHittable {
                 let label = candidate.label
-                candidate.tap()
+                skippingQuiescence(of: app) { candidate.tap() }
 
                 return .success(
                     MessagePayload(message: "pressed keyboard \(label)")
@@ -131,7 +131,7 @@ extension ArgentRunnerSession {
         }
 
         let exceptionDescription = ArgentExceptionGuard.runCatching {
-            app.typeText(text)
+            self.skippingQuiescence(of: app) { app.typeText(text) }
         }
 
         if let exceptionDescription {

package/dist/ios-device-runner/ArgentRunner/ArgentRunnerUITests/RunnerProtocol.swift

@@ -70,10 +70,10 @@ extension CommandKind {
         switch self {
         // XCTest types long strings in real time, so typing needs extra room.
         case .type: return 55
-        // Gestures must outlast XCTest's ~60s pre-event idle wait. A screen that
-        // never reports quiescent stalls the wait until XCTest gives up and
-        // synthesizes the event anyway, and a shorter budget would abandon a
-        // command that still completes.
+        // tap, longPress and drag outlast XCTest's ~60s pre-event idle wait,
+        // which runs where the runner cannot skip it
+        // (ArgentRunnerSession+Quiescence.swift). touchPaths never waits for
+        // idle but shares the gesture budget.
         case .tap, .longPress, .drag, .touchPaths: return 75
         default: return 30
         }
@@ -117,7 +117,7 @@ struct CommandRequest: Codable {
     let y: Double?
     /// `tap`: number of taps. Defaults to 1; 2 is the native double-tap.
     /// Higher counts loop single taps on the device: there is no native N-tap
-    /// API, so they land as separate taps, not one multi-tap gesture.
+    /// API, so they are not one multi-tap gesture.
     let numberOfTaps: Int?
     /// `drag`: absolute start and end points.
     let fromX: Double?

package/dist/tool-args.generated.d.ts

@@ -408,7 +408,7 @@ export interface ArgentToolArgs {
         x: number;
         /** Normalized vertical position 0.0–1.0 (top=0, bottom=1), not pixels */
         y: number;
-        /** Number of taps/clicks dispatched as ONE multi-tap gesture (2 = double-tap / double-click). The taps land inside the OS double-tap window; on Chromium each click carries an escalating CDP clickCount so dblclick actually fires; on physical iOS 2 is the native double-tap and higher counts land as separate taps. On HarmonyOS only 2 is one gesture; 3 or more are separate injections a device round trip apart, which the OS reads as single taps. Default 1. */
+        /** Number of taps/clicks dispatched as ONE multi-tap gesture (2 = double-tap / double-click). The taps land inside the OS double-tap window; on Chromium each click carries an escalating CDP clickCount so dblclick actually fires; on physical iOS 2 is the native double-tap and higher counts loop single taps, which a double-tap recognizer may pair. On HarmonyOS only 2 is one gesture; 3 or more are separate injections a device round trip apart, which the OS reads as single taps. Default 1. */
         clickCount?: number;
     };
     keyboard: {

package/dist/tool-server.cjs

@@ -142136,7 +142136,7 @@ var zodSchema17 = external_exports.object({
   x: external_exports.number().min(0).max(1).describe("Normalized horizontal position 0.0\u20131.0 (left=0, right=1), not pixels"),
   y: external_exports.number().min(0).max(1).describe("Normalized vertical position 0.0\u20131.0 (top=0, bottom=1), not pixels"),
   clickCount: external_exports.number().int().min(1).max(10).optional().describe(
-    "Number of taps/clicks dispatched as ONE multi-tap gesture (2 = double-tap / double-click). The taps land inside the OS double-tap window; on Chromium each click carries an escalating CDP clickCount so dblclick actually fires; on physical iOS 2 is the native double-tap and higher counts land as separate taps. <flag:harmonyos>On HarmonyOS only 2 is one gesture; 3 or more are separate injections a device round trip apart, which the OS reads as single taps. </flag:harmonyos>Default 1."
+    "Number of taps/clicks dispatched as ONE multi-tap gesture (2 = double-tap / double-click). The taps land inside the OS double-tap window; on Chromium each click carries an escalating CDP clickCount so dblclick actually fires; on physical iOS 2 is the native double-tap and higher counts loop single taps, which a double-tap recognizer may pair. <flag:harmonyos>On HarmonyOS only 2 is one gesture; 3 or more are separate injections a device round trip apart, which the OS reads as single taps. </flag:harmonyos>Default 1."
   )
 });
 function tapDescription(params, tense) {
@@ -142209,6 +142209,9 @@ Returns { tapped: true, timestampMs }. On physical iOS, reactivated: true = app
 On a physical iPhone use \`describe\`; \`native-describe-screen\` is simulator-only.
 Before tapping, determine the correct coordinates by using discovery tools. Pick by platform: iOS / Android use \`describe\`, \`native-describe-screen\`, or \`debugger-component-tree\`; Chromium uses \`describe\` (the DOM walker)<flag:harmonyos> and HarmonyOS uses \`describe\` (the \`uitest\` layout dump)</flag:harmonyos>, since the native and RN-specific discovery tools don't apply<flag:harmonyos> to either</flag:harmonyos>. More information in \`argent-device-interact\` skill`,
   alwaysLoad: true,
+  // A physical iPhone's first call waits out the runner build, past the MCP fetch timeout,
+  // whose abort replays the call: the gesture would land once per replay.
+  longRunning: true,
   searchHint: "tap press button element device simulator emulator chromium touch down up click",
   zodSchema: zodSchema17,
   capability: capability9,
@@ -142336,6 +142339,9 @@ Physical iOS: an edge gesture (back-swipe) needs fromX 0 exactly; durationMs set
 HarmonyOS: durationMs sets drag speed, clamped to uitest's 200-40000 px/s, so a short slow swipe ends early and a long fast one runs late.</flag:harmonyos>
 Pass momentum:false for a momentum-free swipe that lands where the finger lifts (little to no fling at the 300 default), when you need a deterministic scroll distance; it needs durationMs >= 150 and is rejected below that, a shorter ease-out leaving the OS too little wall clock to read the deceleration as a stop. At 150 it lands short of the lift point instead, and 2 of 47 runs still flung backwards. A plain swipe takes any duration up to 10000ms and is delivered as close to the speed it was authored as a 16ms frame allows: below ~32ms the whole travel lands in one or two frames, which the OS flings as hard as it flings anything. Returns { swiped: true, timestampMs }. On physical iOS, reactivated: true = app was re-fronted; re-describe. Fails if the simulator-server / emulator backend<flag:harmonyos>, or \`hdc\` on HarmonyOS,</flag:harmonyos> is not reachable for the given device.`,
   alwaysLoad: true,
+  // A physical iPhone's first call waits out the runner build, past the MCP fetch timeout,
+  // whose abort replays the call: the gesture would land once per replay.
+  longRunning: true,
   searchHint: "swipe scroll drag pan gesture device simulator emulator touch move",
   zodSchema: zodSchema18,
   capability: capability10,
@@ -142893,6 +142899,9 @@ Example pinch-to-zoom (with interpolate:10 for smoothness):
   interpolate: 10`,
   zodSchema: zodSchema21,
   capability: capability13,
+  // A physical iPhone's first call waits out the runner build, past the MCP fetch timeout,
+  // whose abort replays the call: the gesture would land once per replay.
+  longRunning: true,
   // Declare the runner only for a train execute can play. A rejected train must not pay a runner cold start.
   services: (params) => {
     const device = resolveDevice(params.udid);
@@ -142980,6 +142989,9 @@ Auto-generates interpolated frames at ~60fps<flag:harmonyos> on iOS and Android;
 Use when you need to zoom in or out on a map, image, or zoomable view. Physical iPhones play both fingers through the runner as one event stream. Returns { pinched: true, timestampMs }. On physical iOS, reactivated: true = app was re-fronted; re-describe. Fails if the simulator-server / emulator backend<flag:harmonyos>, or \`hdc\` on HarmonyOS,</flag:harmonyos> is not reachable for the given device, or on a physical iPhone when the app is not drawn in portrait.`,
   zodSchema: zodSchema22,
   capability: capability14,
+  // A physical iPhone's first call waits out the runner build, past the MCP fetch timeout,
+  // whose abort replays the call: the gesture would land once per replay.
+  longRunning: true,
   services: (params) => {
     const device = resolveDevice(params.udid);
     if (device.platform === "harmony") return {};
@@ -143115,6 +143127,9 @@ Use when you need to rotate a map, image picker, or any rotateable UI element. R
 Size the orbit with radius, or with radiusX and radiusY together (the pair overrides radius); one half of the pair alone, or none of the three, is rejected.`,
   zodSchema: zodSchema23,
   capability: capability15,
+  // A physical iPhone's first call waits out the runner build, past the MCP fetch timeout,
+  // whose abort replays the call: the gesture would land once per replay.
+  longRunning: true,
   services: (params) => {
     const device = resolveDevice(params.udid);
     return isIosPhysicalDevice(device) ? { iosDeviceRunner: iosDeviceRunnerRef(device) } : { simulatorServer: simulatorServerRef(device) };
@@ -143238,6 +143253,9 @@ Returns { pressed: buttonName }.
 Fails if the device backend is not reachable: the simulator-server for iOS, <flag:harmonyos>\`hdc\` for HarmonyOS, </flag:harmonyos>or \`adb\` for Android (Android presses are injected with \`adb shell input keyevent\`).`,
   zodSchema: zodSchema24,
   capability: capability16,
+  // A physical iPhone's first call waits out the runner build, past the MCP fetch timeout,
+  // whose abort replays the call: the press would land once per replay.
+  longRunning: true,
   // Declare only the service the resolved path actually consumes. The Android
   // path uses `adb`, so a sim-server here would spawn a service the tool never
   // uses (up to a 30s ready-wait) and could throw ServiceInitializationError

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.31.2-next.3",
+  "version": "0.31.2-next.4",
   "mcpName": "io.github.software-mansion/argent",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",