Commit fcc403f

/// What confirmed that a focus tap's input took focus.

enum TextEntryFocusEvidence: String {

/// tvOS moves focus with the focus engine, so there is nothing to wait for.

case focusEngine = "focus-engine"

/// The app-wide focus query named a text input (not iOS).

case focusedInput = "focused-input"

/// The tapped input's own snapshot reports keyboard focus.

case inputReportsKeyboardFocus = "input-reports-keyboard-focus"

/// A software keyboard appeared after the tap, so some input took focus.

case keyboardAppeared = "keyboard-appeared"

/// The app-wide keyboard-focus query answered with the tapped input.

case focusQueryMatchesInput = "focus-query-matches-input"

}

/// Nil when nothing confirmed focus before the focus timeout.

let evidence: TextEntryFocusEvidence?

/// `element`'s frame from the read that confirmed focus, when the input's own read did.

var inputFrame: CGRect? = nil

var focusConfirmed: Bool { evidence != nil }

return TextEntryStabilization(element: target, evidence: .focusEngine)

return TextEntryStabilization(element: focused, evidence: .focusedInput)

// The tapped input's own read comes before the keyboard. While a software keyboard is

// presented, the keyboard query blocks and then finds none: after a fill's focus tap it took

// 0.68 s on an iPhone 17 Pro simulator (iOS 27.0) and 0.57–3.77 s on CI. An input that

// reports keyboard focus is stronger evidence than the keyboard's arrival, which shows only

// that some input took focus.

if let target, let frame = keyboardFocusedInputFrame(target) {

return TextEntryStabilization(element: target, evidence: .inputReportsKeyboardFocus, inputFrame: frame)

}

// focusedTextInput is intentionally nil on iOS; the keyboard transitioning to visible after

// our tap is also a focus-moved signal. Don't fast-path when it was already up.

return TextEntryStabilization(element: target, evidence: .keyboardAppeared)

return TextEntryStabilization(element: target, evidence: .focusQueryMatchesInput)

return TextEntryStabilization(element: target, evidence: nil)

// Bare `type` targets the current first responder. On iOS we intentionally do not let the

// app-wide `hasKeyboardFocus` query pick it, 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.

NSLog("AGENT_DEVICE_RUNNER_TEXT_ENTRY_FOCUS evidence=%@", stabilized.evidence?.rawValue ?? "none")

if let frame = stabilized.inputFrame {

// The read that confirmed focus came after the tap, so its frame serves the refresh point.

return TextEntryTarget(

element: stabilized.element,

refreshPoint: textEntryRefreshPoint(frame: frame, fallbackTo: requestedPoint),

prefersFocusedElement: false

)

}

return textEntryRefreshPoint(frame: textEntrySnapshotFrame(element), fallbackTo: requestedPoint)

}

/// `textEntryRefreshPoint(for:)` from a frame already read after the focus tap.

private func textEntryRefreshPoint(frame: CGRect?, fallbackTo requestedPoint: CGPoint?) -> CGPoint? {

guard let frame else {

// under XCUITest, so they never pick the text-entry target. Readiness corroborates the

// input a tap or coordinate already chose.

/// `element`'s frame when its own snapshot reports keyboard focus, or nil. Read through

/// `snapshot()`, which records nothing, after `exists`, so a field that stopped answering its query

/// on focus (#3060) neither records an XCTest failure nor pays the snapshot's wait for a match.

func keyboardFocusedInputFrame(_ element: XCUIElement) -> CGRect? {

return safely("TEXT_ENTRY_INPUT_FOCUS") {

guard element.exists, let snapshot = try? element.snapshot(), snapshotHasKeyboardFocus(snapshot) else {

return nil

}

return snapshot.frame

}

return nil

}

/// After a focus tap raises the software keyboard, stabilization takes focus from the tapped

/// input's own read before it asks for the keyboard. While the keyboard is presented, the keyboard

/// query blocks and then finds none: after a fill's focus tap it took 0.68 s on the test app

/// (iPhone 17 Pro, iOS 27.0) and 0.57–3.77 s on CI. The keyboard is already up here, so asking it

/// first confirms focus from the keyboard's arrival instead.

@MainActor

func testFocusStabilizationAsksTheTappedInputBeforeTheKeyboard() throws {

app.launchArguments = ["--agent-device-text-entry-regression", "--agent-device-text-entry-soft-keyboard"]

app.launch()

defer { invalidateCachedTarget(reason: "unit_test_cleanup"); app.terminate() }

XCTAssertTrue(app.waitForFixtureExistence(timeout: appExistenceTimeout))

let field = app.textFields["agent-device-hardware-keyboard-input"]

XCTAssertTrue(field.waitForFixtureExistence(timeout: appExistenceTimeout))

field.tap()

try XCTSkipUnless(

app.keyboards.firstMatch.waitForFixtureExistence(timeout: appExistenceTimeout),

"software keyboard is down: this simulator cannot show the keyboard a focus tap raises"

)

let stabilized = stabilizeTextInputBeforeTyping(app: app, target: field, keyboardVisibleBeforeTap: false)

XCTAssertEqual(stabilized.evidence, .inputReportsKeyboardFocus)

XCTAssertEqual(stabilized.inputFrame, field.frame)

}

/// A fill whose focus tap raises the software keyboard types and reads its text back when focus is

/// confirmed from the input rather than from the keyboard's arrival.

@MainActor

func testFillThatRaisesTheSoftwareKeyboardTypesAndReadsBack() throws {

app.launchArguments = ["--agent-device-text-entry-regression", "--agent-device-text-entry-soft-keyboard"]

app.launch()

defer { invalidateCachedTarget(reason: "unit_test_cleanup"); app.terminate() }

XCTAssertTrue(app.waitForFixtureExistence(timeout: appExistenceTimeout))

let field = app.textFields["agent-device-hardware-keyboard-input"]

XCTAssertTrue(field.waitForFixtureExistence(timeout: appExistenceTimeout))

XCTAssertFalse(isKeyboardVisible(app: app))

let frame = field.frame

let fill = try runnerCommandFixture(

#"{"command":"type","commandId":"fill-raises-keyboard","text":"hello","textEntryMode":"replace","x":\#(frame.midX),"y":\#(frame.midY)}"#

)

let response = executeTypeCommand(activeApp: app, command: fill)

XCTAssertTrue(response.ok, String(describing: response.error))

XCTAssertEqual(response.data?.textEntryRoute, "xctest-element")

XCTAssertEqual(field.value as? String, "hello")

try XCTSkipUnless(

app.keyboards.firstMatch.waitForFixtureExistence(timeout: appExistenceTimeout),

"software keyboard is down: this simulator did not raise the keyboard the focus tap asked for"

)

}