Skip to content

Commit 427b604

Browse files
committed
fix(ios): fail closed on interactive AX failure, stamp fatal verdict, validate parser
Three review findings on the capture-plan terminal path: - P1: the fail-closed guard required `best == nil`, but the query-sweep tier always returns a synthetic-root sparse payload that sets `best` — so an interactive recursive-tree AX serialization failure that no backend recovered returned a sparse snapshot instead of invalidating the cached target. Reaching the terminal already means no backend produced a usable tree, so the sparse `best` must not suppress the fail-closed path. Extracted the decision into a pure, unit-tested `resolveSnapshotPlanTerminal` (closes the terminal-ordering testability gap the architecture review flagged). - P2: `snapshotAccessibilityUnavailable` returned a payload with no `snapshotQuality`, leaving one planned sparse result on the legacy-message path. It now carries a sparse/ax-rejected verdict like every other planned snapshot, so downstream sparse handling keys off the verdict. - P2: `readSnapshotQualityVerdict` cast any string state/backend into the union, so a malformed object suppressed the legacy node-shape detectors. State and backend are now validated against their unions (unknown → verdict-absent → legacy detectors run); an unknown reasonCode is dropped rather than rejecting the whole verdict, so a forward-version runner still yields a usable verdict. Unit-covered: Swift resolveSnapshotPlanTerminal matrix + fatal-verdict assertion; TS parser accept/reject/forward-compat. Full suite 249 files / 2449 tests, fallow, lint, runner build green.
1 parent 3a868ef commit 427b604

4 files changed

Lines changed: 162 additions & 6 deletions

File tree

‎ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -384,8 +384,18 @@ extension RunnerTests {
384384
func snapshotAccessibilityUnavailable(failure: SnapshotCaptureFailure) -> DataPayload {
385385
NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_AX_UNAVAILABLE=%@", failure.message)
386386
invalidateCachedTarget(reason: Self.axSnapshotUnavailableReason)
387+
// This is a planned terminal result, so it carries the structured verdict like every other
388+
// planned snapshot — downstream sparse handling keys off the verdict, not node shapes.
387389
return sparseTruncatedSnapshotPayload(
388390
message: recoveredSnapshotMessage(failure),
391+
snapshotQuality: SnapshotQuality(
392+
state: "sparse",
393+
backend: SnapshotBackendKind.recursiveTree.rawValue,
394+
reason: failure.message,
395+
reasonCode: "ax-rejected",
396+
effectiveDepth: nil,
397+
collapsedLeafIndexes: nil
398+
),
389399
runnerFatal: true,
390400
runnerFatalReason: Self.axSnapshotUnavailableReason
391401
)
@@ -405,13 +415,15 @@ extension RunnerTests {
405415

406416
func sparseTruncatedSnapshotPayload(
407417
message: String? = nil,
418+
snapshotQuality: SnapshotQuality? = nil,
408419
runnerFatal: Bool? = nil,
409420
runnerFatalReason: String? = nil
410421
) -> DataPayload {
411422
return DataPayload(
412423
message: message,
413424
nodes: [compactInteractiveRootNode(rect: .zero)],
414425
truncated: true,
426+
snapshotQuality: snapshotQuality,
415427
runnerFatal: runnerFatal,
416428
runnerFatalReason: runnerFatalReason
417429
)

‎ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift‎

Lines changed: 68 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -129,12 +129,20 @@ extension RunnerTests {
129129
}
130130

131131
if let axFailure {
132-
switch terminal {
133-
case .throwOnAXFailure:
132+
switch Self.resolveSnapshotPlanTerminal(
133+
terminal: terminal,
134+
interactiveOnly: options.interactiveOnly
135+
) {
136+
case .throwAxFailure:
134137
throw axFailure
135-
case .sparseWithFatalOnAXFailure where options.interactiveOnly && best == nil:
138+
case .failClosed:
139+
// Fail closed on any interactive AX serialization failure that no backend recovered:
140+
// invalidate the cached target so the next command reacquires it (AX-unavailable target
141+
// invalidation, CONTEXT.md). A sparse `best` from a later tier (e.g. the query sweep's
142+
// synthetic root) must NOT suppress this — reaching the terminal already means no backend
143+
// produced a usable tree.
136144
return snapshotAccessibilityUnavailable(failure: axFailure)
137-
default:
145+
case .sparseBest:
138146
break
139147
}
140148
}
@@ -190,6 +198,27 @@ extension RunnerTests {
190198
return nil
191199
}
192200

201+
/// Terminal action when a capture plan exhausted every backend with an AX serialization
202+
/// failure still pending. Pure so the fail-closed-vs-sparse policy is unit-testable without
203+
/// a live app (the ordering gap the architecture review flagged).
204+
enum SnapshotPlanTerminalAction: Equatable {
205+
case throwAxFailure
206+
case failClosed
207+
case sparseBest
208+
}
209+
210+
static func resolveSnapshotPlanTerminal(
211+
terminal: SnapshotCaptureTerminalPolicy,
212+
interactiveOnly: Bool
213+
) -> SnapshotPlanTerminalAction {
214+
switch terminal {
215+
case .throwOnAXFailure:
216+
return .throwAxFailure
217+
case .sparseWithFatalOnAXFailure:
218+
return interactiveOnly ? .failClosed : .sparseBest
219+
}
220+
}
221+
193222
static func isSparseApplicationWindowTree(_ nodes: [SnapshotNode]) -> Bool {
194223
guard !nodes.isEmpty else { return false }
195224
return nodes.allSatisfy { node in
@@ -359,4 +388,39 @@ extension RunnerTests {
359388
)
360389
)
361390
}
391+
func testTerminalFailsClosedOnInteractiveAxFailureRegardlessOfSparseBest() {
392+
// Interactive AX failure must invalidate + fail closed; a later tier's sparse synthetic-root
393+
// "best" must never downgrade this to a returned-sparse payload (regression: best == nil guard).
394+
XCTAssertEqual(
395+
Self.resolveSnapshotPlanTerminal(terminal: .sparseWithFatalOnAXFailure, interactiveOnly: true),
396+
.failClosed
397+
)
398+
XCTAssertEqual(
399+
Self.resolveSnapshotPlanTerminal(terminal: .sparseWithFatalOnAXFailure, interactiveOnly: false),
400+
.sparseBest
401+
)
402+
XCTAssertEqual(
403+
Self.resolveSnapshotPlanTerminal(terminal: .throwOnAXFailure, interactiveOnly: true),
404+
.throwAxFailure
405+
)
406+
}
407+
408+
func testSnapshotAccessibilityUnavailableCarriesSparseVerdict() {
409+
currentApp = app
410+
currentBundleId = "com.example.app"
411+
defer {
412+
currentApp = nil
413+
currentBundleId = nil
414+
}
415+
let payload = snapshotAccessibilityUnavailable(
416+
failure: SnapshotCaptureFailure(
417+
code: "IOS_AX_SNAPSHOT_FAILED",
418+
message: "kAXErrorIllegalArgument",
419+
hint: "use screenshot"
420+
)
421+
)
422+
XCTAssertEqual(payload.runnerFatal, true)
423+
XCTAssertEqual(payload.snapshotQuality?.state, "sparse")
424+
XCTAssertEqual(payload.snapshotQuality?.reasonCode, "ax-rejected")
425+
}
362426
}
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
import { test } from 'vitest';
2+
import assert from 'node:assert/strict';
3+
4+
import { readSnapshotQualityVerdict } from '../snapshot-quality.ts';
5+
6+
test('readSnapshotQualityVerdict accepts a well-formed verdict', () => {
7+
const verdict = readSnapshotQualityVerdict({
8+
state: 'recovered',
9+
backend: 'private-ax',
10+
reason: 'sparse tree',
11+
reasonCode: 'budget',
12+
effectiveDepth: 56,
13+
collapsedLeafIndexes: [3],
14+
});
15+
assert.deepEqual(verdict, {
16+
state: 'recovered',
17+
backend: 'private-ax',
18+
reason: 'sparse tree',
19+
reasonCode: 'budget',
20+
effectiveDepth: 56,
21+
collapsedLeafIndexes: [3],
22+
});
23+
});
24+
25+
test('readSnapshotQualityVerdict rejects unknown state or backend as verdict-absent', () => {
26+
// A malformed object must not be treated as an authoritative verdict — it has to fall through
27+
// so legacy node-shape detectors still run instead of being silently suppressed.
28+
assert.equal(readSnapshotQualityVerdict({ state: 'bogus', backend: 'tree' }), undefined);
29+
assert.equal(readSnapshotQualityVerdict({ state: 'sparse', backend: 'mystery' }), undefined);
30+
assert.equal(readSnapshotQualityVerdict({ backend: 'tree' }), undefined);
31+
assert.equal(readSnapshotQualityVerdict(null), undefined);
32+
});
33+
34+
test('readSnapshotQualityVerdict keeps the verdict but drops an unknown reasonCode', () => {
35+
// Forward-compat: a newer runner adding a reasonCode must still yield a usable verdict.
36+
const verdict = readSnapshotQualityVerdict({
37+
state: 'sparse',
38+
backend: 'queries',
39+
reasonCode: 'future-code',
40+
});
41+
assert.equal(verdict?.state, 'sparse');
42+
assert.equal(verdict?.reasonCode, undefined);
43+
});

‎src/utils/snapshot-quality.ts‎

Lines changed: 39 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,16 +13,53 @@ export type SnapshotQualityVerdict = {
1313
collapsedLeafIndexes?: number[];
1414
};
1515

16+
const SNAPSHOT_QUALITY_STATES = new Set<SnapshotQualityVerdict['state']>([
17+
'healthy',
18+
'recovered',
19+
'sparse',
20+
]);
21+
const SNAPSHOT_QUALITY_BACKENDS = new Set<SnapshotQualityVerdict['backend']>([
22+
'tree',
23+
'queries',
24+
'private-ax',
25+
]);
26+
const SNAPSHOT_QUALITY_REASON_CODES = new Set<NonNullable<SnapshotQualityVerdict['reasonCode']>>([
27+
'ax-rejected',
28+
'sparse-tree',
29+
'budget',
30+
'no-nodes',
31+
'capture-failed',
32+
]);
33+
1634
export function readSnapshotQualityVerdict(value: unknown): SnapshotQualityVerdict | undefined {
1735
if (!value || typeof value !== 'object') return undefined;
1836
const raw = value as Record<string, unknown>;
19-
if (typeof raw.state !== 'string' || typeof raw.backend !== 'string') return undefined;
37+
// Validate the load-bearing union fields: an object with an unknown state/backend is not a
38+
// verdict this version understands, so it falls through as verdict-absent and the legacy
39+
// node-shape detectors run instead of being silently suppressed by a malformed payload.
40+
if (
41+
typeof raw.state !== 'string' ||
42+
!SNAPSHOT_QUALITY_STATES.has(raw.state as SnapshotQualityVerdict['state'])
43+
) {
44+
return undefined;
45+
}
46+
if (
47+
typeof raw.backend !== 'string' ||
48+
!SNAPSHOT_QUALITY_BACKENDS.has(raw.backend as SnapshotQualityVerdict['backend'])
49+
) {
50+
return undefined;
51+
}
2052
return {
2153
state: raw.state as SnapshotQualityVerdict['state'],
2254
backend: raw.backend as SnapshotQualityVerdict['backend'],
2355
reason: typeof raw.reason === 'string' ? raw.reason : undefined,
56+
// An unknown reasonCode is dropped, not rejected: a forward-version runner that adds one
57+
// still yields a usable verdict (only the budget-specific wording is keyed off it).
2458
reasonCode:
25-
typeof raw.reasonCode === 'string'
59+
typeof raw.reasonCode === 'string' &&
60+
SNAPSHOT_QUALITY_REASON_CODES.has(
61+
raw.reasonCode as NonNullable<SnapshotQualityVerdict['reasonCode']>,
62+
)
2663
? (raw.reasonCode as SnapshotQualityVerdict['reasonCode'])
2764
: undefined,
2865
effectiveDepth: typeof raw.effectiveDepth === 'number' ? raw.effectiveDepth : undefined,

0 commit comments

Comments
 (0)