Skip to content

Commit 8c966f3

Browse files
authored
test(daemon): pin the acting route's own ambiguity issuance (ADR 0014 follow-up to #3340) (#3347)
* test(daemon): pin the acting route's own ambiguity issuance; narrow the rule's docblock The review's two follow-ups, both confirmed at c6acd1e: 1) The acting seam had no test of its own. Deleting the touch runtime's consumed-capture slot degraded every press/fill ambiguity to count-only with no test red -- the existing press test pressed an is-minted ref, traveling the selector-route seam. An ambiguous label= press through handleInteractionCommands now asserts its OWN refusal carries refsGeneration and a refFrameScope equal to the printed candidate bodies. Mutation-checked: removing the slot fills makes exactly this test fail. 2) The rule's docblock claimed every AMBIGUOUS_MATCH producer runs through the helper; find's refusal (buildAmbiguousMatchError, #1597) prints candidates without issuing them and never called it. Narrowed to the routes that consume the rule, with the find shape named and its contract stated: it prints no refsGeneration and its hint routes the caller to narrow the locator, so it advertises no issued-ref affordance. Routing find through the rule would make its candidates issuable -- a separate contract change, left to the maintainer. * docs(daemon): state find's missing generation pin, not an affordance claim The review nit was right that the old phrasing leaned on an inference ("advertises no issued-ref affordance") that a reader could overread as "find's candidates cannot be acted on" -- they are printed as ordinary snapshot lines, and a plain ref against an unrelated complete frame is a pre-existing admission the rule does not govern. The builder's own message ("Use a more specific locator or selector.") and absent refsGeneration remain the facts; state those directly and defer the issuance question as the contract decision it is.
1 parent c7b534f commit 8c966f3

2 files changed

Lines changed: 94 additions & 10 deletions

File tree

‎src/daemon/__tests__/selector-runtime-ambiguity-issuance.test.ts‎

Lines changed: 84 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,10 @@ import { handleInteractionCommands } from '../interaction/index.ts';
2626
// resolving against the earlier tree, where the same body names a different
2727
// node. The candidate either acts on the listed node or is refused.
2828

29-
const { mockRunAppleRunnerCommand } = vi.hoisted(() => ({ mockRunAppleRunnerCommand: vi.fn() }));
29+
const { mockRunAppleRunnerCommand, mockCaptureSnapshotWithInteractor } = vi.hoisted(() => ({
30+
mockRunAppleRunnerCommand: vi.fn(),
31+
mockCaptureSnapshotWithInteractor: vi.fn(),
32+
}));
3033

3134
vi.mock('@agent-device/platform-android/mechanics', async (importOriginal) => {
3235
const actual = await importOriginal<typeof import('@agent-device/platform-android/mechanics')>();
@@ -38,9 +41,10 @@ vi.mock('@agent-device/platform-android/mechanics', async (importOriginal) => {
3841
};
3942
});
4043

41-
vi.mock('../snapshot-interactor-capture.ts', () => ({
42-
captureSnapshotWithInteractor: vi.fn(),
43-
}));
44+
vi.mock('../snapshot-interactor-capture.ts', async (importOriginal) => {
45+
const actual = await importOriginal<typeof import('../snapshot-interactor-capture.ts')>();
46+
return { ...actual, captureSnapshotWithInteractor: mockCaptureSnapshotWithInteractor };
47+
});
4448

4549
vi.mock('@agent-device/platform-apple/runner/operations', async (importOriginal) => {
4650
const actual =
@@ -52,6 +56,7 @@ beforeEach(() => {
5256
resetGetRuntimeFixture();
5357
mockRunAppleRunnerCommand.mockReset();
5458
mockRunAppleRunnerCommand.mockResolvedValue({});
59+
mockCaptureSnapshotWithInteractor.mockReset();
5560
});
5661

5762
function isRequest(session: string, positionals: readonly string[]): DaemonRequest {
@@ -233,3 +238,78 @@ test('an ambiguous is on a sparse capture prints no candidates and issues nothin
233238
expect(session.snapshot!.nodes).toBe(storedNodes);
234239
expect(refFrameScope(session)).toBe('all');
235240
});
241+
242+
/**
243+
* The acting route's own coverage of the issuance rule: an ambiguous
244+
* `press` (never an `is`-minted ref) must ITSELF issue the candidates it
245+
* prints. Deleting the touch runtime's consumed-capture slot would silently
246+
* degrade every press/fill ambiguity to count-only if nothing pinned this;
247+
* the `is` tests above travel the selector-route seam, not this one.
248+
*/
249+
test('an ambiguous press issues its printed candidates from its own capture', async () => {
250+
const sessionStore = makeSessionStore();
251+
const sessionName = 'press-ambiguity-issuance';
252+
const session = makeStaleRefSession(sessionName);
253+
session.device = IOS_SIMULATOR;
254+
sessionStore.publish(sessionName, session);
255+
256+
// The press's own capture: two same-label buttons in DISTINCT branches, so
257+
// the acting pipeline's candidate classification refuses to collapse them
258+
// and throws AMBIGUOUS_MATCH with candidate lines. Raw nodes: the capture
259+
// path attaches refs itself (e1 root, e2/e3 the buttons).
260+
mockCaptureSnapshotWithInteractor.mockResolvedValue({
261+
nodes: [
262+
{ index: 0, type: 'Application', rect: { x: 0, y: 0, width: 390, height: 844 } },
263+
{
264+
index: 1,
265+
parentIndex: 0,
266+
type: 'XCUIElementTypeButton',
267+
label: 'Deploy',
268+
rect: { x: 300, y: 300, width: 20, height: 20 },
269+
enabled: true,
270+
hittable: true,
271+
},
272+
{
273+
index: 2,
274+
parentIndex: 0,
275+
type: 'XCUIElementTypeButton',
276+
label: 'Deploy',
277+
rect: { x: 500, y: 500, width: 20, height: 20 },
278+
enabled: true,
279+
hittable: true,
280+
},
281+
],
282+
backend: 'xctest',
283+
producer: 'apple-runner',
284+
});
285+
286+
const response = await handleInteractionCommands({
287+
req: {
288+
token: 't',
289+
session: sessionName,
290+
command: 'press',
291+
positionals: ['label="Deploy"'],
292+
flags: {},
293+
},
294+
sessionName,
295+
sessionStore,
296+
contextFromFlags,
297+
...getRuntimeBindings(),
298+
});
299+
300+
expect(response?.ok).toBe(false);
301+
if (!response || response.ok) throw new Error('expected the acting ambiguity refusal');
302+
expect(response.error.code).toBe('AMBIGUOUS_MATCH');
303+
// The acting refusal owes the same contract the read refusal gives: the
304+
// printed candidates are ISSUED refs pinned to the generation of the
305+
// capture the press itself consumed, not a count-only degradation.
306+
const refsGeneration = response.error.details?.refsGeneration as number;
307+
expect(typeof refsGeneration).toBe('number');
308+
const candidates = response.error.details?.candidates as string[];
309+
expect(candidates.length).toBeGreaterThan(0);
310+
expect([...refFrameScope(session)].sort()).toEqual(
311+
candidates.map((line) => /^@(e\d+)/.exec(line)![1]),
312+
);
313+
// Nothing was tapped: the refusal preceded dispatch.
314+
expect(mockTapPoint).not.toHaveBeenCalled();
315+
});

‎src/daemon/session-snapshot.ts‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -140,12 +140,16 @@ export function issueSettleRefs(
140140
/**
141141
* ADR 0014's issuance rule for ambiguity refusals: a response that prints
142142
* candidate `@ref`s must be able to ISSUE them, and issuance is only ever
143-
* valid against the tree the session's generation describes. Every route
144-
* that can answer `AMBIGUOUS_MATCH` with candidates runs its error through
145-
* here — the acting touch runtime (`press`/`click`/`fill`) and the strict-read
146-
* dispatches (`is`, `get attrs`) — so the rule has
147-
* one implementation beside the partial-frame primitive it wraps, exactly
148-
* like {@link issueSettleRefs}.
143+
* valid against the tree the session's generation describes. The routes that
144+
* owe that contract run their error through here — the acting touch runtime
145+
* (`press`/`click`/`fill`) and the strict-read dispatches (`is`, `get attrs`)
146+
* — so the rule has one implementation beside the partial-frame primitive it
147+
* wraps, exactly like {@link issueSettleRefs}. The `find` refusal
148+
* (`buildAmbiguousMatchError`) deliberately does NOT consume this rule: it
149+
* predates it (#1597), prints no `refsGeneration`, and its hint routes the
150+
* caller to narrow the locator; unlike this rule, it does not pin the printed
151+
* candidate refs to a generation. Making those refs issuable is a separate
152+
* contract decision.
149153
*
150154
* The two branches are one decision, not two features:
151155
* - The request's consumed capture IS the session's stored tree (node

0 commit comments

Comments
 (0)