Skip to content

Commit de2778e

Browse files
committed
refactor(runner): make the text-entry content vector a non-defaulted tri-state
frameOnScreen becomes optional and carries the #3060 rule: it names no box without a snapshot or under an unknown content space, so the four consumer guards collapse into one nil check. liveContentTranslation returns TextEntryContentTranslation (known/none/unknown) instead of CGSize?, so a failed window read can no longer look like full screen and send the readiness retap to a raw window-local point. The vector now rides on TextInputAtPoint, cutting one parameter from the probe signatures. retapAt skips the point on unknown; probe matching and the focus tap fall back to element.frame. Adds the unknown-space retap unit test.
1 parent 8c4786e commit de2778e

12 files changed

Lines changed: 191 additions & 106 deletions

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextEntry.swift‎

Lines changed: 51 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -137,22 +137,37 @@ extension RunnerTests {
137137
var isDistinguishable: Bool { !identifier.isEmpty }
138138
}
139139

140-
/// A text input found under a point, and the identity it carried when found. The element is an
141-
/// index-bound query handle: an input inserted or reordered ahead of it later re-binds the handle
142-
/// to that input, and the identity is what notices.
140+
/// A text input found under a point, the identity it carried when found, and the content vector of
141+
/// the command that found it. The element is an index-bound query handle: an input inserted or
142+
/// reordered ahead of it later re-binds the handle to that input, and the identity is what notices.
143143
struct TextInputAtPoint {
144144
let element: XCUIElement
145145
let identity: TextEntryInputIdentity
146+
let contentTranslation: TextEntryContentTranslation
147+
}
148+
149+
/// The vector that carries a snapshot-read frame to its place on the screen (#3899), read once per
150+
/// command by `liveContentTranslation`. Non-defaulted everywhere it travels: a vector nobody read
151+
/// must never read as full screen, because on a placed window that silently dispatches window-local
152+
/// points as screen points — the #3899 failure.
153+
enum TextEntryContentTranslation {
154+
/// The vector of a placed window: its content box's origin on the screen.
155+
case known(CGSize)
156+
/// The app fills the screen, so a snapshot frame is already a screen frame.
157+
case none
158+
/// The window read could not answer, so the space of a snapshot frame is unknown. Consumers
159+
/// refuse it as a screen frame: `frameOnScreen` reads nil and nothing dispatches a point from it.
160+
case unknown
146161
}
147162

148163
struct TextEntryTarget {
149164
let element: XCUIElement?
150165
let refreshPoint: CGPoint?
151166
let prefersFocusedElement: Bool
152-
/// The content vector of a placed window, read once for the command that built this target and
153-
/// handed to every read it produces, which turns its snapshot frames into screen points (#3899).
154-
/// Nil when the app fills the screen.
155-
let contentTranslation: CGSize?
167+
/// The content vector of the command that built this target, handed to every read it produces,
168+
/// which turns their snapshot frames into screen points (#3899). Non-defaulted: the route that
169+
/// reads no window carries `.unknown`, not a vector that would read as full screen.
170+
let contentTranslation: TextEntryContentTranslation
156171
let fromTapWitness: Bool
157172
/// The input the first resolved element was. Once bound, resolution refuses any other input.
158173
let boundIdentity: TextEntryInputIdentity?
@@ -170,7 +185,7 @@ extension RunnerTests {
170185
element: XCUIElement?,
171186
refreshPoint: CGPoint?,
172187
prefersFocusedElement: Bool,
173-
contentTranslation: CGSize? = nil,
188+
contentTranslation: TextEntryContentTranslation,
174189
fromTapWitness: Bool = false,
175190
boundIdentity: TextEntryInputIdentity? = nil,
176191
inputAtRefreshPoint: TextInputAtPoint? = nil,
@@ -187,14 +202,14 @@ extension RunnerTests {
187202
}
188203

189204
/// The target moved to the input a resolution read: its element, a refresh point at its frame's
190-
/// center on the screen, and its identity while the target is unbound. A read with no snapshot has
191-
/// no frame here, so its center cannot come from the live `element.frame` — the read a post-focus
192-
/// handle cannot answer without recording a failure (#3060).
205+
/// center on the screen, and its identity while the target is unbound. A read that cannot name a
206+
/// screen box — no snapshot, or an unknown content space — keeps the target's current refresh
207+
/// point rather than a center it cannot trust.
193208
func withResolvedInput(_ input: ResolvedTextEntryInput?) -> TextEntryTarget {
194209
guard let input else {
195210
return self
196211
}
197-
let frame = input.snapshot == nil ? .zero : input.frameOnScreen
212+
let frame = input.frameOnScreen ?? .zero
198213
return TextEntryTarget(
199214
element: input.element,
200215
refreshPoint: frame.isEmpty ? refreshPoint : CGPoint(x: frame.midX, y: frame.midY),
@@ -221,10 +236,10 @@ extension RunnerTests {
221236
let element: XCUIElement
222237
/// Nil when the element exists but could not be snapshotted.
223238
let snapshot: XCUIElementSnapshot?
224-
/// The vector of the command that made this read (#3899); nil when the app fills the screen.
225-
let contentTranslation: CGSize?
239+
/// The vector state of the command that made this read (#3899).
240+
let contentTranslation: TextEntryContentTranslation
226241

227-
private init(element: XCUIElement, snapshot: XCUIElementSnapshot?, contentTranslation: CGSize?) {
242+
private init(element: XCUIElement, snapshot: XCUIElementSnapshot?, contentTranslation: TextEntryContentTranslation) {
228243
self.element = element
229244
self.snapshot = snapshot
230245
self.contentTranslation = contentTranslation
@@ -233,7 +248,7 @@ extension RunnerTests {
233248
/// Reads a handle that may name an input the app has removed; nil when it names none or the read
234249
/// raised. The snapshot of a missing element throws only after XCTest waits about two seconds for
235250
/// a match, so existence is read first.
236-
init?(reading element: XCUIElement, contentTranslation: CGSize? = nil) {
251+
init?(reading element: XCUIElement, contentTranslation: TextEntryContentTranslation) {
237252
var exists = false
238253
var snapshot: XCUIElementSnapshot?
239254
if let exception = RunnerObjCExceptionCatcher.catchException({
@@ -249,7 +264,7 @@ extension RunnerTests {
249264

250265
/// Reads a handle its query has just listed, inside the caller's exception containment, so the
251266
/// snapshot is read first and existence only when the snapshot fails; nil when it names no element.
252-
init?(readingListed element: XCUIElement, contentTranslation: CGSize? = nil) {
267+
init?(readingListed element: XCUIElement, contentTranslation: TextEntryContentTranslation) {
253268
let snapshot = try? element.snapshot()
254269
guard snapshot != nil || element.exists else { return nil }
255270
self.init(element: element, snapshot: snapshot, contentTranslation: contentTranslation)
@@ -266,17 +281,25 @@ extension RunnerTests {
266281
return element
267282
}
268283

269-
/// The input's box in screen space: the snapshot frame plus `contentTranslation`, or the live
270-
/// frame when there is no snapshot — that property already reports a placed window's content in
271-
/// screen space (#3899).
272-
var frameOnScreen: CGRect {
284+
/// The input's box in screen space, or nil when this read cannot name one: no snapshot, or a
285+
/// window read that could not answer, so the snapshot frame's space is unknown. A nil here is the
286+
/// one signal every consumer uses to refuse a dispatched point: the live `element.frame` is a
287+
/// read a handle that stopped answering its query cannot make without recording a failure
288+
/// (#3060), and an unknown space must never be dispatched as a screen point (#3899). Callers
289+
/// that need a box for a route which dispatches nothing fall back to `element.frame`, which
290+
/// already reports a placed window's content in screen space.
291+
var frameOnScreen: CGRect? {
273292
guard let snapshot else {
274-
return element.frame
293+
return nil
275294
}
276-
guard let contentTranslation else {
295+
switch contentTranslation {
296+
case .known(let offset):
297+
return snapshot.frame.offsetBy(dx: offset.width, dy: offset.height)
298+
case .none:
277299
return snapshot.frame
300+
case .unknown:
301+
return nil
278302
}
279-
return snapshot.frame.offsetBy(dx: contentTranslation.width, dy: contentTranslation.height)
280303
}
281304
}
282305

@@ -539,7 +562,7 @@ extension RunnerTests {
539562
return input
540563
}
541564
if let input = target.inputAtRefreshPoint,
542-
let read = textInputIfStillResolves(input, contentTranslation: target.contentTranslation) {
565+
let read = textInputIfStillResolves(input) {
543566
return read
544567
}
545568
if target.inputAtRefreshPoint == nil,
@@ -658,12 +681,11 @@ extension RunnerTests {
658681
// zero-size one (how a departed handle reads), there is no point to dispatch — an edge-tap
659682
// from a frame the field moved after records a failure or navigates away, the shape
660683
// `clearTextInput`'s comment refuses — so degrade to the caller's point-free delete burst.
661-
// A snapshotless read gets no point at all: `frameOnScreen`'s fallback is the live
662-
// `element.frame` read this function exists to avoid (#3060).
663-
guard input.snapshot?.frame.isEmpty == false else {
684+
// A snapshotless read gets no point at all: `frameOnScreen` is nil without a snapshot, so the
685+
// live `element.frame` read this function exists to avoid is never reached (#3060).
686+
guard let frame = input.frameOnScreen, !frame.isEmpty else {
664687
return
665688
}
666-
let frame = input.frameOnScreen
667689
_ = tapAt(
668690
app: app,
669691
x: frame.minX + max(2, frame.width - 4),

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextEntryFocus.swift‎

Lines changed: 32 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,9 @@ extension RunnerTests {
2626
}
2727

2828
@MainActor
29-
private func rememberedTextEntryTarget() -> TextEntryTarget? {
29+
private func rememberedTextEntryTarget(
30+
contentTranslation: TextEntryContentTranslation
31+
) -> TextEntryTarget? {
3032
guard let witness = textEntryTapWitness else {
3133
return nil
3234
}
@@ -54,15 +56,16 @@ extension RunnerTests {
5456
element: element,
5557
refreshPoint: nil,
5658
prefersFocusedElement: false,
59+
contentTranslation: contentTranslation,
5760
fromTapWitness: true
5861
)
5962
}
6063

6164
func stabilizeTextInputBeforeTyping(
6265
app: XCUIApplication,
6366
target: XCUIElement?,
64-
keyboardVisibleBeforeTap: Bool? = nil,
65-
contentTranslation: CGSize? = nil
67+
contentTranslation: TextEntryContentTranslation,
68+
keyboardVisibleBeforeTap: Bool? = nil
6669
) -> TextEntryStabilization {
6770
#if os(tvOS)
6871
return TextEntryStabilization(element: target, evidence: .focusEngine, polls: 0)
@@ -104,9 +107,14 @@ extension RunnerTests {
104107

105108
@MainActor
106109
func focusTextInputForTextEntry(app: XCUIApplication, x: Double?, y: Double?) -> TextEntryTarget {
110+
// The one content-vector read for this command (#3899): every target built here carries it and
111+
// every read those targets produce converts through it.
112+
let contentTranslation = liveContentTranslation(app: app)
107113
guard let x, let y else {
108114
let softwareKeyboardVisible = isKeyboardVisible(app: app)
109-
if !softwareKeyboardVisible, let rememberedTarget = rememberedTextEntryTarget() {
115+
if !softwareKeyboardVisible, let rememberedTarget = rememberedTextEntryTarget(
116+
contentTranslation: contentTranslation
117+
) {
110118
return rememberedTarget
111119
}
112120
// Bare `type` targets the current first responder. On iOS we intentionally do not let the
@@ -117,30 +125,35 @@ extension RunnerTests {
117125
return TextEntryTarget(
118126
element: focusedTextInput(app: app),
119127
refreshPoint: nil,
120-
prefersFocusedElement: true
128+
prefersFocusedElement: true,
129+
contentTranslation: contentTranslation
121130
)
122131
}
123132
let focused = waitForTextEntryReadiness(
124133
app: app,
125134
target: TextEntryTarget(
126135
element: focusedTextInput(app: app),
127136
refreshPoint: nil,
128-
prefersFocusedElement: true
137+
prefersFocusedElement: true,
138+
contentTranslation: contentTranslation
129139
)
130140
)
131-
return TextEntryTarget(element: focused, refreshPoint: nil, prefersFocusedElement: true)
141+
return TextEntryTarget(
142+
element: focused,
143+
refreshPoint: nil,
144+
prefersFocusedElement: true,
145+
contentTranslation: contentTranslation
146+
)
132147
}
133148

134-
// The one content-vector read for this command (#3899): every target built here carries it and
135-
// every read those targets produce converts through it.
136-
let contentTranslation = liveContentTranslation(app: app)
137149
let keyboardVisibleBeforeTap = isKeyboardVisible(app: app)
138150
let input = textInputAt(app: app, x: x, y: y, contentTranslation: contentTranslation)
139151
let target = input?.element
140152
let requestedPoint = CGPoint(x: x, y: y)
141153
// The tap goes to the input's own center, and `tapAt` dispatches a screen point, so the point
142-
// comes from `frameOnScreen` (#3899).
143-
let inputCenter = input.map { $0.frameOnScreen }.flatMap {
154+
// comes from `frameOnScreen`; the live frame is the box left when the command's window read
155+
// could not answer (#3899).
156+
let inputCenter = (input?.frameOnScreen ?? input?.element.frame).flatMap {
144157
$0.isEmpty ? nil : CGPoint(x: $0.midX, y: $0.midY)
145158
}
146159
if let inputCenter {
@@ -161,8 +174,8 @@ extension RunnerTests {
161174
let stabilized = stabilizeTextInputBeforeTyping(
162175
app: app,
163176
target: target,
164-
keyboardVisibleBeforeTap: keyboardVisibleBeforeTap,
165-
contentTranslation: contentTranslation
177+
contentTranslation: contentTranslation,
178+
keyboardVisibleBeforeTap: keyboardVisibleBeforeTap
166179
)
167180
NSLog(
168181
"%@%@ polls=%d",
@@ -198,7 +211,7 @@ extension RunnerTests {
198211
private func focusedTextEntryTarget(
199212
_ element: XCUIElement?,
200213
requestedPoint: CGPoint,
201-
contentTranslation: CGSize?
214+
contentTranslation: TextEntryContentTranslation
202215
) -> TextEntryTarget {
203216
guard let element else {
204217
return TextEntryTarget(
@@ -221,7 +234,7 @@ extension RunnerTests {
221234
_ element: XCUIElement,
222235
read: ResolvedTextEntryInput?,
223236
requestedPoint: CGPoint,
224-
contentTranslation: CGSize?
237+
contentTranslation: TextEntryContentTranslation
225238
) -> TextEntryTarget {
226239
return TextEntryTarget(
227240
element: element,
@@ -244,15 +257,15 @@ extension RunnerTests {
244257
/// not yet bound to an identity, and a field that went unqueryable on focus may have moved the
245258
/// layout so the old point names a different input, so fail closed with a typed reason instead of
246259
/// typing into that other field. The frame is `read`'s snapshot frame plus its content vector,
247-
/// never the live `element.frame` (#3899, #3060).
260+
/// never the live `element.frame`, and `frameOnScreen` is nil for a read that cannot name a screen
261+
/// box (#3899, #3060).
248262
private func textEntryRefreshPoint(
249263
read: ResolvedTextEntryInput?,
250264
fallbackTo requestedPoint: CGPoint
251265
) -> CGPoint? {
252-
guard let read, read.snapshot != nil else {
266+
guard let frame = read?.frameOnScreen else {
253267
return nil
254268
}
255-
let frame = read.frameOnScreen
256269
guard !frame.isEmpty else {
257270
return requestedPoint
258271
}

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextEntryReadiness.swift‎

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -86,15 +86,16 @@ extension RunnerTests {
8686
/// wait rather than reused, because focusing a field moves the layout: the repeat aims at where the
8787
/// field is then, which is the moment the read it replaced ran at.
8888
///
89-
/// The re-read carries the live content vector, so the repeat taps a screen point (#3899). It is
90-
/// read only on this branch: a tap that confirms focus dispatches no window lookup.
89+
/// The re-read carries a fresh content-vector read, so the repeat taps a screen point (#3899). It
90+
/// is read only on this branch: a tap that confirms focus dispatches no window lookup.
9191
func waitForTextEntryReadinessAfterTap(app: XCUIApplication, element: XCUIElement) {
9292
#if os(iOS)
9393
if waitForTextEntryFocus(app: app, element: element, timeout: TextEntryTiming.readinessTimeout) {
9494
return
9595
}
96-
// Contained like the probe lookups: a transient window that records an XCTest issue costs the
97-
// vector, not the command.
96+
// Contained like the probe lookups: a transient window or a snapshot that records an XCTest
97+
// issue costs the retap, not the command. A failed window read leaves the read's vector
98+
// `.unknown`, which names no screen box, so `retapAt` taps nothing (#3899).
9899
let settled: ResolvedTextEntryInput?
99100
switch containingTextInputProbeIssues(fallback: nil as ResolvedTextEntryInput?, { _ in
100101
ResolvedTextEntryInput(reading: element, contentTranslation: liveContentTranslation(app: app))
@@ -112,14 +113,13 @@ extension RunnerTests {
112113
}
113114

114115
/// The readiness retap, split out so the unit lane can drive it and assert where the point lands.
115-
/// A read with no snapshot taps nothing: its `frameOnScreen` is the live `element.frame`, the read
116-
/// a handle that stopped answering its query cannot make without recording a failure (#3060).
116+
/// The retap taps nothing when the read cannot name a screen box: with no snapshot that box is the
117+
/// live `element.frame`, the read a handle that stopped answering its query cannot make without
118+
/// recording a failure (#3060); with an unknown content space a snapshot frame is not known to be
119+
/// a screen box, and a raw window-local point is exactly the #3899 failure. The probe-side rule
120+
/// `clearTextInput` and `moveCaretToEnd` settled on: skip the point, never guess through it.
117121
func retapAt(read: ResolvedTextEntryInput, app: XCUIApplication, element: XCUIElement) {
118-
guard read.snapshot != nil else {
119-
return
120-
}
121-
let frame = read.frameOnScreen
122-
guard !frame.isEmpty else {
122+
guard let frame = read.frameOnScreen, !frame.isEmpty else {
123123
return
124124
}
125125
_ = tapAt(app: app, x: frame.midX, y: frame.midY)
@@ -155,7 +155,8 @@ extension RunnerTests {
155155
func keyboardFocusConfirmed(app: XCUIApplication, element: XCUIElement) -> Bool {
156156
#if os(iOS)
157157
// No content vector: this corroborates raw frame against raw frame and dispatches no point.
158-
return ResolvedTextEntryInput(reading: element).map { keyboardFocusConfirmed(app: app, read: $0) } ?? false
158+
return ResolvedTextEntryInput(reading: element, contentTranslation: .unknown)
159+
.map { keyboardFocusConfirmed(app: app, read: $0) } ?? false
159160
#else
160161
return false
161162
#endif

0 commit comments

Comments
 (0)