|
1 | 1 | import XCTest |
| 2 | +import AgentDeviceSnapshotPresentation |
2 | 3 |
|
3 | 4 | private enum KeyboardDismissObservationTiming { |
4 | 5 | static let timeout: TimeInterval = 2 |
@@ -30,6 +31,164 @@ enum RunnerKeyboardDismissMechanism: String { |
30 | 31 | case dismissKey |
31 | 32 | } |
32 | 33 |
|
| 34 | +/// The band the visible keyboard owns, measured by the one producer that can ask the keyboard |
| 35 | +/// directly instead of rebuilding it from a captured tree. |
| 36 | +/// |
| 37 | +/// `app.keyboards.firstMatch` answers in the app's own orientation space, which no tree tier can say |
| 38 | +/// about its own rects while the app is rotated (#2612, #2653). Publishing the measurement is what |
| 39 | +/// lets the daemon's tap guard answer with a point-in-rect test instead of guessing where a |
| 40 | +/// plausible-looking band would be (#2660). |
| 41 | +enum RunnerKeyboardBandFact: Equatable { |
| 42 | + case visible(CGRect) |
| 43 | + case absent |
| 44 | + case unmeasurable(String) |
| 45 | + |
| 46 | + var payload: KeyboardBandFactPayload { |
| 47 | + switch self { |
| 48 | + case .visible(let frame): |
| 49 | + return KeyboardBandFactPayload( |
| 50 | + kind: "visible", |
| 51 | + frame: SnapshotRect( |
| 52 | + x: Double(frame.origin.x), |
| 53 | + y: Double(frame.origin.y), |
| 54 | + width: Double(frame.size.width), |
| 55 | + height: Double(frame.size.height) |
| 56 | + ), |
| 57 | + reason: nil |
| 58 | + ) |
| 59 | + case .absent: |
| 60 | + return KeyboardBandFactPayload(kind: "absent", frame: nil, reason: nil) |
| 61 | + case .unmeasurable(let reason): |
| 62 | + return KeyboardBandFactPayload(kind: "unmeasurable", frame: nil, reason: reason) |
| 63 | + } |
| 64 | + } |
| 65 | + |
| 66 | + var logKind: String { |
| 67 | + switch self { |
| 68 | + case .visible: return "visible" |
| 69 | + case .absent: return "absent" |
| 70 | + case .unmeasurable: return "unmeasurable" |
| 71 | + } |
| 72 | + } |
| 73 | + |
| 74 | + var logReason: String { |
| 75 | + switch self { |
| 76 | + case .visible, .absent: return "-" |
| 77 | + case .unmeasurable(let reason): return reason |
| 78 | + } |
| 79 | + } |
| 80 | +} |
| 81 | + |
| 82 | +/// The reason codes a capture publishes beside `unmeasurable`. Key behavior travels on these, never |
| 83 | +/// on prose: a daemon log line and a `snapshot --json` reader have to agree on what `unmeasurable` |
| 84 | +/// meant without parsing a sentence. |
| 85 | +enum RunnerKeyboardBandReason { |
| 86 | + /// The `app.keyboards` read threw or otherwise produced no answer at all. |
| 87 | + static let queryFailed = "keyboard-frame-query-failed" |
| 88 | + /// The keyboard exists and reports no usable box. It is on screen — only its band is unknown, which |
| 89 | + /// is not the same claim as `absent`. |
| 90 | + static let unusableFrame = "keyboard-frame-unusable" |
| 91 | + /// The read did not return inside the slice this capture had left for it, so the band was abandoned |
| 92 | + /// rather than waited on: a keyboard this capture cannot afford to measure is not worth a stalled |
| 93 | + /// capture, and the daemon's tap guard falls back to the tree rule for this capture alone. |
| 94 | + static let queryTimeout = "keyboard-frame-query-timeout" |
| 95 | + /// No slice was left at all, so the read was never dispatched. |
| 96 | + static let budgetExhausted = "capture-plan-budget-exhausted" |
| 97 | +} |
| 98 | + |
| 99 | +/// Whether a keyboard's reported box can be a band at all. A zero-area or non-finite box is what an |
| 100 | +/// element XCTest cannot measure looks like. |
| 101 | +/// |
| 102 | +/// Reads `origin` and `size` rather than the rect's own accessors: `CGRect.width` and `CGRect.height` |
| 103 | +/// standardize, so a box reported with a negative size answers them with a positive one and an |
| 104 | +/// unmeasurable element would ship as a measured band. The daemon's reader applies the same rule to |
| 105 | +/// the wire frame, so neither language can publish a band the other would refuse. |
| 106 | +func runnerKeyboardFrameIsUsable(_ frame: CGRect) -> Bool { |
| 107 | + let size = frame.size |
| 108 | + let origin = frame.origin |
| 109 | + return [origin.x, origin.y, size.width, size.height].allSatisfy(\.isFinite) |
| 110 | + && size.width > 0 && size.height > 0 |
| 111 | +} |
| 112 | + |
| 113 | +/// The one decision the keyboard-band probe makes, kept away from the live query so the unit lane can |
| 114 | +/// pin it without a keyboard on screen. Three outcomes and no fourth: a read that failed says it |
| 115 | +/// failed, a keyboard that is not there is proven absent, and a keyboard whose box cannot be measured |
| 116 | +/// is unmeasurable rather than absent — the difference is whether anything may claim this screen is |
| 117 | +/// clear of a keyboard. |
| 118 | +func runnerKeyboardBandFact( |
| 119 | + readSucceeded: Bool, |
| 120 | + exists: Bool, |
| 121 | + frame: CGRect |
| 122 | +) -> RunnerKeyboardBandFact { |
| 123 | + guard readSucceeded else { return .unmeasurable(RunnerKeyboardBandReason.queryFailed) } |
| 124 | + guard exists else { return .absent } |
| 125 | + guard runnerKeyboardFrameIsUsable(frame) else { |
| 126 | + return .unmeasurable(RunnerKeyboardBandReason.unusableFrame) |
| 127 | + } |
| 128 | + return .visible(frame) |
| 129 | +} |
| 130 | + |
| 131 | +private struct KeyboardBandProbeTimeout: Error {} |
| 132 | + |
| 133 | +extension RunnerTests { |
| 134 | + /// The band the visible keyboard owns, read once per capture. |
| 135 | + /// |
| 136 | + /// Returns nil only where there is no iOS keyboard to look for. Every other outcome is stated, |
| 137 | + /// including the ones where looking failed: a missing field would leave the daemon guessing which |
| 138 | + /// tier answered, while a published `unmeasurable` names the reason where the band would have been. |
| 139 | + /// |
| 140 | + /// Its own main-thread hop with its own slice, taken immediately after the viewport/orientation hop |
| 141 | + /// and before the tree is captured, so band and tree describe one moment while a keyboard this |
| 142 | + /// capture cannot afford to measure costs the capture nothing: a timeout abandons the fact and leaves |
| 143 | + /// the tree tier standing, the same trade `boundedBlockingSystemAlertSnapshot` makes for the probe it |
| 144 | + /// bounds (#2660). |
| 145 | + func captureKeyboardBandFact(app: XCUIApplication, deadline: Date) -> RunnerKeyboardBandFact? { |
| 146 | +#if os(iOS) |
| 147 | + let slice = min(Self.keyboardBandProbeBudget, max(0, deadline.timeIntervalSinceNow)) |
| 148 | + guard slice > 0 else { |
| 149 | + NSLog( |
| 150 | + "AGENT_DEVICE_RUNNER_KEYBOARD_BAND_FACT kind=unmeasurable reason=%@ elapsedMs=0", |
| 151 | + RunnerKeyboardBandReason.budgetExhausted |
| 152 | + ) |
| 153 | + return .unmeasurable(RunnerKeyboardBandReason.budgetExhausted) |
| 154 | + } |
| 155 | + let startedAt = Date() |
| 156 | + let fact: RunnerKeyboardBandFact |
| 157 | + do { |
| 158 | + fact = try runMainThreadWork( |
| 159 | + "keyboard_band", |
| 160 | + timeout: slice, |
| 161 | + timeoutError: { KeyboardBandProbeTimeout() } |
| 162 | + ) { |
| 163 | + self.keyboardBandFact(app: app) |
| 164 | + } |
| 165 | + } catch { |
| 166 | + fact = .unmeasurable(RunnerKeyboardBandReason.queryTimeout) |
| 167 | + } |
| 168 | + NSLog( |
| 169 | + "AGENT_DEVICE_RUNNER_KEYBOARD_BAND_FACT kind=%@ reason=%@ elapsedMs=%d", |
| 170 | + fact.logKind, |
| 171 | + fact.logReason, |
| 172 | + Int(Date().timeIntervalSince(startedAt) * 1000) |
| 173 | + ) |
| 174 | + return fact |
| 175 | +#else |
| 176 | + return nil |
| 177 | +#endif |
| 178 | + } |
| 179 | + |
| 180 | + private func keyboardBandFact(app: XCUIApplication) -> RunnerKeyboardBandFact { |
| 181 | + let read = safely("KEYBOARD_BAND_FACT") { () -> RunnerKeyboardBandFact? in |
| 182 | + let keyboard = app.keyboards.firstMatch |
| 183 | + guard keyboard.exists else { |
| 184 | + return runnerKeyboardBandFact(readSucceeded: true, exists: false, frame: .zero) |
| 185 | + } |
| 186 | + return runnerKeyboardBandFact(readSucceeded: true, exists: true, frame: keyboard.frame) |
| 187 | + } |
| 188 | + return read ?? .unmeasurable(RunnerKeyboardBandReason.queryFailed) |
| 189 | + } |
| 190 | +} |
| 191 | + |
33 | 192 | extension RunnerTests { |
34 | 193 | func isKeyboardVisible(app: XCUIApplication) -> Bool { |
35 | 194 | return visibleKeyboardFrame(app: app) != nil |
@@ -275,6 +434,88 @@ func runnerScreenshotStabilitySettled( |
275 | 434 |
|
276 | 435 | #if AGENT_DEVICE_RUNNER_UNIT_TESTS |
277 | 436 | extension RunnerTests { |
| 437 | + func testKeyboardBandFactReadFailureIsStatedAsUnmeasurableNotAbsence() { |
| 438 | + // Absence would let a consumer claim the screen is clear of a keyboard on the strength of a read |
| 439 | + // that never answered. |
| 440 | + let fact = runnerKeyboardBandFact( |
| 441 | + readSucceeded: false, |
| 442 | + exists: false, |
| 443 | + frame: CGRect(x: 0, y: 198, width: 402, height: 204) |
| 444 | + ) |
| 445 | + XCTAssertEqual(fact, .unmeasurable(RunnerKeyboardBandReason.queryFailed)) |
| 446 | + XCTAssertEqual(fact.payload.kind, "unmeasurable") |
| 447 | + XCTAssertEqual(fact.payload.reason, RunnerKeyboardBandReason.queryFailed) |
| 448 | + XCTAssertNil(fact.payload.frame) |
| 449 | + } |
| 450 | + |
| 451 | + func testKeyboardBandFactPublishesAbsenceWhenTheQueryFindsNoKeyboard() { |
| 452 | + let fact = runnerKeyboardBandFact(readSucceeded: true, exists: false, frame: .zero) |
| 453 | + XCTAssertEqual(fact, .absent) |
| 454 | + XCTAssertEqual(fact.payload.kind, "absent") |
| 455 | + XCTAssertNil(fact.payload.frame) |
| 456 | + XCTAssertNil(fact.payload.reason) |
| 457 | + } |
| 458 | + |
| 459 | + func testKeyboardBandFactPublishesTheMeasuredBandInAppOrientationSpace() { |
| 460 | + // The landscape band measured on iPhone 17 Pro (iOS 26.2) after #2653: full width across the |
| 461 | + // bottom of a 402 pt-tall app, which is what the tree reported as a strip down the left edge. |
| 462 | + let frame = CGRect(x: 0, y: 198, width: 874, height: 204) |
| 463 | + let fact = runnerKeyboardBandFact(readSucceeded: true, exists: true, frame: frame) |
| 464 | + XCTAssertEqual(fact, .visible(frame)) |
| 465 | + let payload = fact.payload |
| 466 | + XCTAssertEqual(payload.kind, "visible") |
| 467 | + XCTAssertEqual(payload.frame, SnapshotRect(x: 0, y: 198, width: 874, height: 204)) |
| 468 | + XCTAssertNil(payload.reason) |
| 469 | + } |
| 470 | + |
| 471 | + func testKeyboardBandFactRefusesUnusableGeometryInsteadOfClaimingAbsence() { |
| 472 | + let nan = CGFloat(Double.nan) |
| 473 | + let infinite = CGFloat.infinity |
| 474 | + let unusable: [CGRect] = [ |
| 475 | + .zero, |
| 476 | + CGRect(x: 0, y: 198, width: 0, height: 204), |
| 477 | + CGRect(x: 0, y: 198, width: 874, height: -1), |
| 478 | + CGRect(x: 0, y: 198, width: -874, height: 204), |
| 479 | + CGRect(x: 0, y: nan, width: 874, height: 204), |
| 480 | + CGRect(x: 0, y: 198, width: nan, height: 204), |
| 481 | + CGRect(x: infinite, y: 198, width: 874, height: 204) |
| 482 | + ] |
| 483 | + for frame in unusable { |
| 484 | + let fact = runnerKeyboardBandFact(readSucceeded: true, exists: true, frame: frame) |
| 485 | + XCTAssertEqual( |
| 486 | + fact, |
| 487 | + .unmeasurable(RunnerKeyboardBandReason.unusableFrame), |
| 488 | + "expected \(frame) to be refused as a band" |
| 489 | + ) |
| 490 | + } |
| 491 | + } |
| 492 | + |
| 493 | + func testKeyboardBandFactPayloadRoundTripsThroughTheWireShape() throws { |
| 494 | + let cases: [RunnerKeyboardBandFact] = [ |
| 495 | + .visible(CGRect(x: 0, y: 583, width: 402, height: 291)), |
| 496 | + .absent, |
| 497 | + .unmeasurable(RunnerKeyboardBandReason.queryTimeout) |
| 498 | + ] |
| 499 | + for fact in cases { |
| 500 | + let data = try JSONEncoder().encode(fact.payload) |
| 501 | + // `encodeIfPresent` for the two optional fields: a fact carries its own evidence and nothing |
| 502 | + // else, so the daemon never has to distinguish a null from an absent key. |
| 503 | + let object = try XCTUnwrap(JSONSerialization.jsonObject(with: data) as? [String: Any]) |
| 504 | + switch fact { |
| 505 | + case .visible: |
| 506 | + XCTAssertNil(object["reason"]) |
| 507 | + XCTAssertNotNil(object["frame"]) |
| 508 | + case .absent: |
| 509 | + XCTAssertNil(object["frame"]) |
| 510 | + XCTAssertNil(object["reason"]) |
| 511 | + case .unmeasurable: |
| 512 | + XCTAssertNil(object["frame"]) |
| 513 | + XCTAssertNotNil(object["reason"]) |
| 514 | + } |
| 515 | + XCTAssertEqual(try JSONDecoder().decode(KeyboardBandFactPayload.self, from: data), fact.payload) |
| 516 | + } |
| 517 | + } |
| 518 | + |
278 | 519 | func testRunnerScreenshotStabilitySettledNeedsEnoughSamples() { |
279 | 520 | XCTAssertFalse(runnerScreenshotStabilitySettled([], requiredConsecutiveMatches: 3)) |
280 | 521 | XCTAssertFalse(runnerScreenshotStabilitySettled([Data([1])], requiredConsecutiveMatches: 3)) |
|
0 commit comments