Skip to content

Commit 033e55d

Browse files
authored
feat(selectors): export listSelectorChainMatches from agent-device/selectors (#3192)
* feat(selectors): publish listSelectorChainMatches on agent-device/selectors A consumer that needs every node a selector chain matches — to apply its own strictness — gets the same matched-node domain the resolver decided over instead of reimplementing term matching. The function already existed internally; it now leaves through the published AST surface with a public-facing contract doc that names the one way it differs from resolveSelectorChain: that function's default requireUnique refusal can walk past the alternative this one reports. The public-entry test pins the contract through the published module: several matches from one alternative in snapshot-array order (with index order made to disagree), first-alternative selection where find agrees and a uniqueness-refusing resolve does not, requireRect removing candidates before alternative selection, empty chain, and the term semantics the consumer copy drifted on (hittable, text, role, editable, and both visibility arms). * chore(gates): record listSelectorChainMatches in the public API surface The client-api.md subpath manifest and the packed-package selectors smoke check are the two records that a published subpath symbol exists; both name the new list entry so the exports surface cannot drift from the build. The doc also states the two facts a strictness-applying consumer must not guess: the list is null when nothing matches, and resolveSelectorChain can name a later alternative than the one listed.
1 parent ba1d32b commit 033e55d

6 files changed

Lines changed: 305 additions & 12 deletions

File tree

‎packages/selectors/src/ast.ts‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,11 @@
1111
//
1212
// So the AST stays exported, through one named subpath instead of being
1313
// reachable from anywhere: `src/sdk/selectors.ts` is its only consumer, and
14-
// `facade-symbols.ts` pins this list to exactly what v0.20.5 shipped. Widening
15-
// it means widening the public package, and the gate makes that a deliberate
16-
// edit rather than a side effect.
14+
// that file's explicit export list is the pin (the `facade-symbols.ts` table
15+
// #1574 added to hold it was retired in #1614, once every façade named its
16+
// exports itself). Nothing binds this list to `website/docs/docs/client-api.md`
17+
// by gate, so widening it is a deliberate edit whose convention is to record
18+
// the new name in that published API surface too.
1719
import type { SelectorChain } from './internal/parse.ts';
1820
import { formatSelectorFailure as formatSelectorFailureFromText } from './internal/resolve.ts';
1921
import type { SelectorDiagnostics } from './internal/public-resolution-types.ts';
@@ -22,7 +24,11 @@ export type { SelectorChain } from './internal/parse.ts';
2224
export type { SelectorDiagnostics } from './internal/public-resolution-types.ts';
2325

2426
export { isSelectorToken, parseSelectorChain, tryParseSelectorChain } from './internal/parse.ts';
25-
export { findSelectorChainMatch, resolveSelectorChain } from './internal/resolve.ts';
27+
export {
28+
findSelectorChainMatch,
29+
listSelectorChainMatches,
30+
resolveSelectorChain,
31+
} from './internal/resolve.ts';
2632
export { isNodeEditable, isNodeVisible } from './internal/node.ts';
2733

2834
/**

‎packages/selectors/src/internal/resolve.ts‎

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -117,13 +117,24 @@ export type AstSelectorChainMatchList = {
117117
};
118118

119119
/**
120-
* ADR 0012 migration step 4: the raw matched-node list for whichever chain
121-
* alternative `resolveSelectorChain` would pick (first alternative with any
122-
* match, in order) — mirrors `analyzeSelectorMatches`'s alternate-selection
123-
* exactly, decoupled from uniqueness/disambiguation, so a replay-time
124-
* verifier can compute `matchCount` and the recorded-identity set over the
125-
* SAME domain resolution itself used, independent of whether resolution
126-
* could pick a unique winner.
120+
* Every node the winning chain alternative matches, in snapshot order, plus
121+
* that alternative and its index; `null` when no alternative matches.
122+
*
123+
* "Winning" is the SAME alternative `findSelectorChainMatch` picks — the first
124+
* with at least one match — decoupled from uniqueness and disambiguation:
125+
* several matches are reported, never refused or narrowed to one. That is NOT
126+
* always what `resolveSelectorChain` names: under its default
127+
* `requireUnique: true` it skips an ambiguous alternative and resolves from a
128+
* later one, so the indices agree when it passes `requireUnique: false`, when
129+
* the first matching alternative is unique, or when `disambiguateAmbiguous:
130+
* true` resolves that alternative in place (see `firstMatch` vs `matchedNodes`
131+
* above). Published through `agent-device/selectors` (#3180) so a consumer
132+
* applies its OWN strictness to the same matched-node domain the daemon
133+
* resolves against, instead of reimplementing term matching.
134+
*
135+
* ADR 0012 migration step 4 kept this mirroring `analyzeSelectorMatches`'s
136+
* alternate-selection exactly, so a replay-time verifier computes `matchCount`
137+
* and the recorded-identity set over the SAME domain resolution itself used.
127138
*/
128139
export function listSelectorChainMatches(
129140
nodes: SnapshotState['nodes'],

‎src/sdk/selectors.test.ts‎

Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
import assert from 'node:assert/strict';
2+
import { test } from 'vitest';
3+
import { buildNodes } from '../__tests__/test-utils/snapshot-builders.ts';
4+
import {
5+
findSelectorChainMatch,
6+
listSelectorChainMatches,
7+
parseSelectorChain,
8+
resolveSelectorChain,
9+
} from './selectors.ts';
10+
11+
// Public-entry contract (#3180), through `./selectors.ts` rather than a deep
12+
// import: every node the winning alternative matches, on the same snapshot a
13+
// consumer applies its own strictness to.
14+
15+
const loginNodes = () =>
16+
buildNodes([
17+
{ index: 0, type: 'Window' },
18+
{
19+
index: 1,
20+
type: 'Button',
21+
label: 'Continue',
22+
identifier: 'auth_continue',
23+
rect: { x: 0, y: 80, width: 200, height: 44 },
24+
hittable: true,
25+
},
26+
{ index: 2, type: 'Text', label: 'Skip', rect: { x: 0, y: 124, width: 200, height: 20 } },
27+
{
28+
index: 3,
29+
type: 'Button',
30+
label: 'Continue',
31+
identifier: 'secondary_continue',
32+
rect: { x: 0, y: 140, width: 200, height: 44 },
33+
hittable: true,
34+
},
35+
// Matched by default; refused when the caller requires geometry.
36+
{ index: 4, type: 'Button', label: 'Continue', hittable: true },
37+
]);
38+
39+
test('listSelectorChainMatches returns every node of the winning alternative, in snapshot order (#3180)', () => {
40+
const nodes = loginNodes();
41+
const match = listSelectorChainMatches(nodes, parseSelectorChain('label="Continue"'), {
42+
platform: 'ios',
43+
});
44+
assert.ok(match);
45+
assert.equal(match.selectorIndex, 0);
46+
assert.equal(match.selector.raw, 'label="Continue"');
47+
assert.deepEqual(
48+
match.matchedNodes.map((node) => node.ref),
49+
['e2', 'e4', 'e5'],
50+
);
51+
// Identity, not a copy: consumers compare against their own snapshot.
52+
assert.equal(match.matchedNodes[0], nodes[1]);
53+
});
54+
55+
test('listSelectorChainMatches reports several matches where resolveSelectorChain refuses, from the same chain', () => {
56+
const nodes = loginNodes();
57+
const chain = parseSelectorChain('label="Continue"');
58+
assert.equal(
59+
resolveSelectorChain(nodes, chain, { platform: 'ios', requireUnique: true }),
60+
null,
61+
'uniqueness refusal must not remove the matched nodes from the list',
62+
);
63+
const match = listSelectorChainMatches(nodes, chain, { platform: 'ios' });
64+
assert.equal(match?.matchedNodes.length, 3);
65+
});
66+
67+
test('listSelectorChainMatches walks to the first alternative that matches, as find does and a uniqueness-refusing resolve does not', () => {
68+
const nodes = loginNodes();
69+
const match = listSelectorChainMatches(
70+
nodes,
71+
parseSelectorChain('label="Absent" || id=auth_continue'),
72+
{ platform: 'ios' },
73+
);
74+
assert.ok(match);
75+
assert.equal(match.selectorIndex, 1);
76+
assert.deepEqual(
77+
match.matchedNodes.map((node) => node.ref),
78+
['e2'],
79+
);
80+
// Both alternatives match: `find` shares this answer, a default
81+
// `resolveSelectorChain` refuses ambiguous alternative 0 and names 1.
82+
assert.equal(
83+
findSelectorChainMatch(nodes, parseSelectorChain('label="Continue" || id=auth_continue'), {
84+
platform: 'ios',
85+
})?.selectorIndex,
86+
0,
87+
);
88+
assert.equal(
89+
resolveSelectorChain(nodes, parseSelectorChain('label="Continue" || id=auth_continue'), {
90+
platform: 'ios',
91+
})?.selectorIndex,
92+
1,
93+
);
94+
const both = listSelectorChainMatches(
95+
nodes,
96+
parseSelectorChain('label="Continue" || id=auth_continue'),
97+
{ platform: 'ios' },
98+
);
99+
assert.equal(both?.selectorIndex, 0);
100+
assert.deepEqual(
101+
both?.matchedNodes.map((node) => node.ref),
102+
['e2', 'e4', 'e5'],
103+
);
104+
assert.equal(
105+
listSelectorChainMatches(nodes, parseSelectorChain('label="Absent"'), { platform: 'ios' }),
106+
null,
107+
);
108+
});
109+
110+
test('listSelectorChainMatches honors requireRect against the same geometry the resolver sees', () => {
111+
const nodes = loginNodes();
112+
const match = listSelectorChainMatches(nodes, parseSelectorChain('label="Continue"'), {
113+
platform: 'ios',
114+
requireRect: true,
115+
});
116+
assert.deepEqual(
117+
match?.matchedNodes.map((node) => node.ref),
118+
['e2', 'e4'],
119+
);
120+
});
121+
122+
test('listSelectorChainMatches lets requireRect change WHICH alternative wins, not just its members', () => {
123+
// `requireRect` removes candidates BEFORE alternative selection, so the walk
124+
// can move to a later alternative instead of reporting an empty first one.
125+
const nodes = buildNodes([
126+
{ index: 0, type: 'Button', label: 'NoRect' },
127+
{ index: 1, type: 'Button', identifier: 'foo', rect: { x: 0, y: 10, width: 10, height: 10 } },
128+
]);
129+
const chain = parseSelectorChain('label="NoRect" || id=foo');
130+
assert.equal(
131+
listSelectorChainMatches(nodes, chain, { platform: 'ios' })?.selectorIndex,
132+
0,
133+
'without the geometry requirement the first alternative wins',
134+
);
135+
const required = listSelectorChainMatches(nodes, chain, {
136+
platform: 'ios',
137+
requireRect: true,
138+
});
139+
assert.equal(required?.selectorIndex, 1);
140+
assert.deepEqual(
141+
required?.matchedNodes.map((node) => node.ref),
142+
['e2'],
143+
);
144+
});
145+
146+
test('listSelectorChainMatches returns null for an empty chain and for a total miss', () => {
147+
const nodes = loginNodes();
148+
// No alternative to win, and an empty match set is not representable.
149+
assert.equal(
150+
listSelectorChainMatches(nodes, { raw: '', selectors: [] }, { platform: 'ios' }),
151+
null,
152+
);
153+
});
154+
155+
test('listSelectorChainMatches returns nodes in snapshot-array order, not index order', () => {
156+
// Array order, not `index` order: the answer follows the snapshot passed in.
157+
const nodes = buildNodes([
158+
{ index: 5, type: 'Button', label: 'M' },
159+
{ index: 2, type: 'Button', label: 'M' },
160+
]);
161+
assert.deepEqual(
162+
nodes.map((node) => node.ref),
163+
['e1', 'e2'],
164+
);
165+
const match = listSelectorChainMatches(nodes, parseSelectorChain('label="M"'), {
166+
platform: 'ios',
167+
});
168+
assert.deepEqual(
169+
match?.matchedNodes.map((node) => node.ref),
170+
['e1', 'e2'],
171+
);
172+
assert.deepEqual(
173+
match?.matchedNodes.map((node) => node.index),
174+
[5, 2],
175+
);
176+
});
177+
178+
test('listSelectorChainMatches uses agent-device term semantics (#3180)', () => {
179+
// `hittable` requires an explicit true, so the non-hittable row cannot lead.
180+
const hittableNodes = buildNodes([
181+
{ index: 0, type: 'Button', label: 'Refresh' },
182+
{
183+
index: 1,
184+
type: 'Button',
185+
label: 'Refresh',
186+
rect: { x: 0, y: 40, width: 100, height: 40 },
187+
hittable: true,
188+
},
189+
]);
190+
const hittable = listSelectorChainMatches(
191+
hittableNodes,
192+
parseSelectorChain('hittable=true label="Refresh"'),
193+
{ platform: 'ios' },
194+
);
195+
assert.deepEqual(
196+
hittable?.matchedNodes.map((node) => node.ref),
197+
['e2'],
198+
);
199+
200+
// `text` is extractNodeText — the FIRST non-empty of label/value/identifier —
201+
// so e2, whose label wins with a different value, does not match.
202+
const textNodes = buildNodes([
203+
{ index: 0, type: 'Button', label: 'Sign in' },
204+
{ index: 1, type: 'Button', label: 'Other', value: 'Sign in' },
205+
]);
206+
const text = listSelectorChainMatches(textNodes, parseSelectorChain('text="Sign in"'), {
207+
platform: 'android',
208+
});
209+
assert.deepEqual(
210+
text?.matchedNodes.map((node) => node.ref),
211+
['e1'],
212+
);
213+
214+
// `role` matches the NORMALIZED native class, not the raw type string.
215+
const roleNodes = buildNodes([
216+
{ index: 0, type: 'XCUIElementTypeButton', label: 'OK' },
217+
{ index: 1, type: 'XCUIElementTypeSwitch', label: 'Wi-Fi' },
218+
]);
219+
const role = listSelectorChainMatches(roleNodes, parseSelectorChain('role="button"'), {
220+
platform: 'ios',
221+
});
222+
assert.deepEqual(
223+
role?.matchedNodes.map((node) => node.ref),
224+
['e1'],
225+
);
226+
227+
// `editable` is fillable type + enabled: a TextView role="textbox" is not
228+
// fillable, and a disabled EditText is not enabled.
229+
const editableNodes = buildNodes([
230+
{ index: 0, type: 'android.widget.EditText', label: 'Name', enabled: true },
231+
{ index: 1, type: 'android.widget.TextView', label: 'Note', role: 'textbox' },
232+
{ index: 2, type: 'android.widget.EditText', label: 'Disabled', enabled: false },
233+
]);
234+
const editable = listSelectorChainMatches(editableNodes, parseSelectorChain('editable=true'), {
235+
platform: 'android',
236+
});
237+
assert.deepEqual(
238+
editable?.matchedNodes.map((node) => node.ref),
239+
['e1'],
240+
);
241+
242+
// `visible` is isNodeVisible: hittable OR a non-empty rect. e1 exercises the
243+
// hittable arm with a zero-size rect, e2 the rect arm while non-hittable, and
244+
// e3 has neither, which is what `hidden=true` names.
245+
const visibleNodes = buildNodes([
246+
{
247+
index: 0,
248+
type: 'Button',
249+
label: 'Row',
250+
hittable: true,
251+
rect: { x: 0, y: 0, width: 0, height: 0 },
252+
},
253+
{ index: 1, type: 'Button', label: 'Row', rect: { x: 0, y: 20, width: 50, height: 50 } },
254+
{ index: 2, type: 'Button', label: 'Row' },
255+
]);
256+
const visible = listSelectorChainMatches(visibleNodes, parseSelectorChain('visible=true'), {
257+
platform: 'ios',
258+
});
259+
assert.deepEqual(
260+
visible?.matchedNodes.map((node) => node.ref),
261+
['e1', 'e2'],
262+
);
263+
const hidden = listSelectorChainMatches(visibleNodes, parseSelectorChain('hidden=true'), {
264+
platform: 'ios',
265+
});
266+
assert.deepEqual(
267+
hidden?.matchedNodes.map((node) => node.ref),
268+
['e3'],
269+
);
270+
});

‎src/sdk/selectors.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ export {
66
isNodeEditable,
77
isNodeVisible,
88
isSelectorToken,
9+
listSelectorChainMatches,
910
parseSelectorChain,
1011
resolveSelectorChain,
1112
tryParseSelectorChain,

‎test/integration/installed-package-metro.test.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -329,7 +329,9 @@ test('installed package exposes Node APIs and packaged companion tunnel entrypoi
329329
'./plugins': (mod) => Object.keys(mod).length === 0,
330330
'./remote-config': (mod) => typeof mod,
331331
'./selectors': (mod) =>
332-
mod.isSelectorToken('||') && typeof mod.parseSelectorChain === 'function',
332+
mod.isSelectorToken('||') &&
333+
typeof mod.parseSelectorChain === 'function' &&
334+
typeof mod.listSelectorChainMatches === 'function',
333335
};
334336
const subpathSmokeResults = {};
335337
for (const subpath of Object.keys(subpathSmoke).sort()) {

‎website/docs/docs/client-api.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,7 @@ Supported public entry points for Node consumers:
6565
- `tryParseSelectorChain(expression)`
6666
- `resolveSelectorChain(nodes, chain, options)`
6767
- `findSelectorChainMatch(nodes, chain, options)`
68+
- `listSelectorChainMatches(nodes, chain, options)`
6869
- `formatSelectorFailure(chain, diagnostics, options)`
6970
- `isNodeVisible(node)`
7071
- `isSelectorToken(token)`
@@ -496,6 +497,8 @@ Use `agent-device/remote-config` for profile loading and path resolution, `agent
496497

497498
Use `agent-device/selectors` when a remote daemon or bridge needs to parse and match selector expressions without deep-importing daemon internals. Matching is platform-aware because role normalization and editability checks differ by backend.
498499

500+
`listSelectorChainMatches(nodes, chain, options)` returns every node the winning selector alternative matches, in snapshot order, plus that alternative and its index — the same first-match domain `findSelectorChainMatch` uses, without uniqueness refusal, so a runner applies its own strictness to the same nodes the CLI matched. `resolveSelectorChain` can name a LATER alternative: by default it refuses an ambiguous one and keeps walking, so the indices agree when it passes `requireUnique: false`, when the first matching alternative is unique, or when `disambiguateAmbiguous: true` resolves that alternative in place. It returns `null` when no alternative matches. `options` is `{ platform, requireRect? }`; the matched `SnapshotNode` objects are the ones passed in.
501+
499502
```ts
500503
import { findSelectorChainMatch, parseSelectorChain } from 'agent-device/selectors';
501504

0 commit comments

Comments
 (0)