Skip to content

Commit bb3dfdc

Browse files
committed
fix(ios): serve regular --depth from every snapshot backend
A regular depth-capped request was refused on every runner backend but the recursive tree: the query sweep past depth 1 and private AX at any depth returned no capture, so a plan pinned or deferred to private AX (custom actions, a private AX verdict on the session, the XCTest channel penalty) fell through to the synthetic sparse root, which the daemon then rejected as "regular iOS snapshot presentation requires a valid viewport". Presentation already applies the presented-depth cut to whatever hierarchy a backend acquired, and a depth-capped regular capture is a subset of the unscoped one from the same backend, so the refusal protected nothing the unscoped answer did not already disclose through truncated/effectiveDepth. Delete the gate, declare private AX as regular-depth=presentation-cut, and record the rule in ADR 0004. Closes #2403
1 parent 52420d7 commit bb3dfdc

8 files changed

Lines changed: 101 additions & 52 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,15 @@
22

33
## Unreleased
44

5+
- Fixed: iOS `--depth` on `snapshot`, `is`, `wait`, `get`, and `find` no longer fails with
6+
`regular iOS snapshot presentation requires a valid viewport` when the runner plan is pinned or
7+
deferred to the private AX backend (custom actions, a private AX verdict on the session, or the
8+
XCTest channel penalty). The runner refused a regular depth-capped request on every backend but
9+
the recursive tree, fell through to its synthetic sparse root, and the daemon rejected that root
10+
as a missing viewport. Presentation applies the presented-depth cut to whatever hierarchy a
11+
backend acquired, so every backend serves the request; the private AX declaration is now
12+
`regular-depth=presentation-cut` and an acquisition that stopped short of the cut keeps
13+
disclosing that through `truncated`/`effectiveDepth` as it does unscoped.
514
- Added: `replay export` supports flows that switch apps and return, preserving each
615
`open <appId>` target as an explicit Maestro `launchApp.appId`.
716
- Added: `replay export` converts recorded `home` actions to Maestro `pressKey: Home`, allowing

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

Lines changed: 11 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,19 @@ enum SnapshotBackendEnvironment {
55
case physicalDevice
66
}
77

8+
/// How a backend's acquisition relates to a regular `--depth` request. Every backend serves the
9+
/// request: `SnapshotPresentation` applies the presented-depth cut to whatever hierarchy was
10+
/// acquired, and an acquisition that stopped short of the cut discloses that through its own
11+
/// truncation verdict. The capability only says how much acquisition work the request bounds.
812
enum SnapshotRegularDepthCapability: String {
9-
/// The backend can stop acquisition at the requested regular presented-depth frontier.
13+
/// Acquisition stops at the requested regular presented-depth frontier.
1014
case presentedFrontier = "presented-frontier"
11-
/// The backend is flat; it can answer the root and one presented level, but has no hierarchy
12-
/// from which to prove deeper regular depth.
15+
/// The backend is flat: it acquires the root and one presented level, so a cut past depth 1
16+
/// returns the sweep unchanged.
1317
case flat
14-
/// The backend can return raw traversal depth, but cannot prove regular presented depth.
15-
case rawOnly = "raw-only"
18+
/// Acquisition walks its raw-depth ladder regardless of the request; the presented cut happens
19+
/// in presentation and the ladder's cap is disclosed as `effectiveDepth`.
20+
case presentationCut = "presentation-cut"
1621
}
1722

1823
enum SnapshotBackendKind: String, CaseIterable {
@@ -62,19 +67,7 @@ enum SnapshotBackendKind: String, CaseIterable {
6267
case .querySweep:
6368
return .flat
6469
case .privateAX:
65-
return .rawOnly
66-
}
67-
}
68-
69-
func canServeRegularPresentedDepth(_ requestedDepth: Int?) -> Bool {
70-
guard let requestedDepth else { return true }
71-
switch regularDepthCapability {
72-
case .presentedFrontier:
73-
return true
74-
case .flat:
75-
return requestedDepth <= 1
76-
case .rawOnly:
77-
return false
70+
return .presentationCut
7871
}
7972
}
8073

@@ -171,14 +164,5 @@ extension RunnerTests {
171164
)
172165
}
173166
}
174-
175-
func testRegularDepthCapabilityDoesNotClaimFlatOrRawOnlyParity() {
176-
XCTAssertTrue(SnapshotBackendKind.recursiveTree.canServeRegularPresentedDepth(8))
177-
XCTAssertTrue(SnapshotBackendKind.querySweep.canServeRegularPresentedDepth(0))
178-
XCTAssertTrue(SnapshotBackendKind.querySweep.canServeRegularPresentedDepth(1))
179-
XCTAssertFalse(SnapshotBackendKind.querySweep.canServeRegularPresentedDepth(2))
180-
XCTAssertFalse(SnapshotBackendKind.privateAX.canServeRegularPresentedDepth(1))
181-
XCTAssertTrue(SnapshotBackendKind.privateAX.canServeRegularPresentedDepth(nil))
182-
}
183167
}
184168
#endif

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

Lines changed: 0 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -415,22 +415,6 @@ extension RunnerTests {
415415
) throws -> SnapshotBackendAttempt {
416416
let hint = SnapshotPresentation.captureHint(for: options)
417417
var timer = SnapshotPhaseTimer()
418-
// Scoped depth is relative to a presentation-selected root, so its hint stays broad and the
419-
// backend capability gate applies only to an unscoped regular frontier.
420-
let requestedRegularDepth = options.raw || SnapshotScopePolicy.isActive(options.scope)
421-
? nil
422-
: options.depth
423-
guard kind.canServeRegularPresentedDepth(requestedRegularDepth) else {
424-
NSLog(
425-
"AGENT_DEVICE_RUNNER_SNAPSHOT_BACKEND_DEPTH_UNSUPPORTED backend=%@ depth=%ld",
426-
kind.rawValue,
427-
requestedRegularDepth ?? -1
428-
)
429-
return SnapshotBackendAttempt(
430-
outcome: .noCapture,
431-
timing: timer.timing
432-
)
433-
}
434418
let acquisition: SnapshotAcquisition?
435419
do {
436420
acquisition = try timer.measure(.acquisition) {
Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
import AgentDeviceSnapshotPresentation
2+
import CoreGraphics
3+
import XCTest
4+
5+
/// A backend that acquires past the requested frontier (private AX walks its raw ladder) still
6+
/// serves a regular `--depth` request: the cut is presentation's, applied to whatever hierarchy
7+
/// was acquired (#2403).
8+
final class RegularDepthTests: XCTestCase {
9+
func testRegularDepthCutsAHierarchyAcquiredPastTheFrontier() throws {
10+
let options = PresentationOptions(interactiveOnly: false, depth: 1, scope: nil, raw: false)
11+
let viewport = CGRect(x: 0, y: 0, width: 100, height: 100)
12+
// Application > Other(wrapper) > Button "Continue" > StaticText "Deep"
13+
let nodes = [
14+
node(0, type: "Application", label: "App", depth: 0, parentIndex: nil),
15+
node(1, type: "Other", label: nil, depth: 1, parentIndex: 0),
16+
node(2, type: "Button", label: "Continue", depth: 2, parentIndex: 1, hittable: true),
17+
node(3, type: "StaticText", label: "Deep", depth: 3, parentIndex: 2),
18+
]
19+
let acquisition = SnapshotAcquisition(
20+
hint: SnapshotPresentation.captureHint(for: options),
21+
nodes: nodes,
22+
truncated: false,
23+
effectiveDepth: nil,
24+
viewport: viewport
25+
)
26+
27+
let result = try XCTUnwrap(SnapshotPresentation.present(acquisition, options: options))
28+
29+
XCTAssertEqual(result.nodes.map(\.label), ["App", "Continue"])
30+
XCTAssertEqual(result.nodes.map(\.depth), [0, 1])
31+
XCTAssertEqual(result.nodes.map(\.parentIndex), [nil, 0])
32+
}
33+
34+
private func node(
35+
_ index: Int,
36+
type: String,
37+
label: String?,
38+
depth: Int,
39+
parentIndex: Int?,
40+
hittable: Bool = false
41+
) -> RawAXNode {
42+
RawAXNode(
43+
index: index,
44+
type: type,
45+
label: label,
46+
identifier: nil,
47+
value: nil,
48+
rect: SnapshotRect(x: 10, y: 10, width: 40, height: 20),
49+
enabled: true,
50+
focused: nil,
51+
selected: nil,
52+
hittable: hittable,
53+
depth: depth,
54+
parentIndex: parentIndex,
55+
hiddenContentAbove: nil,
56+
hiddenContentBelow: nil
57+
)
58+
}
59+
}

‎contracts/fixtures/ios-snapshot-backends.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@
3939
"name": "private-ax",
4040
"forceable": true,
4141
"supportsRawProjection": true,
42-
"regularDepth": "raw-only",
42+
"regularDepth": "presentation-cut",
4343
"hittable": "geometric-actionability",
4444
"deepExtension": "yes",
4545
"depthLadder": "yes",

‎docs/adr/0004-ios-snapshot-backend-strategy.md‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -273,11 +273,18 @@ fold and eligibility collapse. This keeps shallow probes bounded by the requeste
273273
frontier without inventing a raw-depth multiplier. Scoped captures remain broad because depth is
274274
relative to the scope root selected in presentation.
275275

276-
Backend capability declarations are part of the contract: recursive tree supports the presented
277-
frontier, the flat query sweep supports only its root and one presented level, and private AX is
278-
raw-depth-only for regular depth requests until it has an equivalent hierarchy-aware frontier.
279-
The capture plan does not claim deeper regular-depth completeness from a backend that cannot prove
280-
it. Raw depth remains acquisition depth for every backend.
276+
Backend capability declarations are part of the contract, and they describe how much acquisition
277+
work a regular depth request bounds — never whether the backend may answer it. Every backend
278+
serves a regular `--depth` request because presentation applies the presented-depth cut to
279+
whatever hierarchy was acquired: the recursive tree stops acquisition at the presented frontier,
280+
the flat query sweep has only its root and one presented level (so a cut past depth 1 returns the
281+
sweep unchanged), and private AX walks its raw-depth ladder and is cut afterwards
282+
(`presentation-cut`). Completeness below an acquisition cap is disclosed the same way it is for an
283+
unscoped capture — through `truncated` and `effectiveDepth` — because a depth-capped regular
284+
capture is a subset of the unscoped one from the same backend. Refusing the request instead
285+
produced no answer at all: a plan pinned or deferred to private AX fell through to the synthetic
286+
sparse root, which the daemon then rejected as a missing viewport (#2403). Raw depth remains
287+
acquisition depth for every backend.
281288

282289
Acquisition-side limits remain explicit: raw private-AX captures still disclose their bridge-side
283290
node cap, the flat query sweep still drops frameless elements because it has no hierarchy to attach

‎packages/capture-kit/src/snapshot-quality-backend-capabilities.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ test('iOS snapshot registry classifies every backend and conformance target', ()
100100
expect(SNAPSHOT_BACKEND_CAPABILITIES['private-ax']).toMatchObject({
101101
forceable: true,
102102
supportsRawProjection: true,
103-
regularDepth: 'raw-only',
103+
regularDepth: 'presentation-cut',
104104
hittable: 'geometric-actionability',
105105
deepExtension: 'yes',
106106
depthLadder: 'yes',

‎packages/capture-kit/src/snapshot-quality-backend-capabilities.ts‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,13 @@ import type {
66
/** #1933: every classified backend publishes this shared predicate in the wire `hittable` field. */
77
type SnapshotBackendHittable = 'geometric-actionability';
88
type SnapshotBackendSupport = 'yes' | 'no' | 'n/a';
9-
type SnapshotRegularDepthCapability = 'presented-frontier' | 'flat' | 'raw-only';
9+
/**
10+
* How a backend's acquisition relates to a regular `--depth` request. Presentation applies the
11+
* presented-depth cut to whatever hierarchy was acquired, so every backend serves the request;
12+
* the value says whether acquisition stops at the frontier, is flat, or walks its raw ladder and
13+
* is cut afterwards.
14+
*/
15+
type SnapshotRegularDepthCapability = 'presented-frontier' | 'flat' | 'presentation-cut';
1016

1117
type SnapshotBackendCapability = {
1218
supportsRawProjection: boolean;
@@ -57,7 +63,7 @@ export const SNAPSHOT_BACKEND_CAPABILITIES = {
5763
'private-ax': {
5864
forceable: true,
5965
supportsRawProjection: true,
60-
regularDepth: 'raw-only',
66+
regularDepth: 'presentation-cut',
6167
hittable: 'geometric-actionability',
6268
deepExtension: 'yes',
6369
depthLadder: 'yes',

0 commit comments

Comments
 (0)