Skip to content

Commit 0425df2

Browse files
authored
refactor: bundle snapshot capture annotations (#777)
* refactor: bundle snapshot capture annotations * refactor: address snapshot annotations review * test: cover snapshot annotation quality mapping
1 parent fa8cce3 commit 0425df2

12 files changed

Lines changed: 296 additions & 115 deletions

File tree

‎src/__tests__/client-shared.test.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,3 +130,24 @@ test('serializeSnapshotResult includes Android backend metadata', () => {
130130
},
131131
});
132132
});
133+
134+
test('serializeSnapshotResult maps capture quality annotation to public snapshotQuality', () => {
135+
const snapshotQuality = {
136+
state: 'healthy',
137+
backend: 'tree',
138+
} as const;
139+
const data = serializeSnapshotResult({
140+
nodes: [],
141+
truncated: false,
142+
quality: snapshotQuality,
143+
identifiers: {
144+
session: 'qa',
145+
},
146+
} as Parameters<typeof serializeSnapshotResult>[0] & { quality: typeof snapshotQuality });
147+
148+
assert.deepEqual(data, {
149+
nodes: [],
150+
truncated: false,
151+
snapshotQuality,
152+
});
153+
});

‎src/__tests__/client.test.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -623,6 +623,30 @@ test('client capture.snapshot preserves visibility metadata from daemon response
623623
});
624624
});
625625

626+
test('client capture.snapshot preserves snapshot quality annotation from daemon responses', async () => {
627+
const snapshotQuality = {
628+
state: 'recovered',
629+
backend: 'queries',
630+
reason: 'tree was sparse',
631+
reasonCode: 'sparse-tree',
632+
effectiveDepth: 2,
633+
collapsedLeafIndexes: [7],
634+
} as const;
635+
const setup = createTransport(async () => ({
636+
ok: true,
637+
data: {
638+
nodes: [],
639+
truncated: false,
640+
snapshotQuality,
641+
},
642+
}));
643+
const client = createAgentDeviceClient(setup.config, { transport: setup.transport });
644+
645+
const result = await client.capture.snapshot();
646+
647+
assert.deepEqual(result.snapshotQuality, snapshotQuality);
648+
});
649+
626650
test('client capture.snapshot forwards force-full as snapshotForceFull flag', async () => {
627651
const setup = createTransport(async () => ({
628652
ok: true,

‎src/backend.ts‎

Lines changed: 8 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
import type { SnapshotQualityVerdict } from './utils/snapshot-quality.ts';
2-
import type { AndroidSnapshotBackendMetadata } from './platforms/android/snapshot-types.ts';
31
import type { AlertAction, AlertInfo } from './alert-contract.ts';
42
import type { AppsFilter } from './contracts/app-inventory.ts';
53
import type {
@@ -17,6 +15,11 @@ import type { ClickButton } from './core/click-button.ts';
1715
import type { DeviceRotation } from './core/device-rotation.ts';
1816
import type { ScrollDirection } from './core/scroll-gesture.ts';
1917
import type { SessionSurface } from './core/session-surface.ts';
18+
import type {
19+
SnapshotCaptureAnalysis,
20+
SnapshotCaptureAnnotations,
21+
SnapshotCaptureFreshness,
22+
} from './snapshot-capture-annotations.ts';
2023

2124
export type AgentDeviceBackendPlatform = Platform;
2225

@@ -44,30 +47,17 @@ export type BackendSnapshotResult = {
4447
truncated?: boolean;
4548
backend?: string;
4649
snapshot?: SnapshotState;
47-
analysis?: BackendSnapshotAnalysis;
48-
androidSnapshot?: AndroidSnapshotBackendMetadata;
49-
freshness?: BackendSnapshotFreshness;
50-
warnings?: string[];
51-
quality?: SnapshotQualityVerdict;
5250
appName?: string;
5351
appBundleId?: string;
54-
};
52+
} & SnapshotCaptureAnnotations;
5553

5654
export type BackendSnapshotOptions = SnapshotOptions & {
5755
outPath?: string;
5856
};
5957

60-
export type BackendSnapshotAnalysis = {
61-
rawNodeCount?: number;
62-
maxDepth?: number;
63-
};
58+
export type BackendSnapshotAnalysis = SnapshotCaptureAnalysis;
6459

65-
export type BackendSnapshotFreshness = {
66-
action: string;
67-
retryCount: number;
68-
staleAfterRetries: boolean;
69-
reason?: 'empty-interactive' | 'sharp-drop' | 'stuck-route';
70-
};
60+
export type BackendSnapshotFreshness = SnapshotCaptureFreshness;
7161

7262
export type BackendReadTextResult = {
7363
text: string;

‎src/client-shared.ts‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ import type {
1010
CaptureSnapshotResult,
1111
SessionCloseResult,
1212
} from './client-types.ts';
13+
import {
14+
publicSnapshotCaptureAnnotations,
15+
type SnapshotCaptureAnnotations,
16+
} from './snapshot-capture-annotations.ts';
1317
import type { Platform } from './utils/device.ts';
1418
import { successText, withSuccessText } from './utils/success-text.ts';
1519

@@ -172,9 +176,17 @@ export function serializeSnapshotResult(result: CaptureSnapshotResult): Record<s
172176
...(result.appName ? { appName: result.appName } : {}),
173177
...(result.appBundleId ? { appBundleId: result.appBundleId } : {}),
174178
...(result.visibility ? { visibility: result.visibility } : {}),
175-
...(result.androidSnapshot ? { androidSnapshot: result.androidSnapshot } : {}),
176-
...(result.snapshotQuality ? { snapshotQuality: result.snapshotQuality } : {}),
177-
...(result.warnings && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
179+
...publicSnapshotCaptureAnnotations(snapshotResultAnnotations(result)),
178180
...(result.unchanged ? { unchanged: result.unchanged } : {}),
179181
};
180182
}
183+
184+
function snapshotResultAnnotations(
185+
result: CaptureSnapshotResult,
186+
): Partial<SnapshotCaptureAnnotations> {
187+
const annotations = result as CaptureSnapshotResult & Partial<SnapshotCaptureAnnotations>;
188+
return {
189+
...annotations,
190+
...(result.snapshotQuality ? { quality: result.snapshotQuality } : {}),
191+
};
192+
}

‎src/client-types.ts‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import type { SnapshotQualityVerdict } from './utils/snapshot-quality.ts';
1+
import type { PublicSnapshotCaptureAnnotations } from './snapshot-capture-annotations.ts';
22
import type {
33
DaemonResponseData,
44
DaemonInstallSource,
@@ -26,7 +26,6 @@ import type { ScrollInputDirection } from './commands/interaction-gestures.ts';
2626
import type { LogAction } from './contracts/logs.ts';
2727
import type { SessionSurface } from './core/session-surface.ts';
2828
import type { FindLocator } from './utils/finders.ts';
29-
import type { AndroidSnapshotBackendMetadata } from './platforms/android/snapshot-types.ts';
3029
import type {
3130
ScreenshotOverlayRef,
3231
SnapshotNode,
@@ -335,12 +334,9 @@ export type CaptureSnapshotResult = {
335334
appName?: string;
336335
appBundleId?: string;
337336
visibility?: SnapshotVisibility;
338-
androidSnapshot?: AndroidSnapshotBackendMetadata;
339-
warnings?: string[];
340337
unchanged?: SnapshotUnchanged;
341338
identifiers: AgentDeviceIdentifiers;
342-
snapshotQuality?: SnapshotQualityVerdict;
343-
};
339+
} & PublicSnapshotCaptureAnnotations;
344340

345341
export type CaptureScreenshotOptions = AgentDeviceRequestOverrides & {
346342
path?: string;

‎src/client.ts‎

Lines changed: 2 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
import { readSnapshotQualityVerdict } from './utils/snapshot-quality.ts';
21
import { sendToDaemon } from './daemon-client.ts';
32
import { prepareMetroRuntime, reloadMetro } from './client-metro.ts';
43
import { resolveDaemonPaths } from './daemon/config.ts';
@@ -42,6 +41,7 @@ import type {
4241
MaterializationReleaseOptions,
4342
MetroPrepareOptions,
4443
} from './client-types.ts';
44+
import { readSerializedSnapshotCaptureAnnotations } from './snapshot-capture-annotations.ts';
4545

4646
export function createAgentDeviceClient(
4747
config: AgentDeviceClientConfig = {},
@@ -342,20 +342,11 @@ function optionalSnapshotResponseFields(
342342
>
343343
> {
344344
const visibility = readObject(data.visibility);
345-
const androidSnapshot = readObject(data.androidSnapshot);
346345
const unchanged = readObject(data.unchanged);
347-
const warnings = Array.isArray(data.warnings)
348-
? data.warnings.filter((entry): entry is string => typeof entry === 'string')
349-
: undefined;
350-
const snapshotQuality = readSnapshotQualityVerdict(data.snapshotQuality);
351346
return {
352347
...(visibility ? { visibility: visibility as CaptureSnapshotResult['visibility'] } : {}),
353-
...(snapshotQuality ? { snapshotQuality } : {}),
354-
...(androidSnapshot
355-
? { androidSnapshot: androidSnapshot as CaptureSnapshotResult['androidSnapshot'] }
356-
: {}),
348+
...readSerializedSnapshotCaptureAnnotations(data),
357349
...(unchanged ? { unchanged: unchanged as CaptureSnapshotResult['unchanged'] } : {}),
358-
...(warnings ? { warnings } : {}),
359350
};
360351
}
361352

‎src/commands/capture-snapshot.ts‎

Lines changed: 31 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
import type { BackendSnapshotResult } from '../backend.ts';
2-
import type { AndroidSnapshotBackendMetadata } from '../platforms/android/snapshot-types.ts';
32
import type { AgentDeviceRuntime, CommandSessionRecord } from '../runtime-contract.ts';
43
import {
5-
renderSnapshotQualityWarnings,
6-
type SnapshotQualityVerdict,
7-
} from '../utils/snapshot-quality.ts';
4+
publicSnapshotCaptureAnnotations,
5+
snapshotCaptureAnnotationsFrom,
6+
type PublicSnapshotCaptureAnnotations,
7+
type SnapshotCaptureAnnotations,
8+
} from '../snapshot-capture-annotations.ts';
9+
import { renderSnapshotQualityWarnings } from '../utils/snapshot-quality.ts';
810
import { AppError } from '../utils/errors.ts';
911
import { buildSnapshotDiff, countSnapshotComparableLines } from '../utils/snapshot-diff.ts';
1012
import type { SnapshotDiffLine, SnapshotDiffSummary } from '../utils/snapshot-diff.ts';
@@ -35,11 +37,8 @@ export type SnapshotCommandResult = {
3537
appName?: string;
3638
appBundleId?: string;
3739
visibility?: SnapshotVisibility;
38-
androidSnapshot?: AndroidSnapshotBackendMetadata;
39-
warnings?: string[];
4040
unchanged?: SnapshotUnchanged;
41-
snapshotQuality?: SnapshotQualityVerdict;
42-
};
41+
} & PublicSnapshotCaptureAnnotations;
4342

4443
export type DiffSnapshotCommandResult = {
4544
mode: 'snapshot';
@@ -53,6 +52,7 @@ type SnapshotCapture = {
5352
snapshot: SnapshotState;
5453
result: BackendSnapshotResult;
5554
session: CommandSessionRecord | undefined;
55+
annotations: SnapshotCaptureAnnotations;
5656
warnings: string[];
5757
};
5858

@@ -79,9 +79,10 @@ export const snapshotCommand: RuntimeCommand<
7979
backend: capture.snapshot.backend,
8080
snapshotRaw: options.raw,
8181
}),
82-
...(capture.result.androidSnapshot ? { androidSnapshot: capture.result.androidSnapshot } : {}),
83-
...(capture.result.quality ? { snapshotQuality: capture.result.quality } : {}),
84-
...(capture.warnings.length > 0 ? { warnings: capture.warnings } : {}),
82+
...publicSnapshotCaptureAnnotations({
83+
...capture.annotations,
84+
warnings: capture.warnings,
85+
}),
8586
...(unchanged ? { unchanged } : {}),
8687
...snapshotAppFields(capture),
8788
};
@@ -158,13 +159,16 @@ async function captureRuntimeSnapshot(
158159
normalizeBackendSnapshot(result, runtime),
159160
options,
160161
);
162+
const annotations = snapshotCaptureAnnotationsFrom(result);
161163
const warningTime = now(runtime);
162164
return {
163165
snapshot,
164166
result,
165167
session,
168+
annotations,
166169
warnings: buildSnapshotWarnings({
167170
result,
171+
annotations,
168172
snapshot,
169173
options,
170174
session,
@@ -215,24 +219,29 @@ function snapshotAppFields(capture: SnapshotCapture): {
215219

216220
function buildSnapshotWarnings(params: {
217221
result: BackendSnapshotResult;
222+
annotations: SnapshotCaptureAnnotations;
218223
snapshot: SnapshotState;
219224
options: SnapshotCommandOptions;
220225
session: CommandSessionRecord | undefined;
221226
capturedAt: number;
222227
runtimeNow: number;
223228
}): string[] {
224-
const warnings = [...(params.result.warnings ?? [])];
225-
if (params.result.quality) {
226-
warnings.push(...renderSnapshotQualityWarnings(params.result.quality, params.snapshot.nodes));
229+
const warnings = [...(params.annotations.warnings ?? [])];
230+
if (params.annotations.quality) {
231+
warnings.push(
232+
...renderSnapshotQualityWarnings(params.annotations.quality, params.snapshot.nodes),
233+
);
227234
}
228235
warnings.push(...buildEmptyAndroidInteractiveWarnings(params));
229-
if (!params.result.quality) {
236+
if (!params.annotations.quality) {
230237
// Legacy runners without a structured verdict keep the old daemon-side heuristics.
231238
warnings.push(...buildSparseIosInteractiveWarnings(params));
232239
warnings.push(...buildMergedAccessibilityLeafWarnings(params.snapshot.nodes));
233240
}
234241

235-
const helperFallbackWarning = formatAndroidHelperFallbackWarning(params.result.androidSnapshot);
242+
const helperFallbackWarning = formatAndroidHelperFallbackWarning(
243+
params.annotations.androidSnapshot,
244+
);
236245
if (helperFallbackWarning) warnings.push(helperFallbackWarning);
237246

238247
const reactNativeOverlayWarning = formatReactNativeOverlayWarning(params.snapshot.nodes);
@@ -241,7 +250,7 @@ function buildSnapshotWarnings(params: {
241250
const recentDropWarning = formatRecentSnapshotDropWarning(params);
242251
if (recentDropWarning) warnings.push(recentDropWarning);
243252

244-
warnings.push(...formatFreshnessWarnings(params.result.freshness, params.snapshot.backend));
253+
warnings.push(...formatFreshnessWarnings(params.annotations.freshness, params.snapshot.backend));
245254
return Array.from(new Set(warnings));
246255
}
247256

@@ -295,11 +304,11 @@ function buildMergedAccessibilityLeafWarnings(nodes: SnapshotState['nodes']): st
295304
}
296305

297306
function buildEmptyAndroidInteractiveWarnings(params: {
298-
result: BackendSnapshotResult;
307+
annotations: SnapshotCaptureAnnotations;
299308
snapshot: SnapshotState;
300309
options: SnapshotCommandOptions;
301310
}): string[] {
302-
const analysis = params.result.analysis;
311+
const analysis = params.annotations.analysis;
303312
if (
304313
params.snapshot.backend !== 'android' ||
305314
params.options.interactiveOnly !== true ||
@@ -326,23 +335,23 @@ function buildEmptyAndroidInteractiveWarnings(params: {
326335
}
327336

328337
function formatAndroidHelperFallbackWarning(
329-
androidSnapshot: AndroidSnapshotBackendMetadata | undefined,
338+
androidSnapshot: SnapshotCaptureAnnotations['androidSnapshot'],
330339
): string | undefined {
331340
if (androidSnapshot?.backend !== 'uiautomator-dump') return undefined;
332341
const reason = androidSnapshot.fallbackReason ? ` Reason: ${androidSnapshot.fallbackReason}` : '';
333342
return `Android snapshot helper unavailable; using stock UIAutomator dump, which can time out on busy React Native UIs.${reason}`;
334343
}
335344

336345
function formatRecentSnapshotDropWarning(params: {
337-
result: BackendSnapshotResult;
346+
annotations: SnapshotCaptureAnnotations;
338347
snapshot: SnapshotState;
339348
session: CommandSessionRecord | undefined;
340349
capturedAt: number;
341350
runtimeNow: number;
342351
}): string | undefined {
343352
const previousSnapshot = params.session?.snapshot;
344353
if (
345-
!params.result.freshness &&
354+
!params.annotations.freshness &&
346355
previousSnapshot &&
347356
hasSameSnapshotPresentation(previousSnapshot, params.snapshot) &&
348357
isRecentSnapshot(previousSnapshot, params.capturedAt, params.runtimeNow) &&

‎src/core/interactors/android.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ import { screenshotAndroid } from '../../platforms/android/screenshot.ts';
3131
import { withDiagnosticTimer } from '../../utils/diagnostics.ts';
3232
import type { DeviceInfo } from '../../utils/device.ts';
3333
import type { Interactor } from '../interactor-types.ts';
34+
import { snapshotCaptureAnnotationsFrom } from '../../snapshot-capture-annotations.ts';
3435

3536
export function createAndroidInteractor(device: DeviceInfo): Interactor {
3637
return {
@@ -78,8 +79,7 @@ export function createAndroidInteractor(device: DeviceInfo): Interactor {
7879
nodes: result.nodes ?? [],
7980
truncated: result.truncated ?? false,
8081
backend: 'android',
81-
analysis: result.analysis,
82-
androidSnapshot: result.androidSnapshot,
82+
...snapshotCaptureAnnotationsFrom(result),
8383
};
8484
},
8585
back: (_mode) => backAndroid(device),

0 commit comments

Comments
 (0)