Skip to content

Commit 82b623d

Browse files
committed
fix(ios): derive a served surface identity at the one stamping point
A runner fallback's comparison identity was decided per call site. The `present` path and the off-route path read the runner's `systemSurface` stamp, but the plain `runFallback` path did not: it stamped the app lineage the route had planned, whatever the runner returned. The probe and the capture are separate observations, so a sheet can appear in the gap between them. With the bridge circuit already disabled for the generation, an app capture and a later sheet capture both received the same app-generation key, so tap corroboration could treat two different surfaces as comparable. `stampFallback` now owns the decision for every runner fallback: the surface the runner served outranks the app lineage the route planned. The reason the bridge was skipped survives either way, and app-generation evidence leaves with the app lineage it describes, so two captures of the same sheet still compare equal. `runSurfaceFallback` keeps only the reason, which is the one thing that path decides.
1 parent 28c6e86 commit 82b623d

2 files changed

Lines changed: 135 additions & 26 deletions

File tree

‎packages/platform-apple/src/snapshot-route.test.ts‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,77 @@ test('a lingering probe cannot make a sheet capture and an app capture compare e
146146
]);
147147
});
148148

149+
// The probe is a separate observation from the capture, so a sheet can appear in the gap between
150+
// them. With the bridge circuit already disabled for this generation the route takes the plain
151+
// fallback, which used to stamp the planned app lineage onto whatever came back — so the sheet
152+
// capture carried the app generation and could corroborate a tap against an app capture (#2438).
153+
test('a sheet that appears after an absent probe is identified by the surface, not the app', async () => {
154+
const route = createAppleSnapshotRoute(platformRuntimeHostFixture(), {
155+
source: sourceReturning({
156+
stage: 'failed',
157+
failure: { kind: 'transport-failure', code: 'bridge-disconnected' },
158+
}),
159+
resolveTarget: vi.fn(async () => target),
160+
systemSurfacePresent: async () => 'absent',
161+
});
162+
163+
// The first capture disables the circuit for this generation; both later captures take the
164+
// `circuit-disabled` path, where the route plans nothing about a surface.
165+
const app = await route.capture(ios, input, signal(), async () => runnerResult());
166+
const sheet = await route.capture(ios, input, signal(), async () => surfaceRunnerResult());
167+
const sheetAgain = await route.capture(ios, input, signal(), async () => surfaceRunnerResult());
168+
169+
expect(sheet.comparisonIdentity).toMatchObject({
170+
producer: 'apple-runner',
171+
lineage: { targetId: `${ios.id}:${presentSurface.host.bundleId}` },
172+
residue: [{ kind: 'fallback-source', producer: 'apple-runner' }],
173+
});
174+
expect(app.comparisonIdentity?.lineage).toEqual({
175+
targetId: target.targetId,
176+
generation: target.generation,
177+
});
178+
expect(
179+
areIosSnapshotComparisonIdentitiesEqual(app.comparisonIdentity!, sheet.comparisonIdentity!),
180+
).toBe(false);
181+
// Two captures of the same sheet still compare equal, so a poll can settle on the sheet.
182+
expect(
183+
areIosSnapshotComparisonIdentitiesEqual(
184+
sheet.comparisonIdentity!,
185+
sheetAgain.comparisonIdentity!,
186+
),
187+
).toBe(true);
188+
// The reason the bridge was skipped survives — it is independent of what the runner found — but
189+
// the sentence cannot claim an app generation this capture did not read.
190+
expect(sheet.warnings).toEqual([
191+
'Simulator AX snapshot unavailable (circuit-disabled); used XCTest, which read the system surface presented over the app.',
192+
]);
193+
});
194+
195+
// Same gap, reached through the probe-unavailable arm: that arm adds a per-capture
196+
// `unknown-generation` residue for an app capture, and app-generation evidence must not ride along
197+
// on a capture of a surface — it would make two captures of the same sheet incomparable too.
198+
test('a surface capture drops the app-generation residue of the arm that reached it', async () => {
199+
const route = createAppleSnapshotRoute(platformRuntimeHostFixture(), {
200+
source: sourceReturning(bridgeAcquisition()),
201+
resolveTarget: vi.fn(async () => target),
202+
systemSurfacePresent: async () => 'unknown',
203+
});
204+
205+
const sheet = await route.capture(ios, input, signal(), async () => surfaceRunnerResult());
206+
const sheetAgain = await route.capture(ios, input, signal(), async () => surfaceRunnerResult());
207+
208+
expect(sheet.comparisonIdentity).toMatchObject({
209+
lineage: { targetId: `${ios.id}:${presentSurface.host.bundleId}` },
210+
residue: [{ kind: 'fallback-source', producer: 'apple-runner' }],
211+
});
212+
expect(
213+
areIosSnapshotComparisonIdentitiesEqual(
214+
sheet.comparisonIdentity!,
215+
sheetAgain.comparisonIdentity!,
216+
),
217+
).toBe(true);
218+
});
219+
149220
// A pinned backend and a custom-actions read bypass the route's planning, but they still reach the
150221
// runner, and the runner serves the sheet there too. Without an identity that pair falls back to
151222
// legacy presentation matching, where a sheet and app content read as one presentation and could

‎packages/platform-apple/src/snapshot-route.ts‎

Lines changed: 64 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -108,9 +108,10 @@ export function createAppleSnapshotRoute(
108108
// answer confidently from the occluded app tree — but say so: silently losing the bridge
109109
// fast path, with no warning and a comparable identity, would be its own defect.
110110
return await runFallback(
111+
device.id,
111112
input,
112113
fallback,
113-
{ targetId: `${device.id}:${input.options!.appBundleId!}` },
114+
appLineage(device.id, input),
114115
requestFor(input),
115116
'system-surface-probe-unavailable',
116117
[unknownGenerationResidue()],
@@ -126,16 +127,24 @@ export function createAppleSnapshotRoute(
126127
signal.throwIfAborted();
127128
emitRouteDiagnostic('target-resolution-failed', device, undefined, error);
128129
return await runFallback(
130+
device.id,
129131
input,
130132
fallback,
131-
{ targetId: `${device.id}:${input.options!.appBundleId!}` },
133+
appLineage(device.id, input),
132134
requestFor(input),
133135
'target-resolution-failed',
134136
[unknownGenerationResidue()],
135137
);
136138
}
137139
if (isBridgeDisabled(target)) {
138-
return await runFallback(input, fallback, target, requestFor(input), 'circuit-disabled');
140+
return await runFallback(
141+
device.id,
142+
input,
143+
fallback,
144+
target,
145+
requestFor(input),
146+
'circuit-disabled',
147+
);
139148
}
140149

141150
const request = requestFor(input);
@@ -258,6 +267,7 @@ async function fallbackAfterFailure(
258267
failure.details,
259268
);
260269
return await runFallback(
270+
failedTarget.udid,
261271
input,
262272
fallback,
263273
identity.lineage,
@@ -268,23 +278,24 @@ async function fallbackAfterFailure(
268278
}
269279

270280
async function runFallback(
281+
deviceId: string,
271282
input: CaptureSnapshotInput,
272283
fallback: SnapshotFallback,
273284
lineage: IosSnapshotLineage,
274285
request: ReturnType<typeof createIosSnapshotRequest>,
275286
reason: string,
276287
residue: readonly IosAcquisitionResidue[] = [],
277288
): Promise<SnapshotResult> {
278-
return stampFallback(await fallback(input), lineage, request, reason, residue);
289+
return stampFallback(deviceId, await fallback(input), lineage, request, reason, residue);
279290
}
280291

281292
/**
282-
* The `present` path's capture, identified by what the runner actually served rather than by what
283-
* the probe predicted. The probe answers about a host PROCESS and stays positive while a dismissed
284-
* host lingers, while the runner answers about the screen and stamps the surface it served onto the
285-
* capture — so the capture is the authority. Reading the probe here instead would lineage an app
286-
* capture to the host, and the sheet capture before a dismissal would compare EQUAL to the app
287-
* capture after it, which is exactly the transition a post-gesture poll must not miss (#2438).
293+
* The `present` path's capture. The probe answers about a host PROCESS and stays positive while a
294+
* dismissed host lingers, while the runner answers about the screen — so only the reason is decided
295+
* here, from what the runner served. The identity comes from the shared stamping point, which reads
296+
* the same stamp: if the probe decided identity instead, an app capture taken in the lingering
297+
* window would be lineaged to the host and compare EQUAL to the sheet capture before the dismissal,
298+
* which is exactly the transition a post-gesture poll must not miss (#2438).
288299
*
289300
* `detectedHost` is therefore evidence, not identity: it names the host the probe matched so a
290301
* lingering window is legible in the daemon log instead of looking like a missing bridge capture.
@@ -296,15 +307,11 @@ async function runSurfaceFallback(
296307
detectedHost: string,
297308
): Promise<SnapshotResult> {
298309
const result = await fallback(input);
299-
const served = result.systemSurface;
300-
const reason = served ? SYSTEM_SURFACE_PRESENTED : SYSTEM_SURFACE_HOST_LINGERING;
301-
if (!served) emitRouteDiagnostic(reason, device, undefined, undefined, { detectedHost });
302-
return stampFallback(
303-
result,
304-
{ targetId: `${device.id}:${served?.bundleId ?? input.options!.appBundleId!}` },
305-
requestFor(input),
306-
reason,
307-
);
310+
const reason = result.systemSurface ? SYSTEM_SURFACE_PRESENTED : SYSTEM_SURFACE_HOST_LINGERING;
311+
if (!result.systemSurface) {
312+
emitRouteDiagnostic(reason, device, undefined, undefined, { detectedHost });
313+
}
314+
return stampFallback(device.id, result, appLineage(device.id, input), requestFor(input), reason);
308315
}
309316

310317
/**
@@ -327,30 +334,55 @@ async function captureOffRoute(
327334
return {
328335
...result,
329336
comparisonIdentity: runnerComparisonIdentity(
330-
{ targetId: `${device.id}:${served.bundleId}` },
337+
surfaceLineage(device.id, served.bundleId),
331338
requestFor(input),
332339
[],
333340
),
334341
};
335342
}
336343

344+
/**
345+
* The one place a runner fallback's identity is decided. The runner stamps the surface it actually
346+
* served onto its result, and that stamp is the authority over the app lineage the route planned:
347+
* a capture OF a system surface is identified by that surface whatever reason sent the route here.
348+
* Deriving this per call site is what let `circuit-disabled` stamp app lineage onto a sheet capture,
349+
* so a sheet and the app could compare equal and corroborate a tap across the two (#2438).
350+
*
351+
* `reason` survives either way — why the bridge was skipped is independent of what the runner found.
352+
* App-generation evidence leaves with the app lineage it describes: a surface is not an app
353+
* generation, and a per-capture residue id would make two captures of the same sheet incomparable
354+
* with each other too.
355+
*/
337356
function stampFallback(
357+
deviceId: string,
338358
result: SnapshotResult,
339359
lineage: IosSnapshotLineage,
340360
request: ReturnType<typeof createIosSnapshotRequest>,
341361
reason: string,
342362
residue: readonly IosAcquisitionResidue[] = [],
343363
): SnapshotResult {
364+
const served = result.systemSurface;
344365
return {
345366
...result,
346-
comparisonIdentity: runnerComparisonIdentity(lineage, request, [
347-
...residue,
348-
{ kind: 'fallback-source', producer: 'apple-runner' },
349-
]),
350-
warnings: [...(result.warnings ?? []), fallbackWarning(reason, lineage)],
367+
comparisonIdentity: runnerComparisonIdentity(
368+
served ? surfaceLineage(deviceId, served.bundleId) : lineage,
369+
request,
370+
[...(served ? [] : residue), { kind: 'fallback-source', producer: 'apple-runner' }],
371+
),
372+
warnings: [...(result.warnings ?? []), fallbackWarning(reason, lineage, served !== undefined)],
351373
};
352374
}
353375

376+
/** The app generation the route planned this capture against. */
377+
function appLineage(deviceId: string, input: CaptureSnapshotInput): IosSnapshotLineage {
378+
return { targetId: `${deviceId}:${input.options!.appBundleId!}` };
379+
}
380+
381+
/** A served system surface, which is identified by the surface host and by no app generation. */
382+
function surfaceLineage(deviceId: string, bundleId: string): IosSnapshotLineage {
383+
return { targetId: `${deviceId}:${bundleId}` };
384+
}
385+
354386
function runnerComparisonIdentity(
355387
lineage: IosSnapshotLineage,
356388
request: ReturnType<typeof createIosSnapshotRequest>,
@@ -375,13 +407,19 @@ function runnerComparisonIdentity(
375407
* did not serve, so that sentence says what the capture holds instead. Every other reason keeps the
376408
* unavailable sentence.
377409
*/
378-
function fallbackWarning(reason: string, lineage: IosSnapshotLineage): string {
410+
function fallbackWarning(reason: string, lineage: IosSnapshotLineage, served: boolean): string {
379411
if (reason === SYSTEM_SURFACE_PRESENTED) {
380412
return `Simulator AX snapshot inapplicable (${reason}); used XCTest to read the system surface presented over the app.`;
381413
}
382414
if (reason === SYSTEM_SURFACE_HOST_LINGERING) {
383415
return `Simulator AX snapshot inapplicable (${reason}); used XCTest, which read app content: the system surface host process was still running but no longer presenting.`;
384416
}
417+
// The bridge was skipped for its own reason and the runner then found a surface over the app. The
418+
// app-generation sentence would describe a capture this is not, so the reason keeps its wording
419+
// and the content sentence says what arrived.
420+
if (served) {
421+
return `Simulator AX snapshot unavailable (${reason}); used XCTest, which read the system surface presented over the app.`;
422+
}
385423
const generation = lineage.generation ? 'this app generation' : 'an unverified app generation';
386424
return `Simulator AX snapshot unavailable (${reason}); used XCTest for ${generation}.`;
387425
}

0 commit comments

Comments
 (0)