diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerKeyboardReturnKey.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerKeyboardReturnKey.swift new file mode 100644 index 0000000000..570c1fed63 --- /dev/null +++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerKeyboardReturnKey.swift @@ -0,0 +1,53 @@ +import Foundation + +/// What the keyboard's return key offers, read from the key's own label or identifier. +/// +/// The key is the app's declaration of what submitting the focused field does, and only the app +/// can answer that: `UITextInput.returnKeyType` reaches the keyboard as one of Apple's return-key +/// types, whose English wording is what XCTest exposes. This maps that wording to one stable kind. +/// +/// Exact, case-insensitive matches only. An unlisted label stays `.unknown` rather than being +/// guessed: iOS localizes these keys unevenly, so a prefix or fuzzy rule would report a localized +/// "Done" as something else. Absence is not a kind either — only a control this module cannot read +/// is `.unknown`; a keyboard with no return control is reported by the caller that looked for one. +/// +/// Three of Apple's return-key types are deliberately unmapped and answer `.unknown`: `Google` and +/// `Yahoo` are vendor-branded keys whose wording names a vendor rather than a submit action, and +/// `Emergency Call` places a call, which no caller of this should ever report as a submit. Every +/// other Apple type has a case above. +/// +/// `probeLabels` is the order `findKeyboardReturnControl(app:)` presses in. It is the runner's own +/// vocabulary, so it is not derived from the cases: it carries the two spellings of the plain +/// return key, in the order that found a hittable control before this rule existed. +enum RunnerKeyboardReturnKey: String { + case go + case search + case send + case next + case done + case join + case route + case `continue` + case enter + case unknown + + /// The keyboard control labels `findKeyboardReturnControl(app:)` tries, in order. + static let probeLabels = ["return", "Return", "Enter", "Go", "Search", "Next", "Done", "Send", "Join"] + + /// The kind an accessibility label or identifier names. Surrounding whitespace is trimmed + /// because the accessibility tree carries it; nothing else is normalized. + static func kind(of text: String) -> RunnerKeyboardReturnKey { + switch text.trimmingCharacters(in: .whitespacesAndNewlines).lowercased() { + case "go": return .go + case "search": return .search + case "send": return .send + case "next": return .next + case "done": return .done + case "join": return .join + case "route": return .route + case "continue": return .continue + case "return", "enter": return .enter + default: return .unknown + } + } +} diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Keyboard.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Keyboard.swift index e7779918dd..52725cb190 100644 --- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Keyboard.swift +++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Keyboard.swift @@ -493,20 +493,30 @@ extension RunnerTests { #endif } - private func tapKeyboardReturnControl(app: XCUIApplication) -> Bool { + /// The keyboard's own return control, in the order `RunnerKeyboardReturnKey.probeLabels` tries its + /// labels. On iOS, `nil` means no listed label was hittable. On other platforms nothing is queried + /// and `nil` is returned, so callers must not read it as an absent return control. + func findKeyboardReturnControl(app: XCUIApplication) -> XCUIElement? { #if os(iOS) - for label in ["return", "Return", "Enter", "Go", "Search", "Next", "Done", "Send", "Join"] { + for label in RunnerKeyboardReturnKey.probeLabels { let candidates = [ app.keyboards.buttons[label], app.keyboards.keys[label], ] if let hittable = candidates.first(where: { $0.exists && $0.isHittable }) { - hittable.tap() - return true + return hittable } } #endif - return false + return nil + } + + private func tapKeyboardReturnControl(app: XCUIApplication) -> Bool { + guard let control = findKeyboardReturnControl(app: app) else { + return false + } + control.tap() + return true } private func isKeyboardAccessoryControl(_ element: XCUIElement, keyboardFrame: CGRect) -> Bool { diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+KeyboardReturnKeyTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+KeyboardReturnKeyTests.swift new file mode 100644 index 0000000000..fe38253aac --- /dev/null +++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+KeyboardReturnKeyTests.swift @@ -0,0 +1,86 @@ +import XCTest + +#if AGENT_DEVICE_RUNNER_UNIT_TESTS +extension RunnerTests { + /// Every Apple return-key type this rule maps: the key's English wording, and the wire value the + /// host publishes for it (design Feature C: `keyboard status` reports `returnKey`). The raw value + /// is the contract, so these assert the pair, not the case alone. `Google`, `Yahoo` and + /// `Emergency Call` are Apple types this rule leaves unmapped on purpose; the test below pins that. + func testKeyboardReturnKeyKindNamesEachReturnKeyType() { + let cases: [(label: String, expected: String)] = [ + ("Go", "go"), + ("Search", "search"), + ("Send", "send"), + ("Next", "next"), + ("Done", "done"), + ("Join", "join"), + ("Route", "route"), + ("Continue", "continue"), + ("Return", "enter"), + ("Enter", "enter"), + ] + for (label, expected) in cases { + XCTAssertEqual(RunnerKeyboardReturnKey.kind(of: label).rawValue, expected, label) + } + } + + /// Keyboards and iOS versions differ in the label's casing and padding; the kind it names does not. + func testKeyboardReturnKeyKindIgnoresCasingAndPadding() { + XCTAssertEqual(RunnerKeyboardReturnKey.kind(of: "done"), .done) + XCTAssertEqual(RunnerKeyboardReturnKey.kind(of: "DONE"), .done) + XCTAssertEqual(RunnerKeyboardReturnKey.kind(of: " Done"), .done) + XCTAssertEqual(RunnerKeyboardReturnKey.kind(of: "\nSend\t"), .send) + } + + /// The three Apple return-key types this rule leaves unmapped on purpose. `Google` and `Yahoo` + /// name a vendor rather than a submit action, and `Emergency Call` places a call: reporting any of + /// them as a submit kind would tell a caller to submit a field whose key does something else. + func testKeyboardReturnKeyKindLeavesBrandedAndEmergencyAppleTypesUnknown() { + for label in ["Google", "Yahoo", "Emergency Call"] { + XCTAssertEqual(RunnerKeyboardReturnKey.kind(of: label), .unknown, label) + } + } + + /// Closest negatives: a label that CONTAINS a return-key word, or is a localized or custom key's + /// wording, is not that key. A prefix or fuzzy rule would report a "Send Message" key as `send`, + /// or a localized "Retour" key as `enter`; both would tell a caller to submit a field whose key + /// does something else. + func testKeyboardReturnKeyKindLeavesAmbiguousLabelsUnknown() { + for label in [ + "Send Message", + "Search Messages", + "Done Sending", + "Next slide", + "Go to Settings", + "Continued", + "Return key", + "Retour", + "完了", + "", + " ", + ] { + XCTAssertEqual(RunnerKeyboardReturnKey.kind(of: label), .unknown, label) + } + } + + /// The two owners of the key's wording stay aligned: every label the press path probes names a + /// kind a status read can report, so a lookup that finds a control is never a status read that + /// answers `unknown`. + func testEveryKeyboardReturnProbeLabelMapsToAReportedKind() { + let expected: [String: RunnerKeyboardReturnKey] = [ + "return": .enter, + "Return": .enter, + "Enter": .enter, + "Go": .go, + "Search": .search, + "Next": .next, + "Done": .done, + "Send": .send, + "Join": .join, + ] + for label in RunnerKeyboardReturnKey.probeLabels { + XCTAssertEqual(RunnerKeyboardReturnKey.kind(of: label), expected[label], label) + } + } +} +#endif