Skip to content

Commit 6ee483c

Browse files
authored
feat: warn when @refs outlive the session snapshot they came from (#1093)
Refs are positional indexes into the latest stored session tree; any selector-based command's resolution capture silently reshuffles them (#1076). Track an honest marker on the daemon session (snapshotRefsStale): set wherever the stored snapshot is replaced by a response that does not hand the new refs to the client, cleared only where the client demonstrably receives them (snapshot responses, find ref outputs). Commands consuming @ref arguments while the marker is set (press/click/longpress/fill/get/wait) attach a warning and still execute — the geometric guards keep catching detectable drift. Closes #1076
1 parent ad754ac commit 6ee483c

12 files changed

Lines changed: 560 additions & 9 deletions

‎src/daemon/handlers/__tests__/find.test.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -730,3 +730,30 @@ test('handleFindCommands wait captures fresh snapshots while polling', async ()
730730
}
731731
expect(mockDispatch).toHaveBeenCalledTimes(2);
732732
});
733+
734+
test('handleFindCommands click re-issues a fresh ref and clears the stale-refs marker (#1076)', async () => {
735+
const sessionName = 'default';
736+
const session = makeSession(sessionName);
737+
// As set by an earlier selector-resolution capture that replaced the tree.
738+
session.snapshotRefsStale = true;
739+
740+
const { response, session: storedSession } = await runFindClickScenario({
741+
positionals: ['Increment', 'click'],
742+
nodes: [
743+
{
744+
index: 0,
745+
type: 'Button',
746+
label: 'Increment',
747+
hittable: true,
748+
rect: { x: 50, y: 0, width: 100, height: 100 },
749+
depth: 0,
750+
},
751+
],
752+
session,
753+
});
754+
755+
expect(response.ok).toBe(true);
756+
// The response returns a ref minted from the freshly stored snapshot, so
757+
// the marker clears before the internal click @ref sub-invocation runs.
758+
expect(storedSession.snapshotRefsStale).toBe(false);
759+
});

‎src/daemon/handlers/__tests__/interaction.test.ts‎

Lines changed: 211 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import type { CommandFlags } from '../../../core/dispatch.ts';
66
import { attachRefs, type SnapshotBackend } from '../../../kernel/snapshot.ts';
77
import { AppError } from '../../../kernel/errors.ts';
88
import { buildSnapshotState } from '../snapshot-capture.ts';
9+
import { setSessionSnapshot, STALE_SNAPSHOT_REFS_WARNING } from '../../session-snapshot.ts';
910
import { makeSessionStore } from '../../../__tests__/test-utils/store-factory.ts';
1011
import {
1112
makeIosSession,
@@ -106,7 +107,9 @@ async function emulateCaptureSnapshotForSession(
106107
contextFromFlags(effectiveFlags, session.appBundleId, session.trace?.outPath),
107108
)) as { nodes?: never[]; truncated?: boolean; backend?: SnapshotBackend };
108109
const snapshot = buildSnapshotState(snapshotData ?? {}, effectiveFlags);
109-
session.snapshot = snapshot;
110+
// Mirror the real captureSnapshotForSession: session snapshot writes go
111+
// through setSessionSnapshot so snapshotRefsStale tracking (#1076) applies.
112+
setSessionSnapshot(session, snapshot);
110113
sessionStore.set(session.name, session);
111114
return snapshot;
112115
}
@@ -3196,3 +3199,210 @@ test('is reports Android permission dialog blocker when app content assertion fa
31963199
});
31973200
}
31983201
});
3202+
3203+
// --- Stale @ref warnings (#1076) ---
3204+
3205+
function makeTwoButtonNodes() {
3206+
return [
3207+
{
3208+
index: 0,
3209+
type: 'Application',
3210+
rect: { x: 0, y: 0, width: 390, height: 844 },
3211+
},
3212+
{
3213+
index: 1,
3214+
parentIndex: 0,
3215+
type: 'XCUIElementTypeButton',
3216+
label: 'Continue',
3217+
rect: { x: 10, y: 20, width: 100, height: 40 },
3218+
enabled: true,
3219+
hittable: true,
3220+
},
3221+
{
3222+
index: 2,
3223+
parentIndex: 0,
3224+
type: 'XCUIElementTypeButton',
3225+
label: 'Cancel',
3226+
rect: { x: 10, y: 80, width: 100, height: 40 },
3227+
enabled: true,
3228+
hittable: true,
3229+
},
3230+
];
3231+
}
3232+
3233+
function makeStaleRefSession(sessionName: string): SessionState {
3234+
const session = makeSession(sessionName);
3235+
session.snapshot = {
3236+
nodes: attachRefs(makeTwoButtonNodes() as never),
3237+
createdAt: Date.now(),
3238+
backend: 'xctest',
3239+
};
3240+
// As if the snapshot command just returned these refs to the client.
3241+
session.snapshotRefsStale = false;
3242+
return session;
3243+
}
3244+
3245+
async function runInteraction(
3246+
sessionStore: SessionStore,
3247+
sessionName: string,
3248+
command: string,
3249+
positionals: string[],
3250+
flags: Record<string, unknown> = {},
3251+
) {
3252+
return await handleInteractionCommands({
3253+
req: { token: 't', session: sessionName, command, positionals, flags },
3254+
sessionName,
3255+
sessionStore,
3256+
contextFromFlags,
3257+
});
3258+
}
3259+
3260+
test('press selector then press @ref warns that refs outlived the stored snapshot', async () => {
3261+
const sessionStore = makeSessionStore();
3262+
const sessionName = 'stale-ref-warns';
3263+
const session = makeStaleRefSession(sessionName);
3264+
sessionStore.set(sessionName, session);
3265+
mockDispatch.mockImplementation(async (_device, command) =>
3266+
command === 'snapshot' ? { nodes: makeTwoButtonNodes(), backend: 'xctest' } : {},
3267+
);
3268+
3269+
// Selector press: its resolution capture replaces the stored snapshot
3270+
// without handing the new refs back to the client.
3271+
const selectorPress = await runInteraction(sessionStore, sessionName, 'press', [
3272+
'label=Continue',
3273+
]);
3274+
if (!selectorPress?.ok) {
3275+
throw new Error(`selector press failed: ${JSON.stringify(selectorPress)}`);
3276+
}
3277+
expect(selectorPress.data?.warning).toBeUndefined();
3278+
expect(sessionStore.get(sessionName)?.snapshotRefsStale).toBe(true);
3279+
3280+
const refPress = await runInteraction(sessionStore, sessionName, 'press', ['@e1']);
3281+
expect(refPress?.ok).toBe(true);
3282+
if (refPress?.ok) {
3283+
expect(refPress.data?.warning).toBe(STALE_SNAPSHOT_REFS_WARNING);
3284+
}
3285+
});
3286+
3287+
test('press @ref directly after refs were issued does not warn', async () => {
3288+
const sessionStore = makeSessionStore();
3289+
const sessionName = 'fresh-ref-no-warning';
3290+
const session = makeStaleRefSession(sessionName);
3291+
sessionStore.set(sessionName, session);
3292+
3293+
const response = await runInteraction(sessionStore, sessionName, 'press', ['@e1']);
3294+
expect(response?.ok).toBe(true);
3295+
if (response?.ok) {
3296+
expect(response.data?.warning).toBeUndefined();
3297+
}
3298+
});
3299+
3300+
test('re-issuing refs clears the stale marker so press @ref does not warn', async () => {
3301+
const sessionStore = makeSessionStore();
3302+
const sessionName = 'reissued-refs-no-warning';
3303+
const session = makeStaleRefSession(sessionName);
3304+
sessionStore.set(sessionName, session);
3305+
mockDispatch.mockImplementation(async (_device, command) =>
3306+
command === 'snapshot' ? { nodes: makeTwoButtonNodes(), backend: 'xctest' } : {},
3307+
);
3308+
3309+
const selectorPress = await runInteraction(sessionStore, sessionName, 'press', [
3310+
'label=Continue',
3311+
]);
3312+
expect(selectorPress?.ok).toBe(true);
3313+
expect(sessionStore.get(sessionName)?.snapshotRefsStale).toBe(true);
3314+
3315+
// Simulate the snapshot command re-issuing refs (its handler clears the
3316+
// marker through buildNextSnapshotSession; covered in snapshot-handler tests).
3317+
const stored = sessionStore.get(sessionName)!;
3318+
stored.snapshotRefsStale = false;
3319+
sessionStore.set(sessionName, stored);
3320+
3321+
const refPress = await runInteraction(sessionStore, sessionName, 'press', ['@e1']);
3322+
expect(refPress?.ok).toBe(true);
3323+
if (refPress?.ok) {
3324+
expect(refPress.data?.warning).toBeUndefined();
3325+
}
3326+
});
3327+
3328+
test('fill @ref warns while refs are stale', async () => {
3329+
const sessionStore = makeSessionStore();
3330+
const sessionName = 'stale-ref-fill';
3331+
const session = makeStaleRefSession(sessionName);
3332+
session.snapshot = {
3333+
nodes: attachRefs([
3334+
{
3335+
index: 0,
3336+
type: 'XCUIElementTypeTextField',
3337+
label: 'Email',
3338+
rect: { x: 10, y: 20, width: 200, height: 40 },
3339+
enabled: true,
3340+
hittable: true,
3341+
},
3342+
]),
3343+
createdAt: Date.now(),
3344+
backend: 'xctest',
3345+
};
3346+
session.snapshotRefsStale = true;
3347+
sessionStore.set(sessionName, session);
3348+
3349+
const response = await runInteraction(sessionStore, sessionName, 'fill', [
3350+
'@e1',
3351+
3352+
]);
3353+
expect(response?.ok).toBe(true);
3354+
if (response?.ok) {
3355+
expect(response.data?.warning).toBe(STALE_SNAPSHOT_REFS_WARNING);
3356+
}
3357+
});
3358+
3359+
test('get text @ref warns while refs are stale', async () => {
3360+
const sessionStore = makeSessionStore();
3361+
const sessionName = 'stale-ref-get-text';
3362+
const session = makeStaleRefSession(sessionName);
3363+
session.snapshotRefsStale = true;
3364+
sessionStore.set(sessionName, session);
3365+
mockDispatch.mockRejectedValue(
3366+
new Error('dispatch should not be called for snapshot-derived get text'),
3367+
);
3368+
3369+
const response = await runInteraction(sessionStore, sessionName, 'get', ['text', '@e1']);
3370+
expect(response?.ok).toBe(true);
3371+
if (response?.ok) {
3372+
expect(response.data?.warning).toBe(STALE_SNAPSHOT_REFS_WARNING);
3373+
expect(response.data?.ref).toBe('e1');
3374+
}
3375+
});
3376+
3377+
test('stale-ref warning appends to an existing interaction warning', async () => {
3378+
const sessionStore = makeSessionStore();
3379+
const sessionName = 'stale-ref-appends';
3380+
const session = makeStaleRefSession(sessionName);
3381+
session.snapshot = {
3382+
nodes: attachRefs([
3383+
{
3384+
index: 0,
3385+
// Non-fillable type produces the runtime fill warning the stale-ref
3386+
// warning must append to, not replace.
3387+
type: 'XCUIElementTypeStaticText',
3388+
label: 'Read-only',
3389+
rect: { x: 10, y: 20, width: 200, height: 40 },
3390+
enabled: true,
3391+
hittable: true,
3392+
},
3393+
]),
3394+
createdAt: Date.now(),
3395+
backend: 'xctest',
3396+
};
3397+
session.snapshotRefsStale = true;
3398+
sessionStore.set(sessionName, session);
3399+
3400+
const response = await runInteraction(sessionStore, sessionName, 'fill', ['@e1', 'nope']);
3401+
expect(response?.ok).toBe(true);
3402+
if (response?.ok) {
3403+
const warning = String(response.data?.warning ?? '');
3404+
expect(warning).toContain('attempting fill anyway');
3405+
expect(warning).toContain(STALE_SNAPSHOT_REFS_WARNING);
3406+
expect(warning.endsWith(STALE_SNAPSHOT_REFS_WARNING)).toBe(true);
3407+
}
3408+
});

‎src/daemon/handlers/__tests__/snapshot-handler.test.ts‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -402,6 +402,54 @@ test('snapshot on iOS runs when the session tracks an app', async () => {
402402
);
403403
});
404404

405+
test('snapshot clears the stale-refs marker; diff leaves client refs stale (#1076)', async () => {
406+
const sessionStore = makeSessionStore();
407+
const sessionName = 'android-stale-refs-marker';
408+
const session = makeSession(sessionName, androidDevice);
409+
session.snapshot = {
410+
nodes: [{ ref: 'e1', index: 0, depth: 0, type: 'android.widget.Button', label: 'Old' }],
411+
createdAt: Date.now(),
412+
backend: 'android',
413+
};
414+
// As set by a selector-resolution capture that replaced the stored tree.
415+
session.snapshotRefsStale = true;
416+
sessionStore.set(sessionName, session);
417+
mockDispatch.mockResolvedValue({
418+
nodes: [{ index: 0, depth: 0, type: 'android.widget.Button', label: 'Fresh' }],
419+
truncated: false,
420+
backend: 'android',
421+
});
422+
423+
const snapshotResponse = await handleSnapshotCommands({
424+
req: { token: 't', session: sessionName, command: 'snapshot', positionals: [], flags: {} },
425+
sessionName,
426+
logPath: '/tmp/daemon.log',
427+
sessionStore,
428+
});
429+
430+
// The snapshot response hands every stored node's ref to the client.
431+
expect(snapshotResponse?.ok).toBe(true);
432+
expect(sessionStore.get(sessionName)?.snapshotRefsStale).toBe(false);
433+
434+
const diffResponse = await handleSnapshotCommands({
435+
req: {
436+
token: 't',
437+
session: sessionName,
438+
command: 'diff',
439+
positionals: ['snapshot'],
440+
flags: {},
441+
},
442+
sessionName,
443+
logPath: '/tmp/daemon.log',
444+
sessionStore,
445+
});
446+
447+
// diff replaces the stored tree but only returns a summary, so the refs the
448+
// client holds go stale again.
449+
expect(diffResponse?.ok).toBe(true);
450+
expect(sessionStore.get(sessionName)?.snapshotRefsStale).toBe(true);
451+
});
452+
405453
test('snapshot surfaces filtered-to-zero Android guidance for interactive snapshots', async () => {
406454
const sessionStore = makeSessionStore();
407455
const sessionName = 'android-empty-interactive';

‎src/daemon/handlers/find.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ import { errorResponse, noActiveSessionError } from './response.ts';
2323
import { recordSessionAction } from './handler-utils.ts';
2424
import { stripInternalInteractionFlags } from '../interaction-outcome-policy.ts';
2525
import { dispatchFindReadOnlyViaRuntime } from '../selector-runtime.ts';
26+
import { markSessionSnapshotRefsIssued } from '../session-snapshot.ts';
2627
import { createSelectorCaptureRuntime } from '../selector-capture-runtime.ts';
2728
import {
2829
isSparseSnapshotQualityVerdict,
@@ -156,6 +157,15 @@ export async function handleFindCommands(params: {
156157
const ref = `@${resolvedNode.ref}`;
157158
const actionFlags = { ...(req.flags ?? {}), noRecord: true };
158159
const match: ResolvedMatch = { node, resolvedNode, ref, nodes, actionFlags };
160+
if (session) {
161+
// #1076 clear choke point: every action below returns `match.ref`, minted
162+
// from the snapshot the capture runtime just stored, so the client leaves
163+
// with a ref that matches the stored tree. Clearing here also keeps the
164+
// internal `click/fill @ref` sub-invocations from attaching a spurious
165+
// stale-refs warning to the find response.
166+
markSessionSnapshotRefsIssued(session);
167+
sessionStore.set(sessionName, session);
168+
}
159169

160170
const actionHandlers: Record<string, () => Promise<DaemonResponse | null>> = {
161171
exists: () => handleFindExists(ctx),

‎src/daemon/handlers/interaction-touch-response.ts‎

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import type {
55
PressCommandResult,
66
} from '../../contracts/interaction.ts';
77
import { successText } from '../../utils/success-text.ts';
8+
import { STALE_SNAPSHOT_REFS_WARNING } from '../session-snapshot.ts';
89
import { interactionResultExtra, stripAtPrefix } from './interaction-touch-targets.ts';
910

1011
/**
@@ -55,6 +56,13 @@ export function buildInteractionResponseData(params: {
5556
* button tags for click, selector/maestro details for the direct path.
5657
*/
5758
extra?: Record<string, unknown>;
59+
/**
60+
* The command consumed an `@ref` argument while the session's stored
61+
* snapshot had been replaced without re-issuing refs to the client
62+
* (`session.snapshotRefsStale`, #1076). Appends
63+
* STALE_SNAPSHOT_REFS_WARNING to the response warning.
64+
*/
65+
staleRefs?: boolean;
5866
}): InteractionResponsePayloads {
5967
const { source, referenceFrame, extra } = params;
6068
if (source.kind === 'runner-payload') {
@@ -89,13 +97,27 @@ export function buildInteractionResponseData(params: {
8997
...interactionResultExtra(result),
9098
}
9199
: visualization;
92-
if ('warning' in result && result.warning) {
93-
visualization.warning = result.warning;
94-
responseData.warning = result.warning;
100+
const warning = composeResponseWarning(
101+
'warning' in result ? result.warning : undefined,
102+
params.staleRefs,
103+
);
104+
if (warning) {
105+
visualization.warning = warning;
106+
responseData.warning = warning;
95107
}
96108
return { result: visualization, responseData };
97109
}
98110

111+
function composeResponseWarning(
112+
resultWarning: string | undefined,
113+
staleRefs: boolean | undefined,
114+
): string | undefined {
115+
if (staleRefs !== true) return resultWarning;
116+
return resultWarning
117+
? `${resultWarning} ${STALE_SNAPSHOT_REFS_WARNING}`
118+
: STALE_SNAPSHOT_REFS_WARNING;
119+
}
120+
99121
function buildTouchVisualizationResult(params: {
100122
data: Record<string, unknown> | undefined;
101123
fallbackX?: number;

0 commit comments

Comments
 (0)