Skip to content

Commit 351fe82

Browse files
committed
refactor(ios): route snapshot backends through presentation
## Summary Route every iOS capture-plan backend through one SnapshotPresentation boundary while preserving each backend's current output semantics. SnapshotAcquisition now carries nodes and attempt-level facts, PresentationOptions is the stable policy input, and only the presentation module assembles wire-facing nodes. Part of #1797. Touches 10 files within the existing iOS snapshot module and its architecture vocabulary; scope did not expand beyond the planned command family. ## Validation - Unit-enabled iOS runner build and focused presentation XCTest passed. - Removing the custom-action handoff made the focused test fail with exactly two assertions, proving the routing check is non-vacuous; restoring it returned to 1/1 green. - macOS runner build passed for the shared Swift path. - XCTest selection and repository formatting checks passed.
1 parent f03c030 commit 351fe82

10 files changed

Lines changed: 138 additions & 84 deletions

‎CONTEXT.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -218,6 +218,12 @@ task touches:
218218
- Raw AX node: backend-owned iOS acquisition value before the snapshot presentation boundary. During
219219
the #1797 migration it temporarily carries existing derived fields so the seam can land without a
220220
wire-behavior change.
221+
- Snapshot acquisition: the result of one iOS snapshot backend attempt—raw AX nodes plus
222+
attempt-level truncation, depth, and custom-action facts. Every capture-plan backend returns this
223+
type, and the exhaustive backend switch routes it through `SnapshotPresentation` exactly once.
224+
- Presentation options: the source-of-truth iOS snapshot request policy accepted by
225+
`SnapshotPresentation`. During the behavior-preserving #1797 migration acquisition still reads
226+
these options to reproduce current backend-specific decisions.
221227
- Presented node: wire-facing iOS snapshot value constructed only by `SnapshotPresentation`; response
222228
payload assembly accepts this type rather than backend-owned raw values.
223229
- Snapshot capture plan: per-strategy ordered chain of iOS snapshot capture backends (recursive tree,

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

Lines changed: 18 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -103,11 +103,11 @@ extension RunnerTests {
103103
}
104104
}
105105

106-
func privateAXSnapshotCapture(
106+
func privateAXSnapshotAcquisition(
107107
app: XCUIApplication,
108-
options: SnapshotOptions,
108+
options: PresentationOptions,
109109
deadline: Date = .distantFuture
110-
) -> SnapshotBackendCapture? {
110+
) -> SnapshotAcquisition? {
111111
#if os(iOS) && targetEnvironment(simulator)
112112
let requestedDepth = options.depth ?? 64
113113
// An explicit --depth request is honored as asked: no accepted-depth
@@ -202,11 +202,9 @@ extension RunnerTests {
202202
effectiveDepth,
203203
deepExtension?[RunnerAXSnapshotDeepExtensionNodesAddedKey] as? Int ?? 0
204204
)
205-
return SnapshotBackendCapture(
206-
payload: DataPayload(
207-
presenting: nodes,
208-
truncated: (response["truncated"] as? Bool) == true
209-
),
205+
return SnapshotAcquisition(
206+
nodes: nodes,
207+
truncated: (response["truncated"] as? Bool) == true,
210208
effectiveDepth: depthLimited ? effectiveDepth : nil,
211209
customActions: Self.privateAXCustomActionCoverage(
212210
response[RunnerAXSnapshotCustomActionsKey]
@@ -417,7 +415,7 @@ extension RunnerTests {
417415
func testCustomActionsRequestPinsPrivateAXBackend() throws {
418416
let asked = try JSONDecoder().decode(
419417
Command.self, from: Data(#"{"command":"snapshot","customActions":true}"#.utf8))
420-
let options = Self.snapshotOptions(from: asked)
418+
let options = Self.presentationOptions(from: asked)
421419
XCTAssertTrue(options.customActions)
422420
XCTAssertEqual(options.preferredBackend, SnapshotBackendKind.privateAX.rawValue)
423421
XCTAssertTrue(
@@ -428,12 +426,12 @@ extension RunnerTests {
428426
let pinned = try JSONDecoder().decode(
429427
Command.self,
430428
from: Data(#"{"command":"snapshot","customActions":true,"preferredBackend":"tree"}"#.utf8))
431-
XCTAssertEqual(Self.snapshotOptions(from: pinned).preferredBackend, "tree")
429+
XCTAssertEqual(Self.presentationOptions(from: pinned).preferredBackend, "tree")
432430

433431
// And the default capture neither asks nor pins.
434432
let bare = try JSONDecoder().decode(Command.self, from: Data(#"{"command":"snapshot"}"#.utf8))
435-
XCTAssertFalse(Self.snapshotOptions(from: bare).customActions)
436-
XCTAssertNil(Self.snapshotOptions(from: bare).preferredBackend)
433+
XCTAssertFalse(Self.presentationOptions(from: bare).customActions)
434+
XCTAssertNil(Self.presentationOptions(from: bare).preferredBackend)
437435
}
438436

439437
/// A request-pinned backend degraded nothing, so its verdict must not claim
@@ -639,7 +637,7 @@ extension RunnerTests {
639637
]
640638
let nodes = privateAXPresentation(
641639
rawRoot: tree,
642-
options: SnapshotOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false),
640+
options: PresentationOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false),
643641
viewport: CGRect(x: 0, y: 0, width: 390, height: 844)
644642
)
645643

@@ -664,7 +662,12 @@ extension RunnerTests {
664662
]
665663
let nodes = privateAXPresentation(
666664
rawRoot: tree,
667-
options: SnapshotOptions(interactiveOnly: false, depth: nil, scope: "homeScreen", raw: false),
665+
options: PresentationOptions(
666+
interactiveOnly: false,
667+
depth: nil,
668+
scope: "homeScreen",
669+
raw: false
670+
),
668671
viewport: .infinite
669672
)
670673

@@ -741,7 +744,7 @@ extension RunnerTests {
741744
]
742745
let nodes = privateAXPresentation(
743746
rawRoot: tree,
744-
options: SnapshotOptions(interactiveOnly: true, depth: nil, scope: nil, raw: false),
747+
options: PresentationOptions(interactiveOnly: true, depth: nil, scope: nil, raw: false),
745748
viewport: CGRect(x: 0, y: 0, width: 390, height: 844)
746749
)
747750

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1360,10 +1360,10 @@ extension RunnerTests {
13601360
}
13611361

13621362
/// Pure command→options projection, extracted so the runner unit bundle can
1363-
/// prove the decoded wire field actually reaches capture options (#1634 P2).
1364-
static func snapshotOptions(from command: Command) -> SnapshotOptions {
1363+
/// prove the decoded wire field actually reaches presentation options (#1634 P2).
1364+
static func presentationOptions(from command: Command) -> PresentationOptions {
13651365
let customActions = command.customActions ?? false
1366-
return SnapshotOptions(
1366+
return PresentationOptions(
13671367
interactiveOnly: command.interactiveOnly ?? false,
13681368
depth: command.depth,
13691369
scope: command.scope,
@@ -1378,7 +1378,7 @@ extension RunnerTests {
13781378
}
13791379

13801380
private func executeSnapshotPrepared(command: Command, activeApp: XCUIApplication) throws -> Response {
1381-
let options = Self.snapshotOptions(from: command)
1381+
let options = Self.presentationOptions(from: command)
13821382
do {
13831383
let payload: DataPayload
13841384
if options.raw {

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

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ extension RunnerTests {
119119

120120
func flatSnapshotFilterDecision(
121121
_ node: FlatSnapshotFilterNode,
122-
options: SnapshotOptions,
122+
options: PresentationOptions,
123123
visibilityPolicy: FlatSnapshotVisibilityPolicy,
124124
insideMatchedScope: Bool
125125
) -> FlatSnapshotFilterDecision {
@@ -339,47 +339,47 @@ extension RunnerTests {
339339
XCTAssertTrue(
340340
flatSnapshotFilterDecision(
341341
visibleContent,
342-
options: SnapshotOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false),
342+
options: PresentationOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false),
343343
visibilityPolicy: .interactiveOnly,
344344
insideMatchedScope: false
345345
).include
346346
)
347347
XCTAssertFalse(
348348
flatSnapshotFilterDecision(
349349
hiddenInteractive,
350-
options: SnapshotOptions(interactiveOnly: true, depth: nil, scope: nil, raw: false),
350+
options: PresentationOptions(interactiveOnly: true, depth: nil, scope: nil, raw: false),
351351
visibilityPolicy: .interactiveOnly,
352352
insideMatchedScope: false
353353
).include
354354
)
355355
XCTAssertFalse(
356356
flatSnapshotFilterDecision(
357357
hiddenInteractive,
358-
options: SnapshotOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false),
358+
options: PresentationOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false),
359359
visibilityPolicy: .viewportProjected,
360360
insideMatchedScope: false
361361
).include
362362
)
363363
XCTAssertTrue(
364364
flatSnapshotFilterDecision(
365365
hiddenInteractive,
366-
options: SnapshotOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false),
366+
options: PresentationOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false),
367367
visibilityPolicy: .interactiveOnly,
368368
insideMatchedScope: false
369369
).include
370370
)
371371
XCTAssertTrue(
372372
flatSnapshotFilterDecision(
373373
hiddenRoot,
374-
options: SnapshotOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false),
374+
options: PresentationOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false),
375375
visibilityPolicy: .viewportProjected,
376376
insideMatchedScope: false
377377
).include
378378
)
379379
XCTAssertTrue(
380380
flatSnapshotFilterDecision(
381381
decorative,
382-
options: SnapshotOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false),
382+
options: PresentationOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false),
383383
visibilityPolicy: .interactiveOnly,
384384
insideMatchedScope: false
385385
).include
@@ -401,7 +401,7 @@ extension RunnerTests {
401401
valueText: nil,
402402
visible: true
403403
)
404-
let options = SnapshotOptions(interactiveOnly: false, depth: nil, scope: "homeScreen", raw: false)
404+
let options = PresentationOptions(interactiveOnly: false, depth: nil, scope: "homeScreen", raw: false)
405405

406406
let rootDecision = flatSnapshotFilterDecision(
407407
scopeRoot,

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -375,7 +375,7 @@ struct SnapshotRect: Codable {
375375
let height: Double
376376
}
377377

378-
struct SnapshotOptions {
378+
struct PresentationOptions {
379379
let interactiveOnly: Bool
380380
let depth: Int?
381381
let scope: String?

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

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import XCTest
33
extension RunnerTests {
44
private static let privateAXProjectionTolerance: CGFloat = 1
55

6-
func privateAXPresentation(rawRoot: [String: Any], options: SnapshotOptions, viewport: CGRect)
6+
func privateAXPresentation(rawRoot: [String: Any], options: PresentationOptions, viewport: CGRect)
77
-> [RawAXNode]
88
{
99
var nodes: [RawAXNode] = []
@@ -15,7 +15,7 @@ extension RunnerTests {
1515
}
1616

1717
private func appendPrivateAXNode(_ raw: [String: Any], to nodes: inout [RawAXNode],
18-
hints: inout [Int: (above: Bool, below: Bool)], options: SnapshotOptions, viewport: CGRect,
18+
hints: inout [Int: (above: Bool, below: Bool)], options: PresentationOptions, viewport: CGRect,
1919
depth: Int, parentIndex: Int?, insideMatchedScope: Bool,
2020
scrollContext: (index: Int, rect: CGRect)?, projectionCursor: FlatSnapshotProjectionCursor)
2121
{
@@ -119,7 +119,7 @@ extension RunnerTests {
119119
"children": [["type": Int(XCUIElement.ElementType.button.rawValue), "label": "Profile picture", "frame": frame(16, 120, 44, 44)],
120120
["type": Int(XCUIElement.ElementType.button.rawValue), "label": "Theme", "frame": frame(16, 900, 360, 44)]]]]]
121121
let nodes = privateAXPresentation(rawRoot: root,
122-
options: SnapshotOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false),
122+
options: PresentationOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false),
123123
viewport: CGRect(x: 0, y: 0, width: 402, height: 874))
124124
XCTAssertEqual(nodes.compactMap(\.label), ["Element", "Profile picture"])
125125
let scrollView = nodes.first { $0.type == "ScrollView" }
@@ -142,7 +142,7 @@ extension RunnerTests {
142142
"label": "Theme", "frame": frame(340, 96, 46, 44)]]]]]]]
143143

144144
let nodes = privateAXPresentation(rawRoot: root,
145-
options: SnapshotOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false),
145+
options: PresentationOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false),
146146
viewport: CGRect(x: 0, y: 0, width: 402, height: 874))
147147

148148
XCTAssertEqual(nodes.compactMap(\.label), ["Element"])
@@ -158,7 +158,7 @@ extension RunnerTests {
158158
"type": Int(XCUIElement.ElementType.button.rawValue), "label": "Theme", "frame": zero],
159159
["type": Int(XCUIElement.ElementType.other.rawValue), "frame": zero]]]]]
160160
let nodes = privateAXPresentation(rawRoot: root,
161-
options: SnapshotOptions(interactiveOnly: true, depth: nil, scope: nil, raw: false),
161+
options: PresentationOptions(interactiveOnly: true, depth: nil, scope: nil, raw: false),
162162
viewport: CGRect(x: 0, y: 0, width: 402, height: 874))
163163
XCTAssertEqual(nodes.compactMap(\.label), ["Element", "Settings semantics", "Theme"])
164164
XCTAssertEqual(nodes.filter { $0.index != 0 }.map(\.hittable), [false, false])

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

Lines changed: 24 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,7 @@ extension RunnerTests {
117117
// `boundedBlockingSystemAlertSnapshot`'s probe closure (see `systemModalProbeOverrideForTesting`
118118
// in RunnerTests.swift), so reverting this entry point to bypass the bounded probe fails the
119119
// regression test.
120-
func snapshotFast(app: XCUIApplication, options: SnapshotOptions) throws -> DataPayload {
120+
func snapshotFast(app: XCUIApplication, options: PresentationOptions) throws -> DataPayload {
121121
let deadline = Date().addingTimeInterval(Self.snapshotPlanBudget)
122122
if let blocking = boundedBlockingSystemAlertSnapshot(deadline: deadline) {
123123
return blocking
@@ -131,10 +131,10 @@ extension RunnerTests {
131131
)
132132
}
133133

134-
func recursiveTreeSnapshotPayload(
134+
func recursiveTreeSnapshotAcquisition(
135135
context: SnapshotTraversalContext,
136-
options: SnapshotOptions
137-
) -> DataPayload {
136+
options: PresentationOptions
137+
) -> SnapshotAcquisition {
138138
var cachedDescendantElements: [XCUIElement]?
139139
func collapsedTabDescendants() -> [XCUIElement] {
140140
if let cachedDescendantElements {
@@ -315,14 +315,15 @@ extension RunnerTests {
315315

316316
}
317317

318-
return DataPayload(
319-
presenting: applyHiddenContentHints(hiddenContentHintsByNodeIndex, to: nodes),
320-
truncated: false
318+
return SnapshotAcquisition(
319+
nodes: applyHiddenContentHints(hiddenContentHintsByNodeIndex, to: nodes),
320+
truncated: false,
321+
effectiveDepth: nil
321322
)
322323
}
323324

324325
// See `snapshotFast` above: the single production entry point, no unit-test overload.
325-
func snapshotRaw(app: XCUIApplication, options: SnapshotOptions) throws -> DataPayload {
326+
func snapshotRaw(app: XCUIApplication, options: PresentationOptions) throws -> DataPayload {
326327
let deadline = Date().addingTimeInterval(Self.snapshotPlanBudget)
327328
if let blocking = boundedBlockingSystemAlertSnapshot(deadline: deadline) {
328329
return blocking
@@ -418,10 +419,10 @@ extension RunnerTests {
418419
return min(budget, deadlineRemaining)
419420
}
420421

421-
func rawTreeSnapshotPayload(
422+
func rawTreeSnapshotAcquisition(
422423
context: SnapshotTraversalContext,
423-
options: SnapshotOptions
424-
) throws -> DataPayload {
424+
options: PresentationOptions
425+
) throws -> SnapshotAcquisition {
425426
var nodes: [RawAXNode] = []
426427

427428
func walk(_ snapshot: XCUIElementSnapshot, depth: Int, parentIndex: Int?) throws {
@@ -460,19 +461,19 @@ extension RunnerTests {
460461
}
461462

462463
try walk(context.rootSnapshot, depth: 0, parentIndex: nil)
463-
return DataPayload(presenting: nodes, truncated: false)
464+
return SnapshotAcquisition(nodes: nodes, truncated: false, effectiveDepth: nil)
464465
}
465466

466-
func snapshotFlatInteractive(
467+
func querySweepSnapshotAcquisition(
467468
app: XCUIApplication,
468-
options: SnapshotOptions,
469+
options: PresentationOptions,
469470
planDeadline: Date = .distantFuture
470-
) -> DataPayload {
471+
) -> SnapshotAcquisition {
471472
var nodes: [RawAXNode] = [
472473
interactiveRootNode(rect: .zero)
473474
]
474475
if options.depth == 0 {
475-
return DataPayload(presenting: nodes, truncated: false)
476+
return SnapshotAcquisition(nodes: nodes, truncated: false, effectiveDepth: nil)
476477
}
477478

478479
// Bounded by both its own sweep budget and the umbrella capture-plan deadline, so a
@@ -543,7 +544,7 @@ extension RunnerTests {
543544
)
544545
)
545546
}
546-
return DataPayload(presenting: nodes, truncated: truncated)
547+
return SnapshotAcquisition(nodes: nodes, truncated: truncated, effectiveDepth: nil)
547548
}
548549

549550
func snapshotAccessibilityUnavailable(failure: SnapshotCaptureFailure) -> DataPayload {
@@ -588,7 +589,7 @@ extension RunnerTests {
588589
) -> DataPayload {
589590
return DataPayload(
590591
message: message,
591-
nodes: SnapshotPresentation.preservingCurrentSemantics([interactiveRootNode(rect: .zero)]),
592+
nodes: [SnapshotPresentation.singleElementRead(interactiveRootNode(rect: .zero))],
592593
truncated: true,
593594
snapshotQuality: snapshotQuality,
594595
runnerFatal: runnerFatal,
@@ -669,7 +670,7 @@ extension RunnerTests {
669670
/// assertion instead of racing a fixed-timing guess.
670671
private func assertBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain(
671672
entryPointName: String,
672-
callEntryPoint: @escaping (XCUIApplication, SnapshotOptions) throws -> DataPayload
673+
callEntryPoint: @escaping (XCUIApplication, PresentationOptions) throws -> DataPayload
673674
) {
674675
let targetBundleId = "com.callstack.agentdevice.runner.missing.snapshot-timeout-test"
675676
let snapshotTarget = XCUIApplication(bundleIdentifier: targetBundleId)
@@ -707,7 +708,7 @@ extension RunnerTests {
707708
DispatchQueue(label: "agent-device.runner.tests.modal-probe-timeout").async {
708709
box.payload = try? callEntryPoint(
709710
snapshotTarget,
710-
SnapshotOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false)
711+
PresentationOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false)
711712
)
712713

713714
// 1) Penalty/busy accounting: must already be in place by the time the entry point
@@ -874,7 +875,7 @@ extension RunnerTests {
874875
label: String,
875876
identifier: String,
876877
valueText: String?,
877-
options: SnapshotOptions,
878+
options: PresentationOptions,
878879
hittable: Bool,
879880
visible: Bool,
880881
regularSnapshot: Bool = false
@@ -926,7 +927,7 @@ extension RunnerTests {
926927

927928
func makeSnapshotTraversalContext(
928929
app: XCUIApplication,
929-
options: SnapshotOptions,
930+
options: PresentationOptions,
930931
captureDeadline: Date = .distantFuture,
931932
treeCaptureSliceBudgetOverride: TimeInterval? = nil
932933
) throws -> SnapshotTraversalContext? {
@@ -1567,7 +1568,7 @@ extension RunnerTests {
15671568
index: Int,
15681569
parentIndex: Int?,
15691570
viewport: CGRect,
1570-
options: SnapshotOptions
1571+
options: PresentationOptions
15711572
) -> RawAXNode? {
15721573
var node: RawAXNode?
15731574
let exceptionMessage = RunnerObjCExceptionCatcher.catchException({

0 commit comments

Comments
 (0)