Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -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
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
Original file line number Diff line number Diff line change
@@ -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() {
Comment thread
thymikee marked this conversation as resolved.
Resolved
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
Loading