Skip to content

Commit f5a7e4c

Browse files
authored
test(contracts): prove the band forwarding and restore promotion coverage (#3971)
An independent review found that every test of the seam scripted a tree only, so match.keyboard was always undefined and the forwarding spread the guard prefers was proven nowhere: delete it and the suite stayed green. runnerSnapshotEntry now carries extra runner-result fields, and three scenarios close the gap, each red when its forwarding is deleted: - keyboardOcclusion (manifest): the producer band over a keyboardLifted tree, where the tree rule cannot measure and the refusal can only come from the forwarded fact. - promotion (plain title, not manifest-derived): the deleted hittable- ancestor scenario back as transcript evidence for the half of the nonHittable cell that does run; retargeting findAct.promotion fails it. - keyboardOcclusion forwarding (plain title): find click hands the same band to the acting leaf, pinning preresolvedTarget's #2660 claim. Also: the responseConstruction scenario now pins the payload key set instead of a vacuous refsGeneration check; the errorTaxonomy scenario exercises the ambiguous builder its cell names alongside the no-match arm; the registry says focus <x> <y> is a generic-route command no row classifies instead of calling it 'the coordinate route'; the coordinate disclosure unit cases drop as duplicates of the leaf door's, keeping the lifted-tree hoist with one owner in the shared fixture.
1 parent 5b61e8a commit f5a7e4c

6 files changed

Lines changed: 168 additions & 79 deletions

File tree

‎packages/contracts/src/interaction-guarantees.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -550,7 +550,7 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
550550
},
551551
'find-focus-dispatch': {
552552
description:
553-
'Mutating `find <locator> focus`, and the focus leg of `find <locator> type`: find captures its own tree, ranks its own candidate set, runs the node stages its `findAct` row declares, then dispatches a point focus itself (`type` then dispatches the text) instead of re-entering the interaction leaf. `find click`/`find fill` are NOT this path — they hand the resolved node to `runtime-ref` as a pre-resolved target (#1654). `focus <x> <y>` is the coordinate route. Every cell below classifies what the `findAct` row plus this seam actually run, not what the acting rows run.',
553+
'Mutating `find <locator> focus`, and the focus leg of `find <locator> type`: find captures its own tree, ranks its own candidate set, runs the node stages its `findAct` row declares, then dispatches a point focus itself (`type` then dispatches the text) instead of re-entering the interaction leaf. `find click`/`find fill` are NOT this path — they hand the resolved node to `runtime-ref` as a pre-resolved target (#1654). `focus <x> <y>` shares only `executeFocusPoint`; it is a generic-route command that never enters the interaction leaf and no row of this matrix classifies. Every cell below classifies what the `findAct` row plus this seam actually run, not what the acting rows run.',
554554
commands: ['find'],
555555
guarantees: {
556556
// find's own ranking, but under the same ambiguity contract the runtime paths use: one

‎packages/selectors/src/keyboard-occlusion.test.ts‎

Lines changed: 8 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -13,18 +13,16 @@ import {
1313
KEYBOARD_COVERED_TAB_BAR_RECT,
1414
keyboardCoveredTabBarSnapshot,
1515
} from '@agent-device/test-kit';
16-
import {
17-
assertTapTargetClearOfVisibleKeyboard,
18-
describeKeyboardOccludedPointWarning,
19-
} from './keyboard-occlusion.ts';
16+
import { assertTapTargetClearOfVisibleKeyboard } from './keyboard-occlusion.ts';
2017

21-
// The guard's own two contributions: the refusal it raises for a decision the classifier already
22-
// made, and the disclosure string it composes. Which geometry decides is the classifier's suite
23-
// (packages/contracts/src/tap-keyboard-occlusion.test.ts, golden-table-driven), and which doors run
24-
// the guard is proven where each door lives — the interaction leaf's in
25-
// src/commands/interaction/runtime/target-visibility-stages-keyboard-occlusion.test.ts, the
18+
// The guard's own contribution: the refusal it raises for a decision the classifier already made.
19+
// Which geometry decides is the classifier's suite (packages/contracts/src/tap-keyboard-occlusion.test.ts,
20+
// golden-table-driven), and which doors run the guard is proven where each door lives — the interaction
21+
// leaf's in src/commands/interaction/runtime/target-visibility-stages-keyboard-occlusion.test.ts, the
2622
// mutating-`find` seam's in packages/daemon/src/execution/interaction/internal/__tests__/. Every one
27-
// of those suites measures this same #2589 capture.
23+
// of those suites measures this same #2589 capture. The coordinate path's disclosure string is proven
24+
// through that leaf's production door (`describeKeyboardOccludedPointWarning` has exactly one caller),
25+
// so it is not repeated here.
2826

2927
function centerOf(rect: Rect): Point {
3028
return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
@@ -124,36 +122,3 @@ test('the refusal quotes how the caller named the target', () => {
124122
test('a target with no measurable point cannot be refused', () => {
125123
guard({ snapshot: keyboardCoveredTabBarSnapshot(), tapPoint: null });
126124
});
127-
128-
// The coordinate path discloses the same decision instead of refusing it, in one string the
129-
// response publishes.
130-
131-
function pointWarning(params: {
132-
snapshot: SnapshotState;
133-
point: Point;
134-
keyboard?: SnapshotKeyboardBandFact;
135-
}): string | undefined {
136-
return describeKeyboardOccludedPointWarning({
137-
nodes: params.snapshot.nodes,
138-
point: params.point,
139-
viewport: params.snapshot.nodes[0]!.rect ?? null,
140-
...(params.keyboard ? { keyboard: params.keyboard } : {}),
141-
});
142-
}
143-
144-
test('a coordinate behind the keyboard discloses the point, reason, and band', () => {
145-
const warning = pointWarning({
146-
snapshot: keyboardCoveredTabBarSnapshot(),
147-
point: { x: 200, y: 810 },
148-
});
149-
assert.match(warning ?? '', /\(200, 810\) is behind the visible keyboard/);
150-
assert.match(warning ?? '', /tap_keyboard_occludes_target/);
151-
assert.match(warning ?? '', /keyboard frame 583\.\.874/);
152-
});
153-
154-
test('a coordinate on a reported key discloses nothing', () => {
155-
assert.equal(
156-
pointWarning({ snapshot: keyboardCoveredTabBarSnapshot(), point: { x: 160, y: 760 } }),
157-
undefined,
158-
);
159-
});

‎src/commands/interaction/runtime/target-visibility-stages-keyboard-occlusion.test.ts‎

Lines changed: 15 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -31,15 +31,7 @@ function tappedDevice(snapshot: SnapshotState, calls: Point[]) {
3131
});
3232
}
3333

34-
/** The same tree with its keyboard hoisted above the docking budget, so the tree rule stops measuring. */
35-
function lifted(nodes: SnapshotState['nodes']): SnapshotState['nodes'] {
36-
return nodes.map((node) =>
37-
node.rect && (node.type === 'Keyboard' || node.type === 'Key')
38-
? { ...node, rect: { ...node.rect, y: node.rect.y - 560 } }
39-
: node,
40-
);
41-
}
42-
34+
/** One capture as the producer would hand it over: the tree, plus the band it measured when there is one. */
4335
function captured(params: {
4436
nodes: SnapshotState['nodes'];
4537
keyboard?: SnapshotKeyboardBandFact;
@@ -151,16 +143,16 @@ test('a coordinate behind the keyboard taps anyway and discloses the reason', as
151143
);
152144

153145
assert.deepEqual(calls, [{ x: 200, y: 810 }]);
154-
assert.match(result.warning ?? '', /behind the visible keyboard/);
146+
assert.match(result.warning ?? '', /\(200, 810\) is behind the visible keyboard/);
155147
assert.match(result.warning ?? '', /tap_keyboard_occludes_target/);
156148
});
157149

158150
test('the guard reads the point the interaction dispatches, not the rect center', async () => {
159151
// The Form button's own center sits 3 pt above the key plane, and its interactive child owns that
160152
// upper region, so the point the tap dispatches is pushed down into the keyboard's band.
161-
const aimShifted = makeSnapshotState(
153+
const aimShiftedTree = (base: SnapshotState['nodes']) =>
162154
[
163-
...keyboardCoveredTabBarSnapshot().nodes,
155+
...base,
164156
{
165157
index: 7,
166158
depth: 3,
@@ -172,8 +164,8 @@ test('the guard reads the point the interaction dispatches, not the rect center'
172164
},
173165
].map((node) =>
174166
node.index === 1 ? { ...node, rect: { x: 148, y: 500, width: 104, height: 160 } } : node,
175-
),
176-
);
167+
);
168+
const aimShifted = makeSnapshotState(aimShiftedTree(keyboardCoveredTabBarSnapshot().nodes));
177169

178170
const calls: Point[] = [];
179171
await assert.rejects(
@@ -182,13 +174,16 @@ test('the guard reads the point the interaction dispatches, not the rect center'
182174
);
183175
assert.deepEqual(calls, []);
184176

185-
// The same tree with its keyboard hauled off the bottom edge shows where that tap was aiming: below
186-
// the key plane, which is what makes this the dispatched point's refusal rather than the center's.
177+
// The same tree with its keyboard hauled off the bottom edge — via the shared fixture's lifted
178+
// variant, the one owner of that hoist — shows where that tap was aiming: below the key plane,
179+
// which is what makes this the dispatched point's refusal rather than the center's.
187180
const aim: Point[] = [];
188-
await tappedDevice(makeSnapshotState(lifted(aimShifted.nodes)), aim).interactions.click(
189-
ref('@e2'),
190-
{ session: 'default' },
191-
);
181+
await tappedDevice(
182+
makeSnapshotState(
183+
aimShiftedTree(keyboardCoveredTabBarSnapshot({ keyboardLifted: true }).nodes),
184+
),
185+
aim,
186+
).interactions.click(ref('@e2'), { session: 'default' });
192187
assert.equal(aim.length, 1);
193188
assert.ok((aim[0]?.y ?? 0) > 583, `expected the dispatched point below 583, got ${aim[0]?.y}`);
194189
});

‎test/integration/interaction-contract/daemon-harness.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -89,12 +89,15 @@ export async function withIosContractDaemon(
8989
);
9090
}
9191

92-
export function runnerSnapshotEntry(nodes: readonly unknown[]): ProviderScenarioProviderEntry {
92+
export function runnerSnapshotEntry(
93+
nodes: readonly unknown[],
94+
result: Record<string, unknown> = {},
95+
): ProviderScenarioProviderEntry {
9396
return {
9497
command: 'ios.runner.snapshot',
9598
deviceId: CONTRACT_DEVICE_ID,
9699
platform: 'apple',
97-
result: { nodes, truncated: false },
100+
result: { nodes, truncated: false, ...result },
98101
};
99102
}
100103

‎test/integration/interaction-contract/find-focus-dispatch.contract.test.ts‎

Lines changed: 138 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import assert from 'node:assert/strict';
22
import { test } from 'vitest';
33
import type { InteractionGuarantee } from '@agent-device/contracts/interaction-guarantees';
4-
import { keyboardCoveredTabBarSnapshot } from '@agent-device/test-kit';
4+
import { KEYBOARD_COVERED_BAND_RECT, keyboardCoveredTabBarSnapshot } from '@agent-device/test-kit';
55
import { assertRpcError, assertRpcOk } from '../provider-scenarios/assertions.ts';
66
import { PARALLEL_PROVIDER_SCENARIO_TIMEOUT_MS } from '../provider-scenarios/test-timeouts.ts';
77
import { scenarioName, scenarioNames } from './coverage-manifest.ts';
@@ -61,6 +61,39 @@ test(
6161
PARALLEL_PROVIDER_SCENARIO_TIMEOUT_MS,
6262
);
6363

64+
test(
65+
scenarioNames(FIND_FOCUS_DISPATCH_COVERAGE, 'keyboardOcclusion')[2]!,
66+
async () => {
67+
// The producer's band, scripted onto the capture, over a tree the tree-derived rule refuses to
68+
// measure (the keys are hoisted off the docking edge, which is what the iOS runner's projected
69+
// tree reports when the band comes from the runner's own keyboard probe). So the only source of
70+
// the refusal below is `match.keyboard` reaching the guard — delete the seam's forwarding and
71+
// this scenario dispatches into a transcript with no tap entry, which `assertComplete` fails.
72+
const liftedTree = keyboardCoveredTabBarSnapshot({ keyboardLifted: true }).nodes;
73+
74+
await withIosContractDaemon(
75+
[
76+
runnerSnapshotEntry(liftedTree, {
77+
keyboard: { kind: 'visible', frame: KEYBOARD_COVERED_BAND_RECT },
78+
}),
79+
],
80+
async (daemon) => {
81+
const error = assertRpcError(
82+
await daemon.callCommand('find', ['label', 'Form', 'focus']),
83+
500,
84+
'COMMAND_FAILED',
85+
/Ref @e2 is behind the visible keyboard and cannot be focused safely/,
86+
);
87+
const details = readErrorDetails(error);
88+
assert.equal(details.reason, 'tap_keyboard_occludes_target');
89+
assert.deepEqual(details.keyboardFrame, KEYBOARD_COVERED_BAND_RECT);
90+
assert.equal(details.dispatched, 'no');
91+
},
92+
);
93+
},
94+
PARALLEL_PROVIDER_SCENARIO_TIMEOUT_MS,
95+
);
96+
6497
test(
6598
scenario('occlusion'),
6699
async () => {
@@ -108,18 +141,40 @@ test(
108141
PARALLEL_PROVIDER_SCENARIO_TIMEOUT_MS,
109142
);
110143

144+
test(
145+
'find-focus-dispatch promotion: a non-hittable label retargets the dispatch to the hittable ancestor row',
146+
async () => {
147+
// Discriminating, not decorative: the label's own center is (140,195), the row's is (200,200).
148+
// Retargeting `findAct.promotion` away from `hittable-ancestor-below-root` dispatches at the
149+
// label and this fails. Title deliberately outside the coverage manifest: the promotion half runs
150+
// while the annotation half stays the `nonHittable` waiver's debt, and the gate forbids a
151+
// manifest entry on a waived cell.
152+
await withIosContractDaemon(
153+
[runnerSnapshotEntry(nonHittableRowTree()), runnerTapEntry({})],
154+
async (daemon) => {
155+
const data = assertRpcOk(
156+
await daemon.callCommand('find', ['label', 'Notifications', 'focus']),
157+
);
158+
assert.deepEqual({ x: data.x, y: data.y }, { x: 200, y: 200 });
159+
},
160+
);
161+
},
162+
PARALLEL_PROVIDER_SCENARIO_TIMEOUT_MS,
163+
);
164+
111165
test(
112166
scenario('responseConstruction'),
113167
async () => {
114168
await withIosContractDaemon(
115169
[runnerSnapshotEntry(KEYBOARD_TREE), runnerTapEntry({})],
116170
async (daemon) => {
117171
const data = assertRpcOk(await daemon.callCommand('find', ['label', 'space', 'focus']));
118-
// The focus runtime's own payload: the point it dispatched plus its success text, with nothing
119-
// hand-rolled on top — and no `refsGeneration`, which is what would make the ref pinnable
120-
// (ADR 0014).
172+
// The focus runtime's own payload, exactly: the point it dispatched plus its success text,
173+
// nothing hand-rolled on top and nothing pinnable — no `ref`/`refsGeneration` half of an
174+
// identity (ADR 0014 keeps mutating find's ref diagnostic-only, and the deleted fallback
175+
// means there is no `data.ref` at all to pin).
121176
assert.equal(data.message, 'Focused (202, 779)');
122-
assert.equal(data.refsGeneration, undefined);
177+
assert.deepEqual(Object.keys(data).sort(), ['message', 'x', 'y']);
123178
},
124179
);
125180
},
@@ -129,14 +184,63 @@ test(
129184
test(
130185
scenario('errorTaxonomy'),
131186
async () => {
132-
await withIosContractDaemon([runnerSnapshotEntry(KEYBOARD_TREE)], async (daemon) => {
133-
assertRpcError(
134-
await daemon.callCommand('find', ['label', 'Nowhere', 'focus']),
135-
500,
136-
'COMMAND_FAILED',
137-
/find did not match any element/,
138-
);
139-
});
187+
// Both arms of this route's failure taxonomy, refusing on one transcript with no tap entry:
188+
// the ambiguous refusal produced by the builder the `errorTaxonomy` cell names, and the
189+
// no-match refusal. A candidate-disclosure or message change here fails this scenario, which
190+
// is the cell's own evidence rather than the `disambiguation` scenario's.
191+
await withIosContractDaemon(
192+
[runnerSnapshotEntry(twinFormTree()), runnerSnapshotEntry(KEYBOARD_TREE)],
193+
async (daemon) => {
194+
const ambiguous = assertRpcError(
195+
await daemon.callCommand('find', ['label', 'Form', 'focus']),
196+
500,
197+
'AMBIGUOUS_MATCH',
198+
/find matched 2 elements for label "Form"/,
199+
);
200+
assert.deepEqual(readErrorDetails(ambiguous).candidates, [
201+
'@e2 [button] "Form"',
202+
'@e3 [button] "Form"',
203+
]);
204+
205+
assertRpcError(
206+
await daemon.callCommand('find', ['label', 'Nowhere', 'focus']),
207+
500,
208+
'COMMAND_FAILED',
209+
/find did not match any element/,
210+
);
211+
},
212+
);
213+
},
214+
PARALLEL_PROVIDER_SCENARIO_TIMEOUT_MS,
215+
);
216+
217+
test(
218+
'find-focus-dispatch keyboardOcclusion forwarding: find click hands the same band to the acting leaf',
219+
async () => {
220+
// `find click`/`fill` are not this row's path — they pre-resolve the node to `runtime-ref` — but
221+
// `preresolvedTarget`'s forwarding carries this capture's band to the leaf's guard, and the
222+
// comment there claims "the band this capture measured, not one it re-derives". Over a lifted
223+
// tree the refusal below can only come from that forwarded fact.
224+
const liftedTree = keyboardCoveredTabBarSnapshot({ keyboardLifted: true }).nodes;
225+
226+
await withIosContractDaemon(
227+
[
228+
runnerSnapshotEntry(liftedTree, {
229+
keyboard: { kind: 'visible', frame: KEYBOARD_COVERED_BAND_RECT },
230+
}),
231+
],
232+
async (daemon) => {
233+
const error = assertRpcError(
234+
await daemon.callCommand('find', ['label', 'Form', 'click']),
235+
500,
236+
'COMMAND_FAILED',
237+
/Ref @e2 is behind the visible keyboard and cannot be tapped safely/,
238+
);
239+
const details = readErrorDetails(error);
240+
assert.equal(details.reason, 'tap_keyboard_occludes_target');
241+
assert.deepEqual(details.keyboardFrame, KEYBOARD_COVERED_BAND_RECT);
242+
},
243+
);
140244
},
141245
PARALLEL_PROVIDER_SCENARIO_TIMEOUT_MS,
142246
);
@@ -148,6 +252,27 @@ function readErrorDetails(error: Record<string, unknown>): Record<string, unknow
148252
return details as Record<string, unknown>;
149253
}
150254

255+
function nonHittableRowTree(): unknown[] {
256+
return [
257+
{ index: 0, type: 'Application', rect: { x: 0, y: 0, width: 400, height: 800 } },
258+
{
259+
index: 1,
260+
parentIndex: 0,
261+
type: 'Cell',
262+
rect: { x: 40, y: 160, width: 320, height: 80 },
263+
hittable: true,
264+
},
265+
{
266+
index: 2,
267+
parentIndex: 1,
268+
type: 'StaticText',
269+
label: 'Notifications',
270+
rect: { x: 60, y: 180, width: 160, height: 30 },
271+
hittable: false,
272+
},
273+
];
274+
}
275+
151276
function coveredFormTree(): unknown[] {
152277
return [
153278
{ index: 0, type: 'Application', rect: { x: 0, y: 0, width: 390, height: 844 } },

‎test/integration/interaction-contract/find-focus-dispatch.coverage.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ export const FIND_FOCUS_DISPATCH_COVERAGE = definePathCoverage('find-focus-dispa
77
keyboardOcclusion: [
88
'find-focus-dispatch keyboardOcclusion: a focus match behind the visible keyboard is refused with tap_keyboard_occludes_target',
99
'find-focus-dispatch keyboardOcclusion: the same match above the keyboard band focuses',
10+
'find-focus-dispatch keyboardOcclusion: a producer-measured band refuses the match even when the captured tree cannot derive one',
1011
],
1112
responseConstruction:
1213
'find-focus-dispatch responseConstruction: find focus returns the shared point-focus payload',

0 commit comments

Comments
 (0)