Skip to content

Commit dbf400b

Browse files
thymikeeclaude
andcommitted
fix(ios): hold the back bar still before the tap and surface a hung query
- Read the bar state twice around the button lookup and tap only when the two reads agree and contain the button's frame, so a push still animating is not taken for the state a pop changes. - Compare bar count, identifier, static-text titles, and back buttons. - Start bar reads only within the 1 s budget, checked before each bar's snapshot; document what bounds a read in flight. - Re-record a hung XCTest query as record(_:) requires, send nothing more: BACK_SWIPE_NOT_DISPATCHED before the tap, BACK_SWIPE_UNVERIFIED after it. - Drop the dead outcome guard on the XCTest tap fallback. - Correct the visionOS back hints; a thrown tap no longer logs a swipe verification error line. - Test the two-candidate rule, the skipped read, and hung queries; the lookup-issue test asserts the swipe path, not a swipe outcome. - Name the simulator still span in commands.md. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 0d17e3e commit dbf400b

8 files changed

Lines changed: 369 additions & 98 deletions

File tree

‎apple/runner/AgentDeviceRunner/AgentDeviceRunner/AgentDeviceRunnerAppFixtures.m‎

Lines changed: 35 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,36 @@ - (void)navigationController:(UINavigationController *)navigationController
104104
}
105105
@end
106106

107+
// `--two-stacks` shows two pushed navigation stacks, one above the other, so two hittable system
108+
// back buttons are on screen at once and neither is the one `back` should press.
109+
@interface AgentDeviceTwoStacksBackFixture : UIViewController
110+
@end
111+
112+
@implementation AgentDeviceTwoStacksBackFixture
113+
- (void)viewDidLoad {
114+
[super viewDidLoad];
115+
self.view.backgroundColor = UIColor.systemBackgroundColor;
116+
UIStackView *stack = [UIStackView new];
117+
stack.axis = UILayoutConstraintAxisVertical;
118+
stack.distribution = UIStackViewDistributionFillEqually;
119+
stack.translatesAutoresizingMaskIntoConstraints = NO;
120+
[self.view addSubview:stack];
121+
[NSLayoutConstraint activateConstraints:@[
122+
[stack.topAnchor constraintEqualToAnchor:self.view.safeAreaLayoutGuide.topAnchor],
123+
[stack.bottomAnchor constraintEqualToAnchor:self.view.bottomAnchor],
124+
[stack.leadingAnchor constraintEqualToAnchor:self.view.leadingAnchor],
125+
[stack.trailingAnchor constraintEqualToAnchor:self.view.trailingAnchor],
126+
]];
127+
for (NSInteger index = 0; index < 2; index++) {
128+
AgentDeviceBackNavigationFixture *child = [[AgentDeviceBackNavigationFixture alloc] initWithCustomBackItem:NO
129+
blockedBack:NO];
130+
[self addChildViewController:child];
131+
[stack addArrangedSubview:child.view];
132+
[child didMoveToParentViewController:self];
133+
}
134+
}
135+
@end
136+
107137
@interface AgentDeviceRunnerFixtureViewController () <UNUserNotificationCenterDelegate>
108138
// Held for the app's lifetime: a window nobody retained would be gone before the test queried it.
109139
@property(nonatomic, strong) UIWindow *secondWindow;
@@ -438,10 +468,11 @@ - (void)viewDidAppear:(BOOL)animated {
438468
self.alertFixtureStarted = YES;
439469
BOOL customBackItem = [NSProcessInfo.processInfo.arguments containsObject:@"--custom-back-item"];
440470
BOOL blockedBack = [NSProcessInfo.processInfo.arguments containsObject:@"--blocked-back"];
441-
[self presentViewController:[[AgentDeviceBackNavigationFixture alloc] initWithCustomBackItem:customBackItem
442-
blockedBack:blockedBack]
443-
animated:NO
444-
completion:nil];
471+
UIViewController *fixture = [NSProcessInfo.processInfo.arguments containsObject:@"--two-stacks"]
472+
? [AgentDeviceTwoStacksBackFixture new]
473+
: [[AgentDeviceBackNavigationFixture alloc] initWithCustomBackItem:customBackItem blockedBack:blockedBack];
474+
fixture.modalPresentationStyle = UIModalPresentationFullScreen;
475+
[self presentViewController:fixture animated:NO completion:nil];
445476
}
446477
if (!self.alertFixtureStarted &&
447478
([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-alert-decline-choice"] ||

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift‎

Lines changed: 201 additions & 72 deletions
Large diffs are not rendered by default.

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -219,9 +219,9 @@ final class RunnerTests: XCTestCase {
219219
var litPanelWindowWalkIssueForTesting = false
220220

221221
#if os(iOS)
222-
/// Records an XCTest issue during every navigation bar read of this phase of iOS `back`, as a back
223-
/// button that vanishes mid-transition does.
224-
var navigationBarBackReadIssueForTesting: NavigationBarBackReadPhase?
222+
/// Records an XCTest issue with this description during every navigation bar read of this phase
223+
/// of iOS `back`, as a back button that vanishes mid-transition, or a hung query, does.
224+
var navigationBarBackReadIssueForTesting: (phase: NavigationBarBackReadPhase, description: String)?
225225

226226
/// What the last iOS `back` saw of the navigation bar back button, so a test can tell the button
227227
/// path from the swipe when both navigate.
@@ -325,6 +325,14 @@ final class RunnerTests: XCTestCase {
325325
"Failed to resolve query"
326326
]
327327

328+
/// XCTest's wording for a query that hung. It must keep reaching `record(_:)`: a read that holds
329+
/// its issues records this one again.
330+
static let hungQueryIssueWording = "Timed out while evaluating UI query"
331+
332+
static func isHungQueryIssueDescription(_ description: String) -> Bool {
333+
description.contains(hungQueryIssueWording)
334+
}
335+
328336
/// True for the one recorded-issue class the runner deliberately mutes: an AX-server error
329337
/// (`kAXError*`, deliberately covering kAXErrorIllegalArgument and its sibling codes) inside one
330338
/// of the fetch wordings above. Variants without that token MUST keep recording: the timeout

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+NavigationTests.swift‎

Lines changed: 97 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -91,31 +91,103 @@ extension RunnerTests {
9191

9292
/// An XCTest issue while the back button is looked up, such as a button gone mid-transition, means
9393
/// no button: back answers from the swipe path. An issue that escaped the read would fail this
94-
/// test as it fails the command with a recorded failure.
94+
/// test as it fails the command with a recorded failure. The swipe's own outcome is not asserted:
95+
/// iOS 27 pops this fixture on the edge swipe even with its interactive pop turned off.
9596
@MainActor
9697
func testInAppBackWithAnIssueInTheButtonLookupAnswersFromTheSwipe() throws {
9798
_ = try launchBackNavigationFixture(["--agent-device-back-navigation-bar"])
9899
defer { endBackFixture() }
99-
navigationBarBackReadIssueForTesting = .lookup
100+
navigationBarBackReadIssueForTesting = (.lookup, Self.vanishedBackButtonIssue)
100101
defer { navigationBarBackReadIssueForTesting = nil }
101102

102103
let response = try execute(command: try runnerCommandFixture(
103104
#"{"command":"backInApp","commandId":"back-lookup-issue","appBundleId":"com.callstack.agentdevice.runner"}"#
104105
))
105106

106-
XCTAssertTrue(response.ok, "the swipe answered: \(String(describing: response.error))")
107+
XCTAssertNotEqual(response.error?.code, "XCTEST_RECORDED_FAILURE")
107108
let trace = try XCTUnwrap(lastNavigationBarBackTraceForTesting)
108109
XCTAssertEqual(trace.found, "unreadable")
109110
XCTAssertFalse(trace.pressed, "back answered from the swipe path")
110111
}
111112

113+
/// A hung query before the tap stays visible to XCTest, as `record(_:)` requires, and back sends
114+
/// nothing: neither the button tap nor the swipe follows a hung query.
115+
@MainActor
116+
func testInAppBackWithAHungQueryInTheButtonLookupSendsNothing() throws {
117+
_ = try launchBackNavigationFixture(["--agent-device-back-navigation-bar"])
118+
defer { endBackFixture() }
119+
defer { navigationBarBackReadIssueForTesting = nil }
120+
121+
let outcome = try expectingHungQueryRecorded {
122+
navigationBarBackReadIssueForTesting = (.lookup, Self.hungQueryIssue)
123+
return try performInAppBack(app: app)
124+
}
125+
126+
guard case .refused(let payload) = outcome else { return XCTFail("a hung lookup must send nothing") }
127+
XCTAssertEqual(payload.code, RunnerWireErrorCode.backSwipeNotDispatched)
128+
XCTAssertEqual(lastNavigationBarBackTraceForTesting?.found, "hung")
129+
XCTAssertEqual(lastNavigationBarBackTraceForTesting?.pressed, false)
130+
navigationBarBackReadIssueForTesting = nil
131+
XCTAssertTrue(app.navigationBars["Detail"].exists, "nothing popped the detail screen")
132+
}
133+
134+
/// A hung query after a delivered tap stays visible to XCTest, and back answers unverified at once
135+
/// instead of querying the hung tree again.
136+
@MainActor
137+
func testInAppBackWithAHungQueryInTheConfirmationAnswersUnverified() throws {
138+
_ = try launchBackNavigationFixture(["--agent-device-back-navigation-bar"])
139+
defer { endBackFixture() }
140+
defer { navigationBarBackReadIssueForTesting = nil }
141+
142+
let outcome = try expectingHungQueryRecorded {
143+
navigationBarBackReadIssueForTesting = (.confirmation, Self.hungQueryIssue)
144+
return try performInAppBack(app: app)
145+
}
146+
147+
guard case .unconfirmed(let payload) = outcome else { return XCTFail("a hung confirmation must not read as performed") }
148+
XCTAssertEqual(payload.code, RunnerWireErrorCode.backSwipeUnverified)
149+
XCTAssertEqual(lastNavigationBarBackTraceForTesting?.pressed, true)
150+
XCTAssertEqual(lastNavigationBarBackTraceForTesting?.confirmed, "hung")
151+
}
152+
153+
/// Two hittable system back buttons, one per stack, are ambiguous: back presses neither and
154+
/// answers from the swipe path.
155+
@MainActor
156+
func testInAppBackPressesNoneOfTwoNavigationBarBackButtons() throws {
157+
_ = try launchBackNavigationFixture(["--agent-device-back-navigation-bar", "--two-stacks"])
158+
defer { endBackFixture() }
159+
XCTAssertEqual(app.navigationBars.buttons.matching(identifier: Self.navigationBarBackButtonIdentifier).count, 2)
160+
161+
_ = try performInAppBack(app: app)
162+
163+
let trace = try XCTUnwrap(lastNavigationBarBackTraceForTesting)
164+
XCTAssertEqual(trace.found, "ambiguous")
165+
XCTAssertFalse(trace.pressed, "back answered from the swipe path")
166+
}
167+
168+
/// A penalized XCTest snapshot channel is not read: back skips the button lookup and swipes.
169+
@MainActor
170+
func testInAppBackSkipsTheButtonLookupOnAPenalizedChannel() throws {
171+
_ = try launchBackNavigationFixture(["--agent-device-back-navigation-bar"])
172+
defer { endBackFixture() }
173+
penalizeSnapshotXCTestChannel(bundleId: mainOwned.bundleId, reason: "navigation-test")
174+
defer { clearSnapshotXCTestChannelPenalty(reason: "navigation-test") }
175+
176+
_ = try performInAppBack(app: app)
177+
178+
let trace = try XCTUnwrap(lastNavigationBarBackTraceForTesting)
179+
XCTAssertEqual(trace.found, "skipped")
180+
XCTAssertFalse(trace.pressed, "back answered from the swipe path")
181+
XCTAssertEqual(trace.lookupMs, 0)
182+
}
183+
112184
/// An XCTest issue in every read after a delivered tap proves nothing: back answers unverified and
113185
/// never swipes after the tap. An escaped issue would fail this test.
114186
@MainActor
115187
func testInAppBackWithAnIssueInTheConfirmationAnswersUnverified() throws {
116188
let status = try launchBackNavigationFixture(["--agent-device-back-navigation-bar"])
117189
defer { endBackFixture() }
118-
navigationBarBackReadIssueForTesting = .confirmation
190+
navigationBarBackReadIssueForTesting = (.confirmation, Self.vanishedBackButtonIssue)
119191
defer { navigationBarBackReadIssueForTesting = nil }
120192

121193
let response = try execute(command: try runnerCommandFixture(
@@ -351,6 +423,27 @@ extension RunnerTests {
351423
XCTAssertTrue(status.waitForFixtureExistence(timeout: appExistenceTimeout))
352424
return status
353425
}
426+
static let vanishedBackButtonIssue = "Back button vanished during the navigation bar read"
427+
static let hungQueryIssue = "Timed out while evaluating UI query."
428+
429+
/// Runs `body` and requires the hung query it records to reach XCTest exactly once.
430+
@MainActor
431+
private func expectingHungQueryRecorded<T>(_ body: () throws -> T) throws -> T {
432+
let options = XCTExpectedFailure.Options()
433+
var observed = 0
434+
options.issueMatcher = { issue in
435+
guard issue.compactDescription == Self.hungQueryIssue else { return false }
436+
observed += 1
437+
return true
438+
}
439+
var result: Result<T, Error>?
440+
XCTExpectFailure("The hung query is the condition under test", options: options) {
441+
result = Result { try body() }
442+
}
443+
XCTAssertEqual(observed, 1, "a hung query reaches XCTest once, and no query follows it")
444+
return try XCTUnwrap(result).get()
445+
}
446+
354447
@MainActor
355448
private func launchBackNavigationFixture(_ arguments: [String]) throws -> XCUIElement {
356449
app.launchArguments = arguments

‎apple/runner/RUNNER_PROTOCOL.md‎

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -137,19 +137,28 @@ than silently applied:
137137
`backInApp` is the only back command. On iOS the runner first reads the current tree, in the same
138138
call, for the navigation bar's system back button: a button with the identifier `BackButton` inside a
139139
navigation bar. It taps that button with a synthesized tap only when exactly one live, hittable
140-
candidate is found in a readable tree. No other button counts, whatever its label. After the tap it
141-
reads every navigation bar's identifier and the label and frame of its `BackButton` children, one
142-
XCTest snapshot per bar, with a 0.05 s pause between reads for up to 1 s. A change from the read
143-
taken before the tap answers `ok`. No change, or reads that fail, answer `BACK_SWIPE_UNVERIFIED`;
144-
a delivered tap is never followed by the swipe.
140+
candidate is found in a readable tree, and two reads in a row of the bar state agree and contain
141+
that button's frame; each round re-reads the buttons. No other button counts, whatever its label.
142+
The bar state is every navigation bar's identifier, the labels of its static texts, and the label
143+
and frame of its `BackButton` children, in bar order, one XCTest snapshot per bar. After the tap it
144+
reads that state again with a 0.05 s pause between reads. A change from the state read before the
145+
tap answers `ok`. No change, or reads that fail, answer `BACK_SWIPE_UNVERIFIED`; a delivered tap is
146+
never followed by the swipe. Before and after the tap, reads start for up to 1 s each, checked
147+
before each bar's snapshot; a query in flight finishes or ends at XCTest's own query timeout.
148+
149+
Every bar read holds its XCTest issues. A held issue means the read proved nothing. A hung query
150+
("Timed out while evaluating UI query") is recorded again, and no further query follows it: before
151+
the tap the runner answers `BACK_SWIPE_NOT_DISPATCHED` with nothing sent, and after it
152+
`BACK_SWIPE_UNVERIFIED`.
145153

146154
The runner swipes instead when no tap was sent:
147155

148156
- The tree read is skipped: the window resolution marked the tree unreadable, accessibility is
149157
unavailable, or the XCTest snapshot channel is penalized for the app.
150158
- The read fails or XCTest rejects one of its queries.
151159
- No candidate is found, or two or more are (such as a sheet over a stack).
152-
- The synthesized tap and its XCTest fallback are both refused before anything is sent.
160+
- The bar state does not hold still within 1 s.
161+
- The synthesized tap is refused before anything is sent.
153162

154163
A tap whose outcome is unknown after it may have been sent throws, and neither the bar check nor
155164
the swipe follows. The swipe verifies a change of the app's screen. When XCTest cannot resolve the
@@ -159,9 +168,9 @@ fills its screen; otherwise it refuses with `APP_SCREEN_UNRESOLVED`. Its failure
159168
| Code | When | Sent |
160169
| --- | --- | --- |
161170
| `APP_SCREEN_WINDOW_UNRESOLVED`, `APP_SCREEN_UNRESOLVED`, `APP_SCREEN_CAPTURE_UNRENDERABLE`, `APP_SCREEN_OFF_LIT_PANEL` | The screen could not be sampled before the swipe. | Nothing |
162-
| `BACK_SWIPE_NOT_DISPATCHED` | The swipe was refused before any touch went down, or the platform has no back gesture (visionOS; the daemon refuses it first). | Nothing |
171+
| `BACK_SWIPE_NOT_DISPATCHED` | The swipe was refused before any touch went down, an XCTest query on the navigation bar hung before the tap, or the platform has no back command (visionOS; the daemon refuses it first). | Nothing |
163172
| `BACK_SWIPE_NO_CHANGE` | The swipe was sent and the sampled grid (48×96 grayscale cells, with the top 7 rows always left out; in portrait they hold the status bar and Dynamic Island, and in landscape the iPhone status bar is hidden and the Dynamic Island sits at a side edge, outside those rows) changed in at most 1% of the remaining cells by more than 24 of 256 levels. | The swipe |
164-
| `BACK_SWIPE_UNVERIFIED` | The swipe may have run, or the back button was tapped and the bar did not change within 1 s; the outcome is unknown. | Possibly the swipe, or the tap |
173+
| `BACK_SWIPE_UNVERIFIED` | The swipe may have run, or the back button was tapped and the bar did not change within 1 s or a query on it hung; the outcome is unknown. | Possibly the swipe, or the tap |
165174

166175
The swipe is first resolved up to its contact. Then the settle window is a run of samples, with a
167176
0.05 s pause between captures plus each capture's own time, that agree for as long as the gap the swipe will be credited across: a contact
@@ -190,7 +199,8 @@ window can still be misread as a back navigation; any finite window has that lim
190199

191200
Each iOS back whose window context resolved logs one `AGENT_DEVICE_RUNNER_BACK_NAVIGATION_BAR_BUTTON`
192201
line on every exit of the button path, a thrown tap included, with `found` (`skipped`,
193-
`unreadable`, `no`, `ambiguous`, or `yes`), `pressed`, `confirmed`, `lookupMs` (`0` when the read was
202+
`unreadable`, `hung`, `moving`, `no`, `ambiguous`, or `yes`), `pressed`, `confirmed` (`yes`, `no`,
203+
`hung`, or `-` before a tap), `lookupMs` (`0` when the read was
194204
skipped), and `confirmMs`. Each swipe logs one runner line, `AGENT_DEVICE_RUNNER_BACK_SWIPE_VERIFICATION`, on every exit, with its
195205
`outcome` (`performed`, `refused`, `unconfirmed`, or `error` for a thrown failure), `code`, `changed`, `stableMs`, `justBeforeToAfterMs`, `gestureMs`, `maxCaptureMs`,
196206
`settleSamples`, and `settled`.

‎packages/platform-apple/src/navigation/runtime.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ const backOsUnavailable = Object.freeze({
3333
const backVisionOsUnavailable = Object.freeze({
3434
available: false,
3535
reason: 'unsupported-platform-leaf',
36-
hint: 'iOS back is a left-edge swipe; visionOS has none. Press the visible back control by its ref.',
36+
hint: 'visionOS has no back command. Press the visible back control by its ref.',
3737
} as const);
3838
/** tvOS presses the remote's Menu button, macOS taps the window back control, and iOS presses the
3939
* navigation bar back button or swipes from the left edge. watchOS and visionOS have no back. */

‎packages/platform-apple/src/runtime.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -528,7 +528,7 @@ function expectNavigationAndKeyboardFacts(
528528
if (device.appleOs === 'visionos') {
529529
expect(binding.facts.operations.back).toMatchObject({
530530
reason: 'unsupported-platform-leaf',
531-
hint: expect.stringContaining('visionOS has none'),
531+
hint: expect.stringContaining('visionOS has no back command'),
532532
});
533533
}
534534

0 commit comments

Comments
 (0)