|
| 1 | +import assert from 'node:assert/strict'; |
| 2 | +import { readFileSync } from 'node:fs'; |
| 3 | +import path from 'node:path'; |
| 4 | +import { test } from 'vitest'; |
| 5 | +import { |
| 6 | + SELECTOR_RESOLUTION_POLICIES, |
| 7 | + selectorResolutionKnobs, |
| 8 | + type SelectorResolutionPolicy, |
| 9 | +} from '@agent-device/selectors'; |
| 10 | + |
| 11 | +/** |
| 12 | + * The matrix in resolution-policy.ts is a claim about the callers, so it is |
| 13 | + * gate-tested against them rather than trusted (ADR 0011's declared-plus- |
| 14 | + * gate-tested pattern). Two failure modes this catches: a policy row whose |
| 15 | + * knobs stop matching the ambiguity contract it names, and a structural |
| 16 | + * column (occlusion / off-screen / promotion / poll) drifting into fiction |
| 17 | + * because a caller stopped importing the machinery the row advertises. |
| 18 | + */ |
| 19 | + |
| 20 | +const REPO_SRC = path.resolve(import.meta.dirname, '../../../..'); |
| 21 | + |
| 22 | +function readSource(relative: string): string { |
| 23 | + return readFileSync(path.join(REPO_SRC, relative), 'utf8'); |
| 24 | +} |
| 25 | + |
| 26 | +const CALLERS = { |
| 27 | + act: 'commands/interaction/runtime/resolution.ts', |
| 28 | + actCoveredDiagnosis: 'commands/interaction/runtime/resolution.ts', |
| 29 | + readText: 'commands/interaction/runtime/selector-read.ts', |
| 30 | + readUnique: 'commands/interaction/runtime/selector-read.ts', |
| 31 | + readAny: 'commands/interaction/runtime/selector-read.ts', |
| 32 | + wait: 'commands/interaction/runtime/selector-wait.ts', |
| 33 | + findAct: 'daemon/handlers/find.ts', |
| 34 | +} as const satisfies Record<keyof typeof SELECTOR_RESOLUTION_POLICIES, string>; |
| 35 | + |
| 36 | +// What each structural column means in caller source, so the claim is |
| 37 | +// checkable rather than decorative. |
| 38 | +const OCCLUSION_MARKERS = ['isSnapshotNodeInteractionBlocked', 'interactableSelectorNodes']; |
| 39 | +const OFFSCREEN_MARKERS = ['throwIfOffscreenInteractionTarget', 'assertVisibleSelectorTarget']; |
| 40 | +const PROMOTION_MARKERS = ['resolveActionableTouchNode', 'resolveActionableNodeOrThrow']; |
| 41 | +const POLL_MARKERS = ['createWaitPolling']; |
| 42 | + |
| 43 | +function mentionsAny(source: string, markers: readonly string[]): boolean { |
| 44 | + return markers.some((marker) => source.includes(marker)); |
| 45 | +} |
| 46 | + |
| 47 | +test('every policy row names a real caller', () => { |
| 48 | + assert.deepEqual(Object.keys(SELECTOR_RESOLUTION_POLICIES).sort(), Object.keys(CALLERS).sort()); |
| 49 | +}); |
| 50 | + |
| 51 | +test('knobs match the ambiguity contract each row names', () => { |
| 52 | + const expected: Record<string, ReturnType<typeof selectorResolutionKnobs>> = { |
| 53 | + disambiguate: { requireRect: false, requireUnique: true, disambiguateAmbiguous: true }, |
| 54 | + 'fail-closed': { requireRect: false, requireUnique: true, disambiguateAmbiguous: false }, |
| 55 | + 'first-match': { requireRect: false, requireUnique: false }, |
| 56 | + }; |
| 57 | + for (const [name, policy] of Object.entries(SELECTOR_RESOLUTION_POLICIES)) { |
| 58 | + if (policy.ambiguity === 'reject-candidates') continue; |
| 59 | + const knobs = selectorResolutionKnobs(policy); |
| 60 | + const want = { ...expected[policy.ambiguity], requireRect: policy.requireRect }; |
| 61 | + assert.deepEqual(knobs, want, name); |
| 62 | + } |
| 63 | +}); |
| 64 | + |
| 65 | +test('acting policies require a rect; read and wait policies do not', () => { |
| 66 | + assert.equal(SELECTOR_RESOLUTION_POLICIES.act.requireRect, true); |
| 67 | + assert.equal(SELECTOR_RESOLUTION_POLICIES.findAct.requireRect, true); |
| 68 | + assert.equal(SELECTOR_RESOLUTION_POLICIES.readUnique.requireRect, false); |
| 69 | + assert.equal(SELECTOR_RESOLUTION_POLICIES.readAny.requireRect, false); |
| 70 | + assert.equal(SELECTOR_RESOLUTION_POLICIES.wait.requireRect, false); |
| 71 | +}); |
| 72 | + |
| 73 | +test('is/get-attrs fail closed and wait never disambiguates (the by-design asymmetry)', () => { |
| 74 | + assert.equal(SELECTOR_RESOLUTION_POLICIES.readUnique.ambiguity, 'fail-closed'); |
| 75 | + assert.equal(SELECTOR_RESOLUTION_POLICIES.readAny.ambiguity, 'first-match'); |
| 76 | + assert.equal(SELECTOR_RESOLUTION_POLICIES.wait.ambiguity, 'first-match'); |
| 77 | + assert.equal(SELECTOR_RESOLUTION_POLICIES.act.ambiguity, 'disambiguate'); |
| 78 | + assert.equal(SELECTOR_RESOLUTION_POLICIES.readText.ambiguity, 'disambiguate'); |
| 79 | + assert.equal(SELECTOR_RESOLUTION_POLICIES.findAct.ambiguity, 'reject-candidates'); |
| 80 | +}); |
| 81 | + |
| 82 | +test('structural columns match what each caller actually imports', () => { |
| 83 | + const sources = new Map<string, string>(); |
| 84 | + for (const relative of Object.values(CALLERS)) { |
| 85 | + if (!sources.has(relative)) sources.set(relative, readSource(relative)); |
| 86 | + } |
| 87 | + for (const [name, relative] of Object.entries(CALLERS)) { |
| 88 | + const policy: SelectorResolutionPolicy = |
| 89 | + SELECTOR_RESOLUTION_POLICIES[name as keyof typeof SELECTOR_RESOLUTION_POLICIES]; |
| 90 | + const source = sources.get(relative)!; |
| 91 | + if (policy.occlusion) { |
| 92 | + assert.ok(mentionsAny(source, OCCLUSION_MARKERS), `${name} claims occlusion`); |
| 93 | + } |
| 94 | + if (policy.offscreenGuard) { |
| 95 | + assert.ok(mentionsAny(source, OFFSCREEN_MARKERS), `${name} claims an off-screen guard`); |
| 96 | + } |
| 97 | + if (policy.promotion) { |
| 98 | + assert.ok(mentionsAny(source, PROMOTION_MARKERS), `${name} claims promotion`); |
| 99 | + } |
| 100 | + if (policy.poll === 'wait-budget') { |
| 101 | + assert.ok(mentionsAny(source, POLL_MARKERS), `${name} claims a poll budget`); |
| 102 | + } |
| 103 | + } |
| 104 | +}); |
| 105 | + |
| 106 | +test('read and wait pipelines really do skip occlusion, off-screen, and promotion', () => { |
| 107 | + // The inverse direction: a row claiming NO occlusion must not sit in a file |
| 108 | + // that performs it, or the matrix would under-report real behavior. |
| 109 | + const readSourceText = readSource(CALLERS.readUnique); |
| 110 | + const waitSource = readSource(CALLERS.wait); |
| 111 | + for (const [name, source] of [ |
| 112 | + ['selector-read', readSourceText], |
| 113 | + ['selector-wait', waitSource], |
| 114 | + ] as const) { |
| 115 | + assert.equal(mentionsAny(source, OCCLUSION_MARKERS), false, `${name} occlusion`); |
| 116 | + assert.equal(mentionsAny(source, OFFSCREEN_MARKERS), false, `${name} off-screen`); |
| 117 | + assert.equal(mentionsAny(source, PROMOTION_MARKERS), false, `${name} promotion`); |
| 118 | + } |
| 119 | +}); |
| 120 | + |
| 121 | +test('no caller re-declares ambiguity knobs as inline literals', () => { |
| 122 | + for (const relative of new Set(Object.values(CALLERS))) { |
| 123 | + const source = readSource(relative); |
| 124 | + assert.equal( |
| 125 | + /disambiguateAmbiguous:\s*(true|false)/.test(source), |
| 126 | + false, |
| 127 | + `${relative} declares disambiguateAmbiguous inline`, |
| 128 | + ); |
| 129 | + assert.equal( |
| 130 | + /requireUnique:\s*(true|false)/.test(source), |
| 131 | + false, |
| 132 | + `${relative} declares requireUnique inline`, |
| 133 | + ); |
| 134 | + } |
| 135 | +}); |
0 commit comments