diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift index 1bddbd560c..87ca6d6a58 100644 --- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift +++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift @@ -425,7 +425,11 @@ extension RunnerTests { guard pressTvRemote(button, duration: duration) else { return Response( ok: false, - error: ErrorPayload(code: "UNSUPPORTED_OPERATION", message: "remotePress is only supported on tvOS") + error: ErrorPayload( + code: RunnerWireErrorCode.hardwareControlUnavailable, + message: "remotePress is only supported on tvOS", + hint: "Only a tvOS target has a Siri Remote. On a TV target use tv-remote; on a phone or Mac, press the app's own control by its ref." + ) ) } return Response(ok: true, data: DataPayload(message: "remote pressed")) @@ -567,7 +571,7 @@ extension RunnerTests { return Response( ok: false, error: ErrorPayload( - code: "UNSUPPORTED_OPERATION", + code: RunnerWireErrorCode.hardwareControlUnavailable, message: "actionButton requires a device model with an Action Button", hint: "The Action Button is on iPhone 15 Pro and later and iPad Pro (M4) and later. Assign a Shortcut or App Intent to it in Settings > Action Button." ) @@ -579,7 +583,7 @@ extension RunnerTests { return Response( ok: false, error: ErrorPayload( - code: "UNSUPPORTED_OPERATION", + code: RunnerWireErrorCode.hardwareControlUnavailable, message: "\(command.command) requires a physical iPhone or iPad; XCUIDevice exposes no volume press on a simulator", hint: "hardware-button volume-up/volume-down is supported on physical iOS devices through the runner or Appium; iOS Simulators have no pressable volume key." ) @@ -608,7 +612,7 @@ extension RunnerTests { ) ) case .keyboardReturn: - var press: (wasVisible: Bool, pressed: Bool, visible: Bool)? + var press: (wasVisible: Bool, pressed: Bool, visible: Bool, fieldAttempted: Bool)? withBoundedInteractionIdleTimeoutIfSupported(activeApp, waits: .preEventSkipped) { press = pressKeyboardReturn(app: activeApp) } @@ -618,10 +622,7 @@ extension RunnerTests { if !result.pressed { return Response( ok: false, - error: ErrorPayload( - code: "UNSUPPORTED_OPERATION", - message: "Unable to press the iOS keyboard return key" - ) + error: result.fieldAttempted ? keyboardReturnFieldAttemptFailure : keyboardReturnRefusal ) } return Response( diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Keyboard.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Keyboard.swift index 78d3d3e6c3..e7779918dd 100644 --- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Keyboard.swift +++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Keyboard.swift @@ -287,6 +287,28 @@ extension RunnerTests { "An element whose center sits behind the on-screen keyboard is refused with tap_keyboard_occludes_target; one whose center stays above the keys presses normally. To end editing, tap the app's own Done/Cancel control, or use keyboard enter to press the return key when submission is wanted." } + /// The refusal a `keyboard enter` answers with when the control is missing: the keyboard exposes no + /// return-like key, and typing a return found no field to type into. It carries the runner's own code + /// so the host publishes `details.reason` instead of leaving callers to read the prose. The dispatch + /// disclosure stays `unknown` because typing the return can fail after XCTest sent it. + var keyboardReturnRefusal: ErrorPayload { + return ErrorPayload( + code: RunnerWireErrorCode.keyboardReturnUnavailable, + message: "Unable to press the keyboard return key: the keyboard exposes no return-like key and no text field was available to submit", + hint: "Tap the app's own submit control by its ref, or focus a text field with fill or type before asking keyboard enter to submit it." + ) + } + + /// The refusal for a sole text field that was found and tapped but would not take the return. It is + /// not an absent control, so it has no typed reason; the tap may have landed. + var keyboardReturnFieldAttemptFailure: ErrorPayload { + return ErrorPayload( + code: "UNSUPPORTED_OPERATION", + message: "Unable to press the keyboard return key: the only text field was found, but tapping it and typing a return failed", + hint: "Focus the field with fill or type, or tap the app's own submit control by its ref." + ) + } + // AX-free on purpose (screenshot bytes, not the accessibility tree) so it holds // under the same AX degradation the synthesized gesture lane is built to survive. @@ -332,26 +354,30 @@ extension RunnerTests { return runnerPngData(for: image) } - func pressKeyboardReturn(app: XCUIApplication) -> (wasVisible: Bool, pressed: Bool, visible: Bool) { + /// `fieldAttempted` is true when the sole-text-field route found a field and tapped it before typing, + /// so a failed press there is a failed attempt rather than a missing control. + func pressKeyboardReturn( + app: XCUIApplication + ) -> (wasVisible: Bool, pressed: Bool, visible: Bool, fieldAttempted: Bool) { #if os(tvOS) - return (wasVisible: false, pressed: pressTvRemote(.select), visible: false) + return (wasVisible: false, pressed: pressTvRemote(.select), visible: false, fieldAttempted: false) #elseif os(iOS) let wasVisible = isKeyboardVisible(app: app) if tapKeyboardReturnControl(app: app) { sleepFor(0.2) - return (wasVisible: wasVisible, pressed: true, visible: isKeyboardVisible(app: app)) + return (wasVisible: wasVisible, pressed: true, visible: isKeyboardVisible(app: app), fieldAttempted: false) } guard typeKeyboardReturn({ app.typeText(XCUIKeyboardKey.return.rawValue) }) else { if let singleTarget = singleTextEntryElement(app: app) { return pressKeyboardReturn(on: singleTarget, app: app, wasVisible: wasVisible) } - return (wasVisible: wasVisible, pressed: false, visible: isKeyboardVisible(app: app)) + return (wasVisible: wasVisible, pressed: false, visible: isKeyboardVisible(app: app), fieldAttempted: false) } sleepFor(0.2) - return (wasVisible: wasVisible, pressed: true, visible: isKeyboardVisible(app: app)) + return (wasVisible: wasVisible, pressed: true, visible: isKeyboardVisible(app: app), fieldAttempted: false) #else - return (wasVisible: false, pressed: false, visible: false) + return (wasVisible: false, pressed: false, visible: false, fieldAttempted: false) #endif } @@ -373,7 +399,7 @@ extension RunnerTests { on element: XCUIElement, app: XCUIApplication, wasVisible: Bool - ) -> (wasVisible: Bool, pressed: Bool, visible: Bool) { + ) -> (wasVisible: Bool, pressed: Bool, visible: Bool, fieldAttempted: Bool) { #if os(iOS) // `element` is bound by index, and the keyboard the tap raises shifts those indices, so the // return goes to whatever the tap focused rather than to a re-resolved `element`. @@ -382,12 +408,12 @@ extension RunnerTests { app.typeText(XCUIKeyboardKey.return.rawValue) }) guard typed else { - return (wasVisible: wasVisible, pressed: false, visible: isKeyboardVisible(app: app)) + return (wasVisible: wasVisible, pressed: false, visible: isKeyboardVisible(app: app), fieldAttempted: true) } sleepFor(0.2) - return (wasVisible: wasVisible, pressed: true, visible: isKeyboardVisible(app: app)) + return (wasVisible: wasVisible, pressed: true, visible: isKeyboardVisible(app: app), fieldAttempted: true) #else - return (wasVisible: wasVisible, pressed: false, visible: false) + return (wasVisible: wasVisible, pressed: false, visible: false, fieldAttempted: false) #endif } diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift index 9bec27637d..01d098d2cb 100644 --- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift +++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift @@ -102,7 +102,7 @@ extension RunnerTests { func performInAppBack(app: XCUIApplication) throws -> InAppBackOutcome { #if os(macOS) guard let back = macOSNavigationBackElement(app: app) else { - return .refused(ErrorPayload(message: "in-app back control is not available")) + return .refused(Self.macOSInAppBackControlRefusal) } let frame = back.frame if frame.isEmpty { @@ -602,6 +602,15 @@ extension RunnerTests { ) } + /// macOS `back` presses the app's own back control, read from its tree; when the app exposes none, + /// there is no gesture left to try, so it sends nothing. The refusal carries the runner's own code so + /// the host publishes `details.reason` and a caller never reads the refusal off the message prose. + static let macOSInAppBackControlRefusal = ErrorPayload( + code: RunnerWireErrorCode.inAppBackControlUnavailable, + message: "in-app back control is not available", + hint: "Press the app's visible back control by its ref." + ) + #if os(iOS) /// The last settle sample: the baseline the swipe's change is measured from. `stableSinceMs` is /// when the run of agreeing samples it ends began, and `sampledMs` when it was captured. diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift index 931dc150db..0454fa3ed9 100644 --- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift +++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift @@ -44,6 +44,10 @@ final class RunnerTests: XCTestCase { /// `BACK_SWIPE_UNVERIFIED` is one whose screen kept changing on its own before the swipe, or could /// not be sampled afterwards. Both ran the swipe. `BACK_SWIPE_NOT_DISPATCHED` is a back swipe that /// was refused before any touch went down, so dispatched: no. + /// `IN_APP_BACK_CONTROL_UNAVAILABLE` is macOS `back` finding no in-app back control, so it pressed + /// nothing. `KEYBOARD_RETURN_UNAVAILABLE` is `keyboard enter` finding nothing to submit. + /// `HARDWARE_CONTROL_UNAVAILABLE` is a press the runner answers that its target cannot perform. + /// The host publishes `details.reason` for all three. enum RunnerWireErrorCode { static let mainThreadTimeout = "MAIN_THREAD_TIMEOUT" static let appNotRunning = "APP_NOT_RUNNING" @@ -62,6 +66,20 @@ final class RunnerTests: XCTestCase { /// runner vouches for (#1606). The host reports it under `UNSUPPORTED_OPERATION` and publishes /// `details.reason`, so a caller never reads the refusal off the message prose. static let keyboardDismissUnavailable = "KEYBOARD_DISMISS_UNAVAILABLE" + /// A `keyboard enter` that found no return key to press and no text entry to submit through, so + /// nothing was submitted. The host reports it under `UNSUPPORTED_OPERATION` and publishes + /// `details.reason`; the disclosure stays `unknown` because typing the return can fail after XCTest + /// sent it. A sole field that was found but would not take the return is not this refusal. + static let keyboardReturnUnavailable = "KEYBOARD_RETURN_UNAVAILABLE" + /// A press of a hardware or Siri Remote control this target cannot perform: the press helper refuses + /// before pressing anything, so the host reports `UNSUPPORTED_OPERATION` with `details.reason` and + /// `dispatched: no`. Through the daemon the reachable case today is the Action Button on an iPhone + /// or iPad model without one; the simulator volume and non-tvOS remote cases are refused by runtime + /// admission before the runner is asked. + static let hardwareControlUnavailable = "HARDWARE_CONTROL_UNAVAILABLE" + /// macOS `back` found no in-app back control to press, so it sent nothing. The host keeps the + /// `COMMAND_FAILED` code such a code-less refusal always had and publishes `details.reason`. + static let inAppBackControlUnavailable = "IN_APP_BACK_CONTROL_UNAVAILABLE" /// Refuses a repeat of a `commandId` the runner already finished, when that command's own /// classification keeps no response body to replay. Nothing ran for the repeat, but the daemon's /// dispatch disclosure stays `unknown` — only the runner knows whether an earlier send of that id diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+KeyboardTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+KeyboardTests.swift index 207b05af92..1de368fdcb 100644 --- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+KeyboardTests.swift +++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+KeyboardTests.swift @@ -154,6 +154,22 @@ extension RunnerTests { XCTAssertNotEqual(dispatched.code, notDispatched.code) } + /// `keyboard enter` refusing for having nothing to submit is its own typed refusal, and the host + /// reads this code's literal to publish `details.reason`. The wire code alone is the contract. + func testKeyboardReturnRefusalNamesItsOwnCode() { + let refusal = keyboardReturnRefusal + XCTAssertEqual(refusal.code, "KEYBOARD_RETURN_UNAVAILABLE") + XCTAssertNotNil(refusal.hint) + } + + /// A sole field that was found and tapped but would not take the return is a failed attempt, not an + /// absent control, so it must not publish the unavailable reason. + func testKeyboardReturnFieldAttemptFailureIsNotTheTypedRefusal() { + let failure = keyboardReturnFieldAttemptFailure + XCTAssertEqual(failure.code, "UNSUPPORTED_OPERATION") + XCTAssertNotEqual(failure.code, keyboardReturnRefusal.code) + } + func testKeyboardBandFactPublishesAbsenceWhenTheCompleteCaptureHasNoKeyboard() { let fact = runnerKeyboardBandFact(exists: false, frame: .zero) XCTAssertEqual(fact, .absent) @@ -312,7 +328,10 @@ extension RunnerTests { XCTAssertEqual(textEntryInputCount(), 0) XCTAssertEqual(recordedFailures, 0) - XCTAssertEqual(response.error?.code, "UNSUPPORTED_OPERATION") + // The refusal names itself, so the host publishes its `details.reason`; the host still reports the + // command's own `UNSUPPORTED_OPERATION` for the caller. + XCTAssertEqual(response.error?.code, RunnerWireErrorCode.keyboardReturnUnavailable) + XCTAssertNotNil(response.error?.hint) } @MainActor diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+NavigationTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+NavigationTests.swift index 2007576d2b..2b63e7fc60 100644 --- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+NavigationTests.swift +++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+NavigationTests.swift @@ -580,6 +580,15 @@ extension RunnerTests { #endif + /// macOS `back` has one route: the app's own back control. Finding none sends nothing, so the refusal + /// names itself — the host publishes its `details.reason`, and a caller never reads the refusal off + /// the message. The literal is pinned as the wire value the host reads. + func testInAppBackControlRefusalNamesItsOwnCode() { + let refusal = Self.macOSInAppBackControlRefusal + XCTAssertEqual(refusal.code, "IN_APP_BACK_CONTROL_UNAVAILABLE") + XCTAssertNotNil(refusal.hint) + } + func testNavigationVisualObservationSeparatesChangeFromRefusal() { // A refused side makes the pair uncomparable, not "unchanged"; reading it as "unchanged" would // let a capture that refused become the reason `back` claims its swipe changed nothing. diff --git a/apple/runner/RUNNER_PROTOCOL.md b/apple/runner/RUNNER_PROTOCOL.md index e29eacadb1..bf1ab37a04 100644 --- a/apple/runner/RUNNER_PROTOCOL.md +++ b/apple/runner/RUNNER_PROTOCOL.md @@ -267,6 +267,20 @@ next step also carries `hint`, omitted here. A keyboard that stayed up answers o and the keyboard stayed visible. The host reports both under `UNSUPPORTED_OPERATION` and publishes the first one's `details.reason`. +Three more refusals name the control the target could not supply, so a caller never reads the refusal +off `message`. `KEYBOARD_RETURN_UNAVAILABLE` is a `keyboard enter` whose keyboard exposed no return-like +key and for which no text field could be found; it proves no submission, not that nothing ran, because +typing the return can fail after XCTest sent it. A sole text field that was found and tapped but would +not take the return answers `UNSUPPORTED_OPERATION` with no code, since the control exists and the tap +may have landed. `HARDWARE_CONTROL_UNAVAILABLE` is a press the runner answers that its target cannot +perform. The runner emits it for the Action Button on an iPhone or iPad model that has none, for a +volume press on a simulator, and for a Siri Remote press off tvOS. Runtime admission refuses the last +two before the runner is asked, so through the daemon only the Action Button case reaches a caller. +`IN_APP_BACK_CONTROL_UNAVAILABLE` is macOS `back` finding no in-app back control in the app's tree. The +last two press nothing. The host maps each to the code its command already refused with +(the first two to `UNSUPPORTED_OPERATION`, the macOS back refusal to the `COMMAND_FAILED` a code-less +reply produced) and publishes its `details.reason`. + `data` is command-specific. Common fields include snapshot nodes, text lookup results, gesture timing, visibility metadata, and screenshot or recording output details. Capture-plan snapshots carry `snapshotViewport`, the acquisition's declared viewport evidence. diff --git a/contracts/fixtures/dispatch-disclosure.json b/contracts/fixtures/dispatch-disclosure.json index 261f216a7d..429adb51cc 100644 --- a/contracts/fixtures/dispatch-disclosure.json +++ b/contracts/fixtures/dispatch-disclosure.json @@ -307,6 +307,24 @@ "trigger": "structured runner reply with code KEYBOARD_DISMISS_UNAVAILABLE: `keyboard dismiss` refused because the visible keyboard exposes no dismiss key, before any tap", "dispatched": "no" }, + { + "id": "ios-runner.reply.KEYBOARD_RETURN_UNAVAILABLE", + "producer": "ios-runner", + "trigger": "structured runner reply with code KEYBOARD_RETURN_UNAVAILABLE: `keyboard enter` found no return key to press and no text field to submit through; typing the return can fail after XCTest sent it", + "dispatched": "unknown" + }, + { + "id": "ios-runner.reply.HARDWARE_CONTROL_UNAVAILABLE", + "producer": "ios-runner", + "trigger": "structured runner reply with code HARDWARE_CONTROL_UNAVAILABLE: this target cannot perform the asked-for hardware or Siri Remote press, so nothing was pressed", + "dispatched": "no" + }, + { + "id": "ios-runner.reply.IN_APP_BACK_CONTROL_UNAVAILABLE", + "producer": "ios-runner", + "trigger": "structured runner reply with code IN_APP_BACK_CONTROL_UNAVAILABLE: macOS `back` found no in-app back control in the app's tree and pressed nothing", + "dispatched": "no" + }, { "id": "ios-runner.reply.unlisted-code", "producer": "ios-runner", @@ -493,6 +511,12 @@ "trigger": "fill's first clear-and-retype pass typed and failed verification; the second pass's adb input text then failed, so the fill reports unknown with details.dispatchedSteps counting the steps both passes sent", "dispatched": "unknown" }, + { + "id": "android-adb.keyboard-dismiss.ime-ignored-escape", + "producer": "android-adb", + "trigger": "keyboard dismiss: the IME kept the keyboard visible through every escape keyevent, which were already sent (details.reason keyboard_dismiss_unavailable)", + "dispatched": "unknown" + }, { "id": "android-helper.gesture.reported-failure", "producer": "android-helper", diff --git a/packages/apple-runner/src/__tests__/index-dispatch-disclosure.test.ts b/packages/apple-runner/src/__tests__/index-dispatch-disclosure.test.ts index 81a94e248a..c4cc29bae8 100644 --- a/packages/apple-runner/src/__tests__/index-dispatch-disclosure.test.ts +++ b/packages/apple-runner/src/__tests__/index-dispatch-disclosure.test.ts @@ -194,6 +194,11 @@ const DRIVERS: Record Promise> = { replyFailure('SYNTHESIZED_GESTURE_OUTCOME_UNKNOWN'), 'ios-runner.reply.KEYBOARD_DISMISS_UNAVAILABLE': () => replyFailure('KEYBOARD_DISMISS_UNAVAILABLE'), + 'ios-runner.reply.KEYBOARD_RETURN_UNAVAILABLE': () => replyFailure('KEYBOARD_RETURN_UNAVAILABLE'), + 'ios-runner.reply.HARDWARE_CONTROL_UNAVAILABLE': () => + replyFailure('HARDWARE_CONTROL_UNAVAILABLE'), + 'ios-runner.reply.IN_APP_BACK_CONTROL_UNAVAILABLE': () => + replyFailure('IN_APP_BACK_CONTROL_UNAVAILABLE'), 'ios-runner.reply.unlisted-code': () => replyFailure('XCTEST_RECORDED_FAILURE'), 'ios-runner.series.later-chunk-refused': pressSeriesRefusedOnSecondChunk, 'ios-runner.series.invalid-step-before-send': pressSeriesWithInvalidStep, diff --git a/packages/apple-runner/src/__tests__/runner-error-classification.test.ts b/packages/apple-runner/src/__tests__/runner-error-classification.test.ts index 44640bf88b..cc63351a9a 100644 --- a/packages/apple-runner/src/__tests__/runner-error-classification.test.ts +++ b/packages/apple-runner/src/__tests__/runner-error-classification.test.ts @@ -3,7 +3,10 @@ import { test } from 'vitest'; import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors'; import { COMMAND_ALREADY_FINISHED_RUNNER_CODE, + HARDWARE_CONTROL_UNAVAILABLE_RUNNER_CODE, + IN_APP_BACK_CONTROL_UNAVAILABLE_RUNNER_CODE, KEYBOARD_DISMISS_UNAVAILABLE_RUNNER_CODE, + KEYBOARD_RETURN_UNAVAILABLE_RUNNER_CODE, MAIN_THREAD_TIMEOUT_RUNNER_CODE, NO_TEXT_INPUT_AT_POINT_RUNNER_CODE, RUNNER_SCREEN_CAPTURE_REFUSAL_RUNNER_CODES, @@ -24,6 +27,7 @@ import { } from '../runner-error-classification.ts'; import { runnerConnectFailure, unwrittenConnectRefusal } from './runner-session-fixtures.ts'; import { + requireSwiftControlRefusalWireCodes, requireSwiftKeyboardDismissRefusalWireCode, requireSwiftThrownErrorWireCode, } from './runner-swift-settlement-fixtures.ts'; @@ -209,6 +213,61 @@ test('a keyboard dismiss refused for having no dismiss key keeps its code and pu assert.equal(dispatched.details.dispatched, 'unknown'); }); +// Three more refusals a caller could only tell apart by reading `message`. Each keeps the code its +// command already refused with, so only `details.reason` is added; the two that provably pressed +// nothing disclose `no`, and `keyboard enter` cannot, because its sole-field route taps the field +// before typing. +test('the hardware-control refusal keeps UNSUPPORTED_OPERATION and says nothing was pressed', () => { + assert.equal(HARDWARE_CONTROL_UNAVAILABLE_RUNNER_CODE, 'HARDWARE_CONTROL_UNAVAILABLE'); + const refusal = classifyRunnerReportedError(HARDWARE_CONTROL_UNAVAILABLE_RUNNER_CODE); + assert.equal(refusal.code, 'UNSUPPORTED_OPERATION'); + assert.deepEqual(refusal.details, { + runnerErrorCode: 'HARDWARE_CONTROL_UNAVAILABLE', + reason: 'hardware_control_unavailable', + dispatched: 'no', + }); + // The closest negative: the same sentence with no code earns no reason, so a consumer keyed on + // `reason` cannot mistake prose for the typed refusal. + const untyped = commandFailed('actionButton requires a device model with an Action Button'); + assert.equal(untyped.details?.reason, undefined); +}); + +test('the keyboard-return refusal keeps UNSUPPORTED_OPERATION and reports an unknown dispatch', () => { + assert.equal(KEYBOARD_RETURN_UNAVAILABLE_RUNNER_CODE, 'KEYBOARD_RETURN_UNAVAILABLE'); + const refusal = classifyRunnerReportedError(KEYBOARD_RETURN_UNAVAILABLE_RUNNER_CODE); + assert.equal(refusal.code, 'UNSUPPORTED_OPERATION'); + // The refusal says nothing about dispatch: the sole-text-field route taps the field before typing the + // return, so a refusal can follow a tap that landed. + assert.deepEqual(refusal.details, { + runnerErrorCode: 'KEYBOARD_RETURN_UNAVAILABLE', + reason: 'keyboard_return_unavailable', + dispatched: 'unknown', + }); + // The closest negative: the same sentence with no code earns no reason, so a consumer keyed on + // `reason` cannot mistake prose for the typed refusal. + const untyped = commandFailed( + 'Unable to press the keyboard return key: the keyboard exposes no return-like key and no text field was available to submit', + ); + assert.equal(untyped.details?.reason, undefined); +}); + +test('the macOS in-app back refusal publishes its reason under the code a code-less reply had', () => { + assert.equal(IN_APP_BACK_CONTROL_UNAVAILABLE_RUNNER_CODE, 'IN_APP_BACK_CONTROL_UNAVAILABLE'); + const refusal = classifyRunnerReportedError(IN_APP_BACK_CONTROL_UNAVAILABLE_RUNNER_CODE); + // That reply carried no code, so the host read COMMAND_FAILED; naming it must not move the command + // to a code its callers never saw. + assert.equal(refusal.code, 'COMMAND_FAILED'); + assert.deepEqual(refusal.details, { + runnerErrorCode: 'IN_APP_BACK_CONTROL_UNAVAILABLE', + reason: 'in_app_back_control_unavailable', + dispatched: 'no', + }); + // The closest negative: the base reply was a code-less COMMAND_FAILED, and prose alone still earns no + // reason, so a consumer keyed on `reason` cannot mistake it for the typed refusal. + const untyped = commandFailed('in-app back control is not available'); + assert.equal(untyped.details?.reason, undefined); +}); + test('retryable requires an AppError with COMMAND_FAILED', () => { assert.equal(isRetryableRunnerError(new Error('fetch failed')), false); assert.equal(isRetryableRunnerError(new AppError('DEVICE_NOT_FOUND', 'fetch failed')), false); @@ -609,6 +668,28 @@ test('the runner declares the wire code the keyboard-dismiss refusal publishes i ); }); +test('the runner declares the wire codes the control refusals publish their reasons under', () => { + const swift = requireSwiftControlRefusalWireCodes(); + assert.equal( + swift.keyboardReturnCode, + KEYBOARD_RETURN_UNAVAILABLE_RUNNER_CODE, + 'the runner must encode its nothing-to-submit refusal under the code the daemon maps to ' + + 'details.reason, or that reason becomes unreachable', + ); + assert.equal( + swift.hardwareControlCode, + HARDWARE_CONTROL_UNAVAILABLE_RUNNER_CODE, + 'the runner must encode its cannot-press-here refusal under the code the daemon maps to ' + + 'details.reason, or that reason becomes unreachable', + ); + assert.equal( + swift.inAppBackControlCode, + IN_APP_BACK_CONTROL_UNAVAILABLE_RUNNER_CODE, + 'the runner must encode its macOS no-back-control refusal under the code the daemon maps to ' + + 'details.reason, or that reason becomes unreachable', + ); +}); + // --- runner that predates the listener token --- test('a runner that does not require the token is session-fatal and never retried or replayed', () => { diff --git a/packages/apple-runner/src/__tests__/runner-swift-settlement-fixtures.ts b/packages/apple-runner/src/__tests__/runner-swift-settlement-fixtures.ts index 46d110dfb9..5cb9043cbf 100644 --- a/packages/apple-runner/src/__tests__/runner-swift-settlement-fixtures.ts +++ b/packages/apple-runner/src/__tests__/runner-swift-settlement-fixtures.ts @@ -192,3 +192,40 @@ export function requireSwiftKeyboardDismissRefusalWireCode(): string { ); return refusalCode; } + +/** + * The Swift declarations for the runner refusals that name a control or a key the target could not + * supply: `keyboard enter` with nothing to submit, a hardware or Siri Remote control this platform + * cannot express, and macOS `back` with no in-app back control. Each is thrown on a device lane, so the + * tie that keeps the host's `details.reason` row attached to it reads the declaration rather than a + * second copy of the literal. + */ +export function requireSwiftControlRefusalWireCodes(): { + keyboardReturnCode: string; + hardwareControlCode: string; + inAppBackControlCode: string; +} { + const codes = readSwiftWireErrorCodes(); + const members = [ + 'keyboardReturnUnavailable', + 'hardwareControlUnavailable', + 'inAppBackControlUnavailable', + ] as const; + const keys = ['keyboardReturnCode', 'hardwareControlCode', 'inAppBackControlCode'] as const; + const refusalCodes: Record = {}; + for (const [index, member] of members.entries()) { + const key = keys[index]!; + const refusalCode = codes[member]; + assert.ok( + refusalCode !== undefined, + `RunnerWireErrorCode must declare ${member}: the daemon publishes details.reason for this ` + + 'code, and a runner that stopped encoding it would leave that reason unreachable.', + ); + refusalCodes[key] = refusalCode; + } + return refusalCodes as { + keyboardReturnCode: string; + hardwareControlCode: string; + inAppBackControlCode: string; + }; +} diff --git a/packages/apple-runner/src/runner-contract.ts b/packages/apple-runner/src/runner-contract.ts index 7c17a89784..b48b1bb765 100644 --- a/packages/apple-runner/src/runner-contract.ts +++ b/packages/apple-runner/src/runner-contract.ts @@ -300,6 +300,35 @@ export const SCROLL_KEYBOARD_OCCLUDES_SURFACE_RUNNER_CODE = 'SCROLL_KEYBOARD_OCC */ export const KEYBOARD_DISMISS_UNAVAILABLE_RUNNER_CODE = 'KEYBOARD_DISMISS_UNAVAILABLE'; +/** + * The runner's own code refusing a `keyboard enter` whose keyboard exposes no return-like key and for + * which no text field could be found to submit through. Unlike the dismiss refusal it cannot prove + * nothing ran: typing the return can fail after XCTest sent it, so the disclosure stays `unknown`. A + * sole field that was found and tapped but would not take the return is not this refusal. It is the + * runner's vocabulary, declared here beside the set that keeps it off the wire, and consumers read + * `details.reason`. + */ +export const KEYBOARD_RETURN_UNAVAILABLE_RUNNER_CODE = 'KEYBOARD_RETURN_UNAVAILABLE'; + +/** + * The runner's own code refusing a press of a hardware or Siri Remote control its target cannot + * perform. Today that is the Action Button on an iPhone or iPad model without one: the daemon admits + * `action-button` for every iPhone and iPad and lets the runner answer whether the hardware is there. + * A volume key on a simulator and a remote button off tvOS are refused by runtime admission before the + * runner is reached, so those refusals carry `unsupported-device-kind` and `unsupported-platform-leaf`. + * Each refusal comes from the press helper answering false, which it does before pressing anything, so + * the reply proves nothing was sent. One code covers the family because the recovery is one question — + * does this target have that control — and the message names the control. + */ +export const HARDWARE_CONTROL_UNAVAILABLE_RUNNER_CODE = 'HARDWARE_CONTROL_UNAVAILABLE'; + +/** + * The runner's own code refusing macOS `back` when the app's tree exposes no in-app back control. The + * refusal answered with no code at all before, which left the caller reading prose; it keeps the + * `COMMAND_FAILED` code such a code-less reply always produced. + */ +export const IN_APP_BACK_CONTROL_UNAVAILABLE_RUNNER_CODE = 'IN_APP_BACK_CONTROL_UNAVAILABLE'; + /** * The codes the XCTest runner answers with when a resolved-display capture it was asked to make did * not happen (#2728): no window resolved so no display could be named, the resolved window named no @@ -381,6 +410,9 @@ const DIAGNOSTIC_ONLY_RUNNER_ERROR_CODES: ReadonlyMap< [ALERT_NOT_FOUND_RUNNER_CODE, {}], [SCROLL_KEYBOARD_OCCLUDES_SURFACE_RUNNER_CODE, {}], [KEYBOARD_DISMISS_UNAVAILABLE_RUNNER_CODE, {}], + [KEYBOARD_RETURN_UNAVAILABLE_RUNNER_CODE, {}], + [HARDWARE_CONTROL_UNAVAILABLE_RUNNER_CODE, {}], + [IN_APP_BACK_CONTROL_UNAVAILABLE_RUNNER_CODE, {}], [SYNTHESIZED_GESTURE_NOT_DISPATCHED_RUNNER_CODE, {}], [SYNTHESIZED_GESTURE_OUTCOME_UNKNOWN_RUNNER_CODE, {}], [BACK_SWIPE_NO_CHANGE_RUNNER_CODE, {}], @@ -391,11 +423,15 @@ const DIAGNOSTIC_ONLY_RUNNER_ERROR_CODES: ReadonlyMap< /** * Diagnostic-only codes that keep the wire code their command already refuses with instead of - * `COMMAND_FAILED`: the keyboard-dismiss refusal stays `UNSUPPORTED_OPERATION`, the code - * `keyboard dismiss` already refuses with. + * `COMMAND_FAILED`: the keyboard-dismiss, keyboard-return and hardware-control refusals stay + * `UNSUPPORTED_OPERATION`, the code each of those commands already refuses with. A macOS in-app back + * that found no control is absent here on purpose: that refusal carried no code at all, which the host + * read as `COMMAND_FAILED`, and adding a row must not move the command to a new code. */ const DIAGNOSTIC_RUNNER_ERROR_WIRE_CODES: ReadonlyMap = new Map([ [KEYBOARD_DISMISS_UNAVAILABLE_RUNNER_CODE, 'UNSUPPORTED_OPERATION'], + [KEYBOARD_RETURN_UNAVAILABLE_RUNNER_CODE, 'UNSUPPORTED_OPERATION'], + [HARDWARE_CONTROL_UNAVAILABLE_RUNNER_CODE, 'UNSUPPORTED_OPERATION'], ]); /** @@ -414,6 +450,9 @@ const RUNNER_REPORTED_ERROR_REASONS: ReadonlyMap = new [SYNTHESIZED_GESTURE_NOT_DISPATCHED_RUNNER_CODE, 'no'], [BACK_SWIPE_NOT_DISPATCHED_RUNNER_CODE, 'no'], [KEYBOARD_DISMISS_UNAVAILABLE_RUNNER_CODE, 'no'], + [HARDWARE_CONTROL_UNAVAILABLE_RUNNER_CODE, 'no'], + [IN_APP_BACK_CONTROL_UNAVAILABLE_RUNNER_CODE, 'no'], ...[...RUNNER_SCREEN_CAPTURE_REFUSAL_RUNNER_CODES].map((code) => [code, 'no'] as const), ]); @@ -458,7 +499,10 @@ type RunnerReportedErrorReason = | 'back_swipe_no_change' | 'back_swipe_unverified' | 'back_swipe_not_dispatched' - | 'keyboard_dismiss_unavailable'; + | 'keyboard_dismiss_unavailable' + | 'keyboard_return_unavailable' + | 'hardware_control_unavailable' + | 'in_app_back_control_unavailable'; /** Wire code plus the details every path must publish for one runner-reported error code. */ export type RunnerReportedErrorClass = Readonly<{ diff --git a/packages/command-surface/src/system/index.ts b/packages/command-surface/src/system/index.ts index f6ede050c7..07de4cac1e 100644 --- a/packages/command-surface/src/system/index.ts +++ b/packages/command-surface/src/system/index.ts @@ -301,11 +301,11 @@ const foldCommandDescription = `Fold or unfold a foldable iPhone simulator (iPho const appSwitcherCommandDescription = 'Open the device app switcher to inspect or change foreground apps. This changes the visible system UI and may move focus away from the current app.'; const keyboardCommandDescription = - 'Inspect Android keyboard visibility/type or press/dismiss the device keyboard. The dismiss action hides the keyboard. It taps the keyboard dismiss/hide key when one is exposed, verifies the keyboard closed, and reports UNSUPPORTED_OPERATION when the keyboard stays up \u2014 background taps are never attempted. On iOS a keyboard with no dismiss key adds error.details.reason keyboard_dismiss_unavailable with dispatched: no; one whose key was tapped and stayed visible has no reason and dispatched: unknown.'; + 'Inspect Android keyboard visibility/type or press/dismiss the device keyboard. The dismiss action hides the keyboard. It taps the keyboard dismiss/hide key when one is exposed, verifies the keyboard closed, and reports UNSUPPORTED_OPERATION when the keyboard stays up \u2014 background taps are never attempted. On iOS a keyboard with no dismiss key adds error.details.reason keyboard_dismiss_unavailable with dispatched: no; one whose key was tapped and stayed visible has no reason and dispatched: unknown. Android reports keyboard_dismiss_unavailable with dispatched: unknown, since its own dismiss keyevents were already sent.'; const clipboardCommandDescription = 'Read the current device clipboard text, or replace its contents with the given text. Android runs both through the clipboard service shell command, and a build that implements none (Android 16 does not) refuses with UNSUPPORTED_OPERATION rather than reporting an empty clipboard.'; const actionButtonCommandDescription = - 'Press the iPhone or iPad Action Button once. The press is dispatched without activating the session app and nothing is re-observed afterwards, so the app keeps the state the press found. What the system does with the press is not observed by this command: Simulators run no Shortcuts or App Intents, so delivery to an assigned Shortcut is verifiable only on a physical iPhone.'; + 'Press the iPhone or iPad Action Button once. The press is dispatched without activating the session app and nothing is re-observed afterwards, so the app keeps the state the press found. What the system does with the press is not observed by this command: Simulators run no Shortcuts or App Intents, so delivery to an assigned Shortcut is verifiable only on a physical iPhone. A model with no Action Button refuses with UNSUPPORTED_OPERATION, error.details.reason hardware_control_unavailable and dispatched: no.'; const tvRemoteCommandDescription = 'Press or long-press a TV remote button on Android TV, tvOS, or Vega OS. Android TV also supports volume, power, media, channel, guide, captions, input, color keys, and android-keycode:N. tvOS and Vega OS support up, down, left, right, select, menu, home, and back. Phones and WebDriver sessions are unsupported. The aliases ok, center, and enter map to select.'; @@ -734,7 +734,7 @@ const actionButtonCommandFacet = defineParameterlessCommandFacet({ description: actionButtonCommandDescription, text: { summary: 'Press the iPhone or iPad Action Button', - searchHint: 'hardware', + searchHint: 'side switch', cliDetail: 'iPhone and iPad only. The runner asks the device for the button and reports unsupported when that model has none.', }, diff --git a/packages/platform-android/src/__tests__/device-input-state.test.ts b/packages/platform-android/src/__tests__/device-input-state.test.ts index 10cf3d73b5..8e15bb51d1 100644 --- a/packages/platform-android/src/__tests__/device-input-state.test.ts +++ b/packages/platform-android/src/__tests__/device-input-state.test.ts @@ -391,6 +391,10 @@ test('dismissAndroidKeyboard fails explicitly when non-navigation dismiss does n await assertRejectsAppError(() => dismissAndroidKeyboard(device), { code: 'UNSUPPORTED_OPERATION', message: /without back navigation/i, + // The refusal is typed, so a caller never reads the prose to learn which of the IME refusals it + // got. `unknown` and not `no`: the escape keyevents above reached the device. + reason: 'keyboard_dismiss_unavailable', + dispatched: 'unknown', }); const flat = calls.map((args) => args.join(' ')); diff --git a/packages/platform-android/src/__tests__/index-dispatch-disclosure.test.ts b/packages/platform-android/src/__tests__/index-dispatch-disclosure.test.ts index 935e0b1cef..a60460a170 100644 --- a/packages/platform-android/src/__tests__/index-dispatch-disclosure.test.ts +++ b/packages/platform-android/src/__tests__/index-dispatch-disclosure.test.ts @@ -14,6 +14,7 @@ import { type AndroidAdbExecutor, } from '../adb-executor.ts'; import { completeAndroidFillVerification } from '../fill-verification.ts'; +import { dismissAndroidKeyboard } from '../device-input-state.ts'; import { doubleTapAndroid, pressAndroid } from '../input-actions.ts'; import { resetAndroidSnapshotHelperSessions } from '../snapshot-helper-session-lifecycle.ts'; import { fillAndroid, typeAndroid } from '../text-input.ts'; @@ -176,6 +177,36 @@ async function oneShotGesture(instrument: AndroidAdbExecutor): Promise { ); } +/** + * `keyboard dismiss` on a keyboard the escape keyevent never hides: the loop runs its two attempts and + * the producer refuses. Each `input keyevent` it sent counts as a dispatched step, so the disclosure + * cannot be `no`. + */ +async function dismissAgainstImeThatIgnoresEscape(): Promise { + let escapeKeyevents = 0; + await withFakeAdb( + (args) => { + const flat = args.join(' '); + if (flat === 'shell dumpsys input_method') { + return ['mInputShown=true mIsInputViewShown=true', 'inputType=0x1'].join('\n'); + } + if (flat === 'shell input keyevent 111') { + escapeKeyevents += 1; + return ''; + } + return { stderr: `unexpected args: ${flat}`, exitCode: 1 }; + }, + async ({ device }) => { + try { + await dismissAndroidKeyboard(device); + } catch (error) { + assert.equal(escapeKeyevents, 2, 'the refusal follows both scripted escape keyevents'); + throw error; + } + }, + ); +} + const HELPER_REPORTED_FAILURE = resultRecord({ ok: 'false', errorType: 'java.lang.IllegalStateException', @@ -244,6 +275,9 @@ const DRIVERS: Record Promise; dispatchedSteps?: actualInput: null, }), }, + 'android-adb.keyboard-dismiss.ime-ignored-escape': { + drive: dismissAgainstImeThatIgnoresEscape, + }, 'android-helper.gesture.reported-failure': { drive: () => oneShotGesture(async () => ({ exitCode: 0, stdout: HELPER_REPORTED_FAILURE, stderr: '' })), diff --git a/packages/platform-android/src/device-input-state.ts b/packages/platform-android/src/device-input-state.ts index cca08b2059..930f3d6447 100644 --- a/packages/platform-android/src/device-input-state.ts +++ b/packages/platform-android/src/device-input-state.ts @@ -33,6 +33,13 @@ const ANDROID_TEXT_VARIATION_VISIBLE_PASSWORD = 0x00000090; const ANDROID_KEYBOARD_DISMISS_MAX_ATTEMPTS = 2; const ANDROID_KEYBOARD_DISMISS_RETRY_DELAY_MS = 120; const ANDROID_KEYCODE_ESCAPE = '111'; +/** + * `details.reason` of a `keyboard dismiss` whose keyboard stayed up. One reason covers both platforms + * because the concept and the recovery are one thing: the safe mechanism this platform has would not + * bring the keyboard down, so press the app's own control. What differs is how far each got, and + * `details.dispatched` says that, never the reason. + */ +const ANDROID_KEYBOARD_DISMISS_UNAVAILABLE_REASON = 'keyboard_dismiss_unavailable'; const ANDROID_KEYBOARD_VISIBILITY_KEYS = [ 'mInputShown', 'mIsInputViewShown', @@ -126,6 +133,11 @@ export async function dismissAndroidKeyboardWithAdb( 'UNSUPPORTED_OPERATION', 'Android keyboard dismiss is unavailable for the current IME without back navigation.', { + // The same reason the Apple runner publishes for a keyboard that stays up: the safe mechanism + // this platform has would not bring it down. `dispatched` is the producer's own verdict and + // differs here — the escape keyevents above went out, so the disclosure cannot be `no`. + reason: ANDROID_KEYBOARD_DISMISS_UNAVAILABLE_REASON, + dispatched: 'unknown', attempts, inputType: state.inputType, type: state.type, diff --git a/src/commands/schema/cli-help.ts b/src/commands/schema/cli-help.ts index 869e8455b6..7dfa20686c 100644 --- a/src/commands/schema/cli-help.ts +++ b/src/commands/schema/cli-help.ts @@ -106,7 +106,7 @@ Text entry: fill replaces; type appends to an already-focused field: fill 'id="field-email"' "qa@example.com"; type "Handle with care" --delay-ms 80 fill "" clears the field (replace with nothing); the empty argument must be present -- fill alone is a missing argument. For dropped iOS text, retry with --delay-ms before clipboard paste (also Limrun iOS). - Element presses behind the keyboard are refused with tap_keyboard_occludes_target. keyboard dismiss taps its own dismiss key when one exists, else UNSUPPORTED_OPERATION (iOS: error.details.reason keyboard_dismiss_unavailable, dispatched: no). Android: try dismiss before back. iOS: when both fail, never tap static text/headings; prefer type "\\n" to submit. + Element presses behind the keyboard are refused with tap_keyboard_occludes_target. keyboard dismiss taps its own dismiss key when one exists, else UNSUPPORTED_OPERATION (error.details.reason keyboard_dismiss_unavailable). Android: try dismiss before back. iOS: when both fail, never tap static text/headings; prefer type "\\n" to submit. iOS paste-prompt limits and Android IME/handwriting capture quirks: help debugging. Session ordering: diff --git a/test/repo-guards/runner-refusal-reason-docs.test.ts b/test/repo-guards/runner-refusal-reason-docs.test.ts new file mode 100644 index 0000000000..a5d452032b --- /dev/null +++ b/test/repo-guards/runner-refusal-reason-docs.test.ts @@ -0,0 +1,102 @@ +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { test } from 'vitest'; +import { parseSync } from 'oxc-parser'; + +/** + * `error.details.reason` is a published vocabulary: a client that branches on it treats an + * undocumented member as an unknown value. The runner refusal reasons are the members a caller reads to + * decide whether resending is safe, so every member of the union in `runner-contract.ts` has to appear + * in the command docs in the same change that adds it. Nothing else connects the union to the doc: the + * classifier publishes the reason from a code, and the doc is prose a reader follows. + */ + +const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..'); +const contractPath = path.join(repoRoot, 'packages/apple-runner/src/runner-contract.ts'); +const commandsDocPath = path.join(repoRoot, 'website/docs/docs/commands.md'); + +test('every runner refusal reason is documented in the command docs', () => { + const reasons = runnerReportedErrorReasons(readFile(contractPath)); + const docs = readFile(commandsDocPath); + for (const reason of reasons) { + assert.ok( + documentsReason(docs, reason), + `commands.md must document the ${reason} reason: runner-contract.ts publishes it as ` + + 'details.reason and a client cannot branch on a value it was never told exists.', + ); + } +}); + +test('a documented reason does not stand in for a longer undocumented one', () => { + assert.ok(documentsReason('reports `back_swipe_no_change` here', 'back_swipe_no_change')); + assert.ok(documentsReason('reason: back_swipe_no_change.', 'back_swipe_no_change')); + assert.ok(!documentsReason('reports `back_swipe_no_change_extra`', 'back_swipe_no_change')); + assert.ok(!documentsReason('reports `pre_back_swipe_no_change`', 'back_swipe_no_change')); + assert.ok(!documentsReason('reports back-swipe_no_change-x', 'swipe_no_change')); +}); + +test('reason extraction reads every member of the union, not the ones it recognises', () => { + assert.deepEqual( + runnerReportedErrorReasons(` + const UNRELATED = ['not_a_reason_member']; + type RunnerReportedErrorReason = + | 'runner_busy' + | 'keyboard-2' + | 'keyboard_dismiss_unavailable'; + `), + ['runner_busy', 'keyboard-2', 'keyboard_dismiss_unavailable'], + ); +}); + +test('reason extraction rejects every unsupported member instead of dropping it', () => { + for (const member of ['RunnerBusy | OtherReason', 'OTHER_REASONS', 'string']) { + assert.throws( + () => runnerReportedErrorReasons(`type RunnerReportedErrorReason = ${member};`), + /unsupported member in RunnerReportedErrorReason/, + ); + } + assert.throws( + () => runnerReportedErrorReasons(`type RunnerReportedErrorReason = 'runner_busy' | string;`), + /unsupported member in RunnerReportedErrorReason/, + ); +}); + +/** Whether `docs` names `reason` as a whole token, so a longer reason that extends it does not count. */ +function documentsReason(docs: string, reason: string): boolean { + assert.match(reason, /^[a-z0-9_-]+$/, 'a reason is a lowercase token, so it needs no escaping'); + return new RegExp(`(? + statement.type === 'TSTypeAliasDeclaration' && + statement.id.type === 'Identifier' && + statement.id.name === 'RunnerReportedErrorReason', + ); + assert.ok( + declaration !== undefined && declaration.type === 'TSTypeAliasDeclaration', + 'runner-contract.ts must declare the RunnerReportedErrorReason union: it is the published ' + + 'vocabulary this guard reads.', + ); + const union = declaration.typeAnnotation; + const members = union.type === 'TSUnionType' ? union.types : [union]; + return members.map((member) => { + assert.ok( + member.type === 'TSLiteralType' && + member.literal.type === 'Literal' && + typeof member.literal.value === 'string', + `unsupported member in RunnerReportedErrorReason: ${member.type}`, + ); + return member.literal.value; + }); +} + +function readFile(target: string): string { + return fs.readFileSync(target, 'utf8'); +} diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md index f0abcae1df..034d20b130 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -123,7 +123,7 @@ iOS Simulator launch behavior: Back, orientation, and hardware buttons: -- `back` uses app-owned back navigation: the back keyevent on Android, the visible back control on macOS, and the Siri Remote Menu button on tvOS. `--in-app` names this default explicitly. +- `back` uses app-owned back navigation: the back keyevent on Android, the visible back control on macOS, and the Siri Remote Menu button on tvOS. `--in-app` names this default explicitly. macOS finds that control by the app's own back identifier or "Back" label; an app that exposes neither refuses with `error.details.reason: in_app_back_control_unavailable` under `COMMAND_FAILED` and `dispatched: no`, pressing nothing, so press the app's visible back control by its ref. - On iOS, `back` first looks for the navigation bar's system back button (a button with the identifier `BackButton` inside a navigation bar), read fresh in the same call. It presses that button only when exactly one live, hittable one is found, the app's accessibility tree is readable (it is not read when XCTest could not query it earlier in the session), and two reads of the navigation bars at least 0.05 s apart agree, so a screen that is still being pushed is not taken for the screen to go back from. After the tap, `back` reads the navigation bars again, about every 0.05 s, and succeeds once one of these changes: the number of navigation bars, the number of back buttons (for example, the button is gone at the root screen), or a back button's title. If none changes, it reports `back_swipe_unverified` and does not swipe. A bar's title alone never counts, because a title can update itself, such as a countdown timer. A back button that only moves never counts either, because a tap that goes nowhere can still move it, such as when a large title collapses. So a pop that leaves the back button as it was, for example between two screens whose back buttons show the same title (such as an app that titles every back button "Back"), also reports `back_swipe_unverified`. A back button whose own title updates itself can still be misread as a navigation. Before and after the tap, reads start for up to 1 s each; a read that is still running at that point finishes, or ends at XCTest's own query timeout. A read that is still running can take well past the 1 s; about 2 s was measured on a CI simulator. After the tap, when no read in that 1 s saw a change, `back` starts one more read after it, so a pop can still be confirmed on a slow host. That read can also fail, or hang until XCTest's query timeout; both report `back_swipe_unverified`. When an XCTest query hangs, `back` sends nothing more: before the tap it reports `back_swipe_not_dispatched`, and after the tap `back_swipe_unverified`. Only the system back button counts: a custom bar button titled "Back", or a "Back" button in a toolbar, is never pressed. With no such button, with two or more (such as a sheet over a stack), when the tree cannot be read, when the bars do not hold still within 1 s, or when the tap is refused before it is sent, `back` is the left-edge back swipe, with or without `--in-app` or `--system`. When XCTest cannot resolve the app's window, the swipe samples the device's only screen: on a single-screen iPhone, or on an iPad only while the app provably fills its screen; otherwise it refuses with `APP_SCREEN_UNRESOLVED`. The swipe succeeds only when the app's screen, drawn as a 48×96 grayscale grid with its top 7 rows left out (in portrait, the status bar and Dynamic Island band, whether the status bar is shown or hidden; in landscape the iPhone status bar is hidden and the Dynamic Island sits at a side edge, outside those rows), differs in more than 1% of the remaining cells by more than 24 of 256 levels. A small spinner usually stays under that; a larger animation can still count as a change. The change counted is the one between the sample taken immediately before the swipe and the one taken about 0.1 s after it, so a screen that changes on its own inside that gap, after it looked still, can be misread as a back navigation; verify with `snapshot` when the screen has auto-advancing content. Before it swipes, it waits for the screen to stop changing, with a 0.05 s pause between captures (each capture adds its own time), within a settle budget of 2 s that extends on a host whose captures are slow enough that a still screen needs more time. The screen must stay still for the contact allowance (0.2 s on a simulator, 0.4 s on a physical device), a 0.25 s margin, and the slowest capture: about 0.55 s in all on a simulator. The margin keeps a screen that repaints itself about every 0.5 s, such as a carousel, from looking still, so its next repaint is not read as a back; it does not depend on the 0.1 s wait after the swipe. A screen that repaints on its own more often than the still span never settles, and `back` reports `back_swipe_unverified`; the runner's tests check this with a screen that repaints every 0.45 s. A still screen usually settles in about 0.6 s on a simulator, and in about 1.4 s on a physical iPhone, based on the 0.4 s capture measured on one iPhone 17 Pro with iOS 27.0.1 ([PR #4460 evidence](https://github.com/callstack/agent-device/pull/4460#issuecomment-6828546541)). - `reason: back_swipe_no_change`: the swipe was sent and the screen did not change. Press the visible back or close control. - `reason: back_swipe_unverified`: the back button was pressed but the navigation bar's back buttons did not change within 1 s or on one more read after it or an XCTest query hung after the tap, or the swipe may or may not have navigated, because the screen kept changing before the swipe, the swipe took longer than the screen had been still, or the screen could not be sampled after it. Check with `snapshot`. A real pop on a stack of three or more screens also answers this after the full 1 s when the outgoing and incoming back buttons share a label. @@ -134,10 +134,10 @@ Back, orientation, and hardware buttons: - `back --system` sends system back input: the Android back keyevent, the same iOS back as the default, or the tvOS Siri Remote Menu button. macOS has no system back, so it refuses before dispatch. - `orientation portrait|portrait-upside-down|landscape-left|landscape-right` works on iOS and Android mobile targets only. On ADB-backed Android it turns auto-rotate off, and the lock persists after the session ends until something turns it back on. In both default and scoped simulator sets, an iPhone Duo classified with more than one integrated panel refuses `portrait-upside-down` and rotates through the fold helper. It succeeds only when the lit panel shows the requested orientation; if it never does, or the simulator never reports a single lit panel, the command fails with `orientation-unverified`. Unresolved guest reads are retried inside the settle loop; an unresolved final read reports `orientation-panel-table-unavailable`. The picker offsets were measured on iPhone Duo; a new multi-panel model needs its own mapping. A simulator classified with one panel, or whose first classification read is unresolved, uses the standard runner rotation. - `orientation auto` hands rotation back to the sensor on ADB-backed Android, local or Limrun (`accelerometer_rotation=1`, `user_rotation` untouched), and reports `orientation: "auto"`. It does not wait for the display to rotate, because there is no target rotation: the sensor decides, and an emulator usually settles on portrait. Every other backend refuses `auto` with `UNSUPPORTED_OPERATION`. -- `action-button` presses the iPhone or iPad Action Button once. It takes no arguments, no hold duration, and no `--settle`, and it doesn't activate the session app or drive Camera Control. Other platforms refuse it, and a model without the button (an iPhone SE, most iPad simulators) fails with `UNSUPPORTED_OPERATION`. +- `action-button` presses the iPhone or iPad Action Button once. It takes no arguments, no hold duration, and no `--settle`, and it doesn't activate the session app or drive Camera Control. Other platforms refuse it, and a model without the button (an iPhone SE, most iPad simulators) fails with `UNSUPPORTED_OPERATION` and `error.details.reason: hardware_control_unavailable` with `dispatched: no` — nothing was pressed. - `action-button` reports that the press was dispatched, not what it triggered. Simulators run no Shortcuts or App Intents, so verify the outcome on a physical iPhone. Expect a press to take about five seconds on a Simulator. - `hardware-button