agent-device 0.20.10 → 0.21.1

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedTextEntry.swift

@@ -1,7 +1,7 @@
 import XCTest
 
-// AX-independent text synthesis: private-XCTest boundary, pacing plan, and route policy.
-// The verified XCUIElement path remains in TextEntry/TextTyping.
+
+
 extension RunnerTests {
   enum SynthesizedReplacementRouteOutcome {
     case notApplicable
@@ -40,9 +40,14 @@ extension RunnerTests {
       replacingExistingText: Bool
     ) -> SynthesizedTextEntryAction {
 #if os(iOS)
+      let postStartedAt = Date()
       let result = replacingExistingText
         ? RunnerSynthesizedTextEntry.replaceText(withApplication: app, text: text)
         : RunnerSynthesizedTextEntry.synthesizeText(withApplication: app, text: text)
+      NSLog(
+        "[DEBUG-1874] synthesize posted %d chars status=%d tookMs=%.0f",
+        text.count, result.status.rawValue, postStartedAt.timeIntervalSinceNow * -1000
+      )
       return Self.action(status: result.status, message: result.message)
 #else
       return .fallback
@@ -122,6 +127,17 @@ extension RunnerTests {
         sleepFor(request.delaySeconds)
       }
     }
+
+
+
+
+
+
+    let commit = awaitSynthesizedReplacementCommit(
+      app: request.app,
+      target: request.target,
+      expectedText: request.text
+    )
     logTextEntryPhase(
       commandId: request.commandId,
       phase: "total",
@@ -135,7 +151,8 @@ extension RunnerTests {
         repaired: false,
         expectedText: request.text,
         observedText: nil,
-        textEntryRoute: "synthesized-first-responder-replacement"
+        textEntryRoute: "synthesized-first-responder-replacement",
+        failure: Self.textEntryFailure(forCommitOutcome: commit)
       )
     )
 #else
@@ -165,12 +182,12 @@ extension RunnerTests {
     case diverged
   }
 
-  // The private synthesize call returns once the event record is posted, not once the target
-  // app has committed the characters, so intermediate reads walk prefix-by-prefix toward the
-  // expected value. Anything off that prefix path means the app transformed the input
-  // (formatter, mid-text caret, autocomplete) and the runner must not second-guess it. An
-  // unreadable value — secure field, or the element stopped resolving — ends the wait the
-  // same way.
+
+
+
+
+
+
   static func synthesizedTextCommitProgress(
     observedText: String?,
     expectedText: String
@@ -184,35 +201,140 @@ extension RunnerTests {
     return expectedText.hasPrefix(observedText) ? .pending : .diverged
   }
 
-  /// Blocks until the synthesized bare-type text is observable in the target field, so `type`
-  /// cannot report ok while trailing characters are still uncommitted on a slow simulator.
-  ///
-  /// Observation only. A stalled prefix cannot be told apart from a suffix still queued in the
-  /// event stream, so re-synthesizing the difference risks committing it twice after the command
-  /// already reported success. Text carrying a submit key is skipped outright: the app may clear
-  /// or rewrite the field on submit, so `textBefore + typedText` is not the value to wait for.
-  func awaitSynthesizedFirstResponderCommit(
-    app: XCUIApplication,
-    target: TextEntryTarget,
-    textBefore: String?,
-    typedText: String
-  ) {
-    guard let textBefore, !typedText.contains("\n"), !typedText.contains("\r") else {
-      return
+
+
+
+  static func commonPrefixLength(_ lhs: String, _ rhs: String) -> Int {
+    var length = 0
+    for (l, r) in zip(lhs, rhs) {
+      if l != r { break }
+      length += 1
     }
-    let expectedText = textBefore + typedText
-    let deadline = Date().addingTimeInterval(TextEntryTiming.synthesizedCommitTimeout)
-    while Date() < deadline {
-      let observedText = editableTextValue(
-        for: resolveTextEntryElement(app: app, target: target),
-        treatingPlaceholderAsEmpty: true
-      )
-      switch Self.synthesizedTextCommitProgress(observedText: observedText, expectedText: expectedText) {
+    return length
+  }
+
+
+
+
+
+
+  enum SynthesizedTextCommitOutcome: Equatable {
+
+
+
+
+
+    case settled
+
+    case unobservable
+
+    case notObserved
+  }
+
+
+
+
+
+
+
+
+
+  static func awaitSynthesizedCommitOutcome(
+    expectedText: String,
+    placeholder: String?,
+    stallBudget: TimeInterval = TextEntryTiming.synthesizedCommitStallTimeout,
+    ceiling: TimeInterval = TextEntryTiming.synthesizedCommitCeiling,
+    now: () -> Date = { Date() },
+    observe: () -> String?,
+    waitForNextObservation: () -> Void
+  ) -> SynthesizedTextCommitOutcome {
+
+
+
+    if Self.textMatchesPlaceholder(expectedText, placeholder: placeholder) {
+      return .notObserved
+    }
+    var deadline = SynthesizedCommitDeadline(startedAt: now(), stallBudget: stallBudget, ceiling: ceiling)
+
+
+
+    while true {
+      let observedText = observe()
+      switch synthesizedTextCommitProgress(observedText: observedText, expectedText: expectedText) {
       case .committed, .diverged:
-        return
+        return .settled
       case .pending:
-        sleepFor(TextEntryTiming.pollInterval)
+
+
+        let sampledAt = now()
+        deadline.record(
+          expectedPrefixLength: Self.commonPrefixLength(observedText ?? "", expectedText),
+          at: sampledAt
+        )
+        if deadline.isExpired(at: sampledAt) { return .notObserved }
+        waitForNextObservation()
+      }
+    }
+  }
+
+
+
+
+  static func textEntryFailure(
+    forCommitOutcome outcome: SynthesizedTextCommitOutcome
+  ) -> TextEntryFailure? {
+    switch outcome {
+    case .settled, .unobservable:
+      return nil
+    case .notObserved:
+      return .commitNotObserved
+    }
+  }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+  static func awaitSynthesizedReplacementCommitOutcome(
+    expectedText: String,
+    placeholder: String?,
+    stallBudget: TimeInterval = TextEntryTiming.synthesizedCommitStallTimeout,
+    ceiling: TimeInterval = TextEntryTiming.synthesizedCommitCeiling,
+    now: () -> Date = { Date() },
+    observe: () -> String?,
+    waitForNextObservation: () -> Void
+  ) -> SynthesizedTextCommitOutcome {
+    if Self.textMatchesPlaceholder(expectedText, placeholder: placeholder) {
+      return .notObserved
+    }
+    var deadline = SynthesizedCommitDeadline(startedAt: now(), stallBudget: stallBudget, ceiling: ceiling)
+    while true {
+      let observedText = observe()
+      if observedText == expectedText {
+        return .settled
       }
+
+
+
+      let sampledAt = now()
+      deadline.record(
+        expectedPrefixLength: Self.commonPrefixLength(observedText ?? "", expectedText),
+        at: sampledAt
+      )
+      if deadline.isExpired(at: sampledAt) { return .notObserved }
+      waitForNextObservation()
     }
   }
 

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SystemModal.swift

@@ -1,7 +1,8 @@
 import XCTest
+import AgentDeviceSnapshotPresentation
 
 extension RunnerTests {
-  // MARK: - Blocking System Modal Snapshot
+
 
   func blockingSystemAlertSnapshot(deadline: Date = .distantFuture) -> DataPayload? {
     #if os(macOS)
@@ -41,8 +42,8 @@ extension RunnerTests {
       nodes.append(actionNode)
     }
 
-    // Action controls are the interaction contract. Informative text is useful context, but
-    // must not make a usable modal miss the bounded system-modal probe deadline.
+
+
     let contentDeadline = deadline.addingTimeInterval(-0.5)
     for content in informativeElements(in: modal, deadline: contentDeadline) {
       guard Date() < contentDeadline,
@@ -85,7 +86,7 @@ extension RunnerTests {
       }
     }
 
-    // Don't start the second (sheet) enumeration once the shared probe deadline is spent (#1244).
+
     if Date() >= deadline {
       NSLog("AGENT_DEVICE_RUNNER_SYSTEM_MODAL_PROBE_DEADLINE stage=sheets")
       return nil

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextEntry.swift

@@ -1,12 +1,13 @@
 import XCTest
 
-// Text entry & keyboard-readiness for the runner: the focus -> type -> verify -> repair
-// pipeline, readiness polling, and field clearing. Behavior-preserving extraction from
-// RunnerTests+Interaction.swift (no logic changes) to keep that file navigable.
+
+
+
 extension RunnerTests {
   enum TextEntryFailure: String {
     case notFocused = "TEXT_INPUT_NOT_FOCUSED"
     case synthesisUnavailable = "TEXT_INPUT_SYNTHESIS_UNAVAILABLE"
+    case commitNotObserved = "TEXT_INPUT_COMMIT_NOT_OBSERVED"
 
     var message: String {
       switch self {
@@ -14,6 +15,8 @@ extension RunnerTests {
         return "No focused text input was available for typing."
       case .synthesisUnavailable:
         return "Reliable text synthesis is unavailable while the software keyboard is hidden."
+      case .commitNotObserved:
+        return "The runner could not confirm the typed text reached the field."
       }
     }
 
@@ -23,6 +26,8 @@ extension RunnerTests {
         return "Focus a visible text input, then retry type or fill. If the input is not exposed by accessibility, use a coordinate focus command before typing."
       case .synthesisUnavailable:
         return "Show the software keyboard, then retry type or fill."
+      case .commitNotObserved:
+        return "The field may hold none, part, or all of the text. Run snapshot -i and inspect the field: if it already matches, continue; otherwise retry fill with the full text quoted and --delay-ms 80. Do not use type, which appends to whatever committed."
       }
     }
   }
@@ -40,7 +45,15 @@ extension RunnerTests {
     static let pollInterval: TimeInterval = 0.02
     static let warmupValueTimeout: TimeInterval = 0.4
     static let verificationStabilityWindow: TimeInterval = 0.2
-    static let synthesizedCommitTimeout: TimeInterval = 3.0
+
+
+
+    static let synthesizedCommitStallTimeout: TimeInterval = 3.0
+
+
+
+    static let synthesizedCommitCeiling: TimeInterval = 10.0
+    static let synthesizedCommitPollInterval: TimeInterval = 0.2
   }
 
   struct TextEntryResult {
@@ -101,14 +114,14 @@ extension RunnerTests {
   }
 
   func clearTextInput(_ element: XCUIElement) {
-    // Skip the clear (delete burst + moveCaretToEnd edge-tap) ONLY when we can confirm the
-    // field is empty. Why skip: the edge-tap computes a point from the element frame, which can
-    // be stale after the field repositions on focus (e.g. the Settings search bar jumps
-    // bottom->top and reveals a "Suggestions" list) — tapping there navigates away instead of
-    // clearing; and replacing into an already-empty field is a no-op anyway.
-    // editableTextValue returns nil for secure (and unknown) fields, where we CANNOT confirm
-    // emptiness — those must still be cleared, or replace would concatenate stale + new text.
-    // So distinguish nil (clear) from "" (skip).
+
+
+
+
+
+
+
+
     if let existing = editableTextValue(for: element, treatingPlaceholderAsEmpty: true),
        existing.isEmpty {
       return
@@ -121,211 +134,6 @@ extension RunnerTests {
     element.typeText(deletes)
   }
 
-  func focusedTextInput(app: XCUIApplication) -> XCUIElement? {
-#if os(iOS)
-    // iOS focus predicates can return stale or misleading text-input matches
-    // under XCUITest, so text entry readiness is driven by tap/keyboard state.
-    return nil
-#else
-    return safely("FOCUSED_INPUT_QUERY") {
-      let candidates = app
-        .descendants(matching: .any)
-        .matching(NSPredicate(format: "hasKeyboardFocus == 1"))
-        .allElementsBoundByIndex
-      for candidate in candidates where candidate.exists {
-        switch candidate.elementType {
-        case .textField, .secureTextField, .searchField, .textView:
-          return candidate
-        default:
-          continue
-        }
-      }
-      return nil
-    }
-#endif
-  }
-
-  func rememberTextEntryTap(_ element: XCUIElement?) {
-    guard let element, isTextEntryElement(element) else {
-      clearRememberedTextEntryTap()
-      return
-    }
-    textEntryTapWitness = TextEntryTapWitness(
-      element: element,
-      bundleId: currentBundleId,
-      processIdentifier: currentAppProcessIdentifier
-    )
-  }
-
-  func clearRememberedTextEntryTap() {
-    textEntryTapWitness = nil
-  }
-
-  private func rememberedTextEntryTarget() -> TextEntryTarget? {
-    guard let witness = textEntryTapWitness else {
-      return nil
-    }
-    // The tap is proof for one immediately-following bare type only. Consume it before checking
-    // the element so a failed or interrupted type cannot reuse stale focus evidence.
-    clearRememberedTextEntryTap()
-    guard witness.matches(
-      bundleId: currentBundleId,
-      processIdentifier: currentAppProcessIdentifier
-    ) else {
-      return nil
-    }
-    let element = witness.element
-    // XCUIElement is query-backed rather than a stable node identity. A same-identifier field
-    // introduced by app-side navigation between tap and this immediate type can therefore
-    // re-resolve here; keep the witness one-shot and fail closed on every observable identity
-    // boundary instead of using frame equality, which would reject legitimate layout changes.
-    guard safely("LAST_TAPPED_TEXT_INPUT_EXISTS", false, { element.exists }) else {
-      return nil
-    }
-    // Keep the target scoped to the element that the preceding tap actually selected. Do not
-    // attach a refresh point: if that element disappeared, bare type must fail closed rather
-    // than rediscovering a different field or dispatching unscoped app.typeText.
-    return TextEntryTarget(
-      element: element,
-      refreshPoint: nil,
-      prefersFocusedElement: false,
-      fromTapWitness: true
-    )
-  }
-
-  func stabilizeTextInputBeforeTyping(
-    app: XCUIApplication,
-    target: XCUIElement?,
-    keyboardVisibleBeforeTap: Bool? = nil
-  ) -> TextEntryStabilization {
-#if os(tvOS)
-    return TextEntryStabilization(element: target, focusConfirmed: true)
-#else
-    let latest = target
-    let keyboardVisibleAtEntry = keyboardVisibleBeforeTap ?? isKeyboardVisible(app: app)
-    let deadline = Date().addingTimeInterval(TextEntryTiming.focusTimeout)
-    while Date() < deadline {
-      if let focused = focusedTextInput(app: app) {
-        return TextEntryStabilization(element: focused, focusConfirmed: true)
-      }
-      // focusedTextInput is intentionally nil on iOS; treat the keyboard transitioning to
-      // visible after our tap as the focus-moved signal. Don't fast-path when it was already up.
-      if keyboardBecameVisible(app: app, wasVisibleAtEntry: keyboardVisibleAtEntry) {
-        return TextEntryStabilization(element: latest, focusConfirmed: true)
-      }
-      sleepFor(TextEntryTiming.pollInterval)
-    }
-    return TextEntryStabilization(element: latest, focusConfirmed: false)
-#endif
-  }
-
-  func focusTextInputForTextEntry(app: XCUIApplication, x: Double?, y: Double?) -> TextEntryTarget {
-    guard let x, let y else {
-      let softwareKeyboardVisible = isKeyboardVisible(app: app)
-      if !softwareKeyboardVisible, let rememberedTarget = rememberedTextEntryTarget() {
-        return rememberedTarget
-      }
-      // Bare `type` targets the current first responder. On iOS we intentionally do not trust
-      // `hasKeyboardFocus`, but an already-visible software keyboard is sufficient evidence that
-      // app.typeText has a receiver; waiting the full readiness timeout cannot prove a stronger
-      // target because there is no selector/coordinate focus move to validate.
-      if softwareKeyboardVisible {
-        return TextEntryTarget(
-          element: focusedTextInput(app: app),
-          refreshPoint: nil,
-          prefersFocusedElement: true
-        )
-      }
-      let focused = waitForTextEntryReadiness(
-        app: app,
-        target: TextEntryTarget(
-          element: focusedTextInput(app: app),
-          refreshPoint: nil,
-          prefersFocusedElement: true
-        )
-      )
-      return TextEntryTarget(element: focused, refreshPoint: nil, prefersFocusedElement: true)
-    }
-
-    let keyboardVisibleBeforeTap = isKeyboardVisible(app: app)
-    let target = textInputAt(app: app, x: x, y: y)
-    let requestedPoint = CGPoint(x: x, y: y)
-    if let target {
-      let frame = target.frame
-      if !frame.isEmpty {
-        _ = tapAt(app: app, x: frame.midX, y: frame.midY)
-      } else {
-        _ = tapAt(app: app, x: x, y: y)
-      }
-    } else {
-      _ = tapAt(app: app, x: x, y: y)
-    }
-    // A visible keyboard is not enough evidence for app.typeText, because focus may still
-    // belong to a previous field. With a concrete target we type through XCUIElement.typeText,
-    // so after tapping it the iOS readiness timeout cannot prove anything stronger.
-    if keyboardVisibleBeforeTap, let target {
-      return TextEntryTarget(
-        element: target,
-        refreshPoint: textEntryRefreshPoint(for: target) ?? requestedPoint,
-        prefersFocusedElement: false
-      )
-    }
-    let stabilized = stabilizeTextInputBeforeTyping(
-      app: app,
-      target: target,
-      keyboardVisibleBeforeTap: keyboardVisibleBeforeTap
-    )
-    let readyTarget = TextEntryTarget(
-      element: stabilized.element ?? target,
-      refreshPoint: requestedPoint,
-      prefersFocusedElement: false
-    )
-    let concreteTargetReady = keyboardVisibleBeforeTap && readyTarget.element != nil
-    let element = stabilized.focusConfirmed || concreteTargetReady
-      ? (stabilized.element ?? target)
-      : (waitForTextEntryReadiness(app: app, target: readyTarget) ?? stabilized.element ?? target)
-    return TextEntryTarget(
-      element: element,
-      refreshPoint: textEntryRefreshPoint(for: element) ?? requestedPoint,
-      prefersFocusedElement: false
-    )
-  }
-
-  func focusTextInputForTextEntry(app: XCUIApplication, element: XCUIElement) -> TextEntryTarget {
-    let point = textEntryRefreshPoint(for: element)
-    let keyboardVisibleBeforeTap = isKeyboardVisible(app: app)
-    if let point {
-      _ = tapAt(app: app, x: point.x, y: point.y)
-    }
-    // See the coordinate-target path above: direct element typing keeps this scoped to the
-    // tapped target, while the first-character warmup and final verify still catch dropped input.
-    if keyboardVisibleBeforeTap {
-      return TextEntryTarget(
-        element: element,
-        refreshPoint: textEntryRefreshPoint(for: element) ?? point,
-        prefersFocusedElement: false
-      )
-    }
-    let stabilized = stabilizeTextInputBeforeTyping(
-      app: app,
-      target: element,
-      keyboardVisibleBeforeTap: keyboardVisibleBeforeTap
-    )
-    let readyTarget = TextEntryTarget(
-      element: stabilized.element ?? element,
-      refreshPoint: point,
-      prefersFocusedElement: false
-    )
-    let resolved = stabilized.focusConfirmed
-      ? (stabilized.element ?? element)
-      : (waitForTextEntryReadiness(app: app, target: readyTarget) ?? stabilized.element ?? element)
-    return TextEntryTarget(
-      element: resolved,
-      refreshPoint: textEntryRefreshPoint(for: resolved) ?? point,
-      prefersFocusedElement: false
-    )
-  }
-
   func isTextEntryElement(_ element: XCUIElement) -> Bool {
     switch element.elementType {
     case .textField, .secureTextField, .searchField, .textView:
@@ -369,103 +177,6 @@ extension RunnerTests {
     return nil
   }
 
-  private func waitForTextEntryReadiness(
-    app: XCUIApplication,
-    target: TextEntryTarget,
-    timeout: TimeInterval = TextEntryTiming.readinessTimeout
-  ) -> XCUIElement? {
-#if os(iOS)
-    var latest = resolveTextEntryElement(app: app, target: target)
-    let keyboardVisibleAtEntry = isKeyboardVisible(app: app)
-    let deadline = Date().addingTimeInterval(timeout)
-    let hardwareKeyboardFallback = Date().addingTimeInterval(
-      min(TextEntryTiming.hardwareKeyboardFallbackTimeout, timeout)
-    )
-    var sawSoftwareKeyboard = false
-    while Date() < deadline {
-      if let focused = focusedTextInput(app: app) {
-        latest = focused
-        if isKeyboardVisible(app: app) {
-          return focused
-        }
-      }
-      // Fast-path on a keyboard hidden->visible transition: our tapped field gained focus, so
-      // return immediately instead of burning the full readinessTimeout (warmup-first-char echo
-      // + post-type verify/repair remain as drop safety nets). When the keyboard was ALREADY up
-      // (back-to-back fills), this isn't a focus signal — fall through to the settle/timeout so
-      // text isn't sent to the previously-focused field.
-      if keyboardBecameVisible(app: app, wasVisibleAtEntry: keyboardVisibleAtEntry) {
-        return latest
-      }
-      sawSoftwareKeyboard = sawSoftwareKeyboard || keyboardElementExists(app: app)
-      if !sawSoftwareKeyboard && Date() >= hardwareKeyboardFallback && latest != nil {
-        return latest
-      }
-      sleepFor(TextEntryTiming.pollInterval)
-    }
-    return focusedTextInput(app: app) ?? latest
-#else
-    return resolveTextEntryElement(app: app, target: target)
-#endif
-  }
-
-  func waitForTextEntryReadinessAfterTap(app: XCUIApplication, element: XCUIElement) {
-#if os(iOS)
-    switch element.elementType {
-    case .textField, .secureTextField, .searchField, .textView:
-      if waitForFocusedTextInput(app: app, timeout: TextEntryTiming.readinessTimeout) != nil {
-        return
-      }
-      let frame = element.frame
-      if !frame.isEmpty {
-        _ = tapAt(app: app, x: frame.midX, y: frame.midY)
-        _ = waitForFocusedTextInput(app: app, timeout: TextEntryTiming.readinessTimeout)
-      }
-    default:
-      return
-    }
-#endif
-  }
-
-  private func waitForFocusedTextInput(app: XCUIApplication, timeout: TimeInterval) -> XCUIElement? {
-    let deadline = Date().addingTimeInterval(timeout)
-    while Date() < deadline {
-      if let focused = focusedTextInput(app: app) {
-        return focused
-      }
-      sleepFor(TextEntryTiming.pollInterval)
-    }
-    return focusedTextInput(app: app)
-  }
-
-  private func textEntryRefreshPoint(for element: XCUIElement?) -> CGPoint? {
-    guard let element else {
-      return nil
-    }
-    let frame = element.frame
-    guard !frame.isEmpty else {
-      return nil
-    }
-    return CGPoint(x: frame.midX, y: frame.midY)
-  }
-
-  /// A focus-moved signal for iOS text entry, where `focusedTextInput` is intentionally nil.
-  /// The software keyboard TRANSITIONING from hidden (at entry) to visible means the field we
-  /// just tapped gained first-responder. If the keyboard was ALREADY up (e.g. back-to-back
-  /// fills into different fields), its visibility is not evidence focus moved to the new field,
-  /// so callers must keep waiting rather than typing into the previously-focused field.
-  private func keyboardBecameVisible(app: XCUIApplication, wasVisibleAtEntry: Bool) -> Bool {
-    return !wasVisibleAtEntry && isKeyboardVisible(app: app)
-  }
-
-  private func keyboardElementExists(app: XCUIApplication) -> Bool {
-#if os(iOS)
-    return safely("KEYBOARD_EXISTS", false) { app.keyboards.firstMatch.exists }
-#else
-    return false
-#endif
-  }
-
   private func moveCaretToEnd(element: XCUIElement) {
 #if os(tvOS)
     return
@@ -516,14 +227,13 @@ extension RunnerTests {
   }
 
   private func isPlaceholderValue(_ value: String, for element: XCUIElement) -> Bool {
+    if Self.textMatchesPlaceholder(value, placeholder: element.placeholderValue) {
+      return true
+    }
     let normalizedValue = value.trimmingCharacters(in: .whitespacesAndNewlines)
     guard !normalizedValue.isEmpty else {
       return false
     }
-    let placeholder = element.placeholderValue?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-    if !placeholder.isEmpty && normalizedValue == placeholder {
-      return true
-    }
     if isGenericTextInputLabel(normalizedValue) {
       return true
     }
@@ -531,6 +241,13 @@ extension RunnerTests {
     return normalizedLabel == normalizedValue && isGenericTextInputLabel(normalizedLabel)
   }
 
+  static func textMatchesPlaceholder(_ text: String, placeholder: String?) -> Bool {
+    let normalizedText = text.trimmingCharacters(in: .whitespacesAndNewlines)
+    guard !normalizedText.isEmpty else { return false }
+    let normalizedPlaceholder = placeholder?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+    return !normalizedPlaceholder.isEmpty && normalizedText == normalizedPlaceholder
+  }
+
   private func isGenericTextInputLabel(_ value: String) -> Bool {
     switch value {
     case "Text input field":