agent-device 0.2.3 → 0.2.5

package/skills/agent-device/references/snapshot-refs.md

@@ -1,8 +1,8 @@
-# Snapshot + Refs Workflow (Mobile)
+# Snapshot Refs and Selectors (Mobile)
 
 ## Purpose
 
-Refs let agents interact without repeating full UI trees. Snapshot -> refs -> click/fill.
+Refs are useful for discovery/debugging. For deterministic scripts, use selectors.
 
 ## Snapshot
 
@@ -21,17 +21,25 @@ App: com.apple.Preferences
   @e3 [button] "Privacy & Security"
 ```
 
-## Using refs
+## Using refs (discovery/debug)
 
 ```bash
 agent-device click @e2
 agent-device fill @e5 "test"
 ```
 
+## Using selectors (deterministic)
+
+```bash
+agent-device click 'id="camera_row" || label="Camera" role=button'
+agent-device fill 'id="search_input" editable=true' "test"
+agent-device is visible 'id="camera_settings_anchor"'
+```
+
 ## Ref lifecycle
 
-Refs become invalid when UI changes (navigation, modal, dynamic list updates).
-Always re-snapshot after any transition.
+Refs can become invalid when UI changes (navigation, modal, dynamic list updates).
+Re-snapshot after transitions if you keep using refs.
 
 ## Scope snapshots
 
@@ -47,3 +55,8 @@ agent-device snapshot -i -s @e3
 - Ref not found: re-snapshot.
 - AX returns Simulator window: restart Simulator and re-run.
 - AX empty: verify Accessibility permission or use `--backend xctest` (XCTest is more complete).
+
+## Replay note
+
+- Prefer selector-based actions in recorded `.ad` replays.
+- Use `agent-device replay -u <path>` to update selector drift and rewrite replay scripts in place.

package/skills/agent-device/references/video-recording.md

@@ -12,7 +12,7 @@ agent-device record start ./recordings/ios.mov
 
 # Perform actions
 agent-device open App
-agent-device snapshot
+agent-device snapshot -i
 agent-device click @e3
 agent-device close
 
@@ -30,7 +30,7 @@ agent-device record start ./recordings/android.mp4
 
 # Perform actions
 agent-device open App
-agent-device snapshot
+agent-device snapshot -i
 agent-device click @e3
 agent-device close
 

package/src/cli.ts

@@ -93,6 +93,12 @@ export async function runCli(argv: string[]): Promise<void> {
           return;
         }
       }
+      if (command === 'is') {
+        const predicate = (response.data as any)?.predicate ?? 'assertion';
+        process.stdout.write(`Passed: is ${predicate}\n`);
+        if (logTailStopper) logTailStopper();
+        return;
+      }
       if (command === 'click') {
         const ref = (response.data as any)?.ref ?? '';
         const x = (response.data as any)?.x;

package/src/core/__tests__/capabilities.test.ts

@@ -0,0 +1,67 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { isCommandSupportedOnDevice } from '../capabilities.ts';
+import type { DeviceInfo } from '../../utils/device.ts';
+
+const iosSimulator: DeviceInfo = {
+  platform: 'ios',
+  id: 'sim-1',
+  name: 'iPhone',
+  kind: 'simulator',
+};
+
+const iosDevice: DeviceInfo = {
+  platform: 'ios',
+  id: 'dev-1',
+  name: 'iPhone',
+  kind: 'device',
+};
+
+const androidDevice: DeviceInfo = {
+  platform: 'android',
+  id: 'and-1',
+  name: 'Pixel',
+  kind: 'device',
+};
+
+test('iOS simulator-only commands reject iOS devices and Android', () => {
+  for (const cmd of ['alert', 'pinch']) {
+    assert.equal(isCommandSupportedOnDevice(cmd, iosSimulator), true, `${cmd} on iOS sim`);
+    assert.equal(isCommandSupportedOnDevice(cmd, iosDevice), false, `${cmd} on iOS device`);
+    assert.equal(isCommandSupportedOnDevice(cmd, androidDevice), false, `${cmd} on Android`);
+  }
+});
+
+test('iOS simulator + Android commands reject iOS devices', () => {
+  for (const cmd of [
+    'app-switcher',
+    'apps',
+    'back',
+    'click',
+    'close',
+    'fill',
+    'find',
+    'focus',
+    'get',
+    'home',
+    'long-press',
+    'open',
+    'press',
+    'record',
+    'screenshot',
+    'scroll',
+    'settings',
+    'snapshot',
+    'type',
+    'wait',
+  ]) {
+    assert.equal(isCommandSupportedOnDevice(cmd, iosSimulator), true, `${cmd} on iOS sim`);
+    assert.equal(isCommandSupportedOnDevice(cmd, iosDevice), false, `${cmd} on iOS device`);
+    assert.equal(isCommandSupportedOnDevice(cmd, androidDevice), true, `${cmd} on Android`);
+  }
+});
+
+test('unknown commands default to supported', () => {
+  assert.equal(isCommandSupportedOnDevice('some-future-cmd', iosSimulator), true);
+  assert.equal(isCommandSupportedOnDevice('some-future-cmd', androidDevice), true);
+});

package/src/core/capabilities.ts

@@ -0,0 +1,49 @@
+import type { DeviceInfo } from '../utils/device.ts';
+
+type KindMatrix = {
+  simulator?: boolean;
+  device?: boolean;
+  emulator?: boolean;
+  unknown?: boolean;
+};
+
+type CommandCapability = {
+  ios?: KindMatrix;
+  android?: KindMatrix;
+};
+
+const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
+  // iOS simulator-only in v1.
+  alert: { ios: { simulator: true }, android: {} },
+  pinch: { ios: { simulator: true }, android: {} },
+  'app-switcher': { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  apps: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  back: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  click: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  close: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  fill: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  find: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  focus: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  get: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  is: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  home: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  'long-press': { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  open: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  press: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  record: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  screenshot: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  scroll: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  settings: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  snapshot: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  type: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  wait: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+};
+
+export function isCommandSupportedOnDevice(command: string, device: DeviceInfo): boolean {
+  const capability = COMMAND_CAPABILITY_MATRIX[command];
+  if (!capability) return true;
+  const byPlatform = capability[device.platform];
+  if (!byPlatform) return false;
+  const kind = (device.kind ?? 'unknown') as keyof KindMatrix;
+  return byPlatform[kind] === true;
+}

package/src/core/dispatch.ts

@@ -1,3 +1,5 @@
+import { promises as fs } from 'node:fs';
+import pathModule from 'node:path';
 import { AppError } from '../utils/errors.ts';
 import { selectDevice, type DeviceInfo } from '../utils/device.ts';
 import { listAndroidDevices } from '../platforms/android/devices.ts';
@@ -10,13 +12,14 @@ import {
   snapshotAndroid,
 } from '../platforms/android/index.ts';
 import { listIosDevices } from '../platforms/ios/devices.ts';
-import { getInteractor } from '../utils/interactors.ts';
+import { getInteractor, type RunnerContext } from '../utils/interactors.ts';
 import { runIosRunnerCommand } from '../platforms/ios/runner-client.ts';
 import { snapshotAx } from '../platforms/ios/ax-snapshot.ts';
 import { setIosSetting } from '../platforms/ios/index.ts';
 import type { RawSnapshotNode } from '../utils/snapshot.ts';
 
 export type CommandFlags = {
+  session?: string;
   platform?: 'ios' | 'android';
   device?: string;
   udid?: string;
@@ -30,10 +33,11 @@ export type CommandFlags = {
   snapshotScope?: string;
   snapshotRaw?: boolean;
   snapshotBackend?: 'ax' | 'xctest';
+  saveScript?: boolean;
   noRecord?: boolean;
-  recordJson?: boolean;
   appsFilter?: 'launchable' | 'user-installed' | 'all';
   appsMetadata?: boolean;
+  replayUpdate?: boolean;
 };
 
 export async function resolveTargetDevice(flags: CommandFlags): Promise<DeviceInfo> {
@@ -88,7 +92,13 @@ export async function dispatchCommand(
     snapshotBackend?: 'ax' | 'xctest';
   },
 ): Promise<Record<string, unknown> | void> {
-  const interactor = getInteractor(device);
+  const runnerCtx: RunnerContext = {
+    appBundleId: context?.appBundleId,
+    verbose: context?.verbose,
+    logPath: context?.logPath,
+    traceLogPath: context?.traceLogPath,
+  };
+  const interactor = getInteractor(device, runnerCtx);
   switch (command) {
     case 'open': {
       const app = positionals[0];
@@ -110,15 +120,7 @@ export async function dispatchCommand(
     case 'press': {
       const [x, y] = positionals.map(Number);
       if (Number.isNaN(x) || Number.isNaN(y)) throw new AppError('INVALID_ARGS', 'press requires x y');
-      if (device.platform === 'ios' && device.kind === 'simulator') {
-        await runIosRunnerCommand(
-          device,
-          { command: 'tap', x, y, appBundleId: context?.appBundleId },
-          { verbose: context?.verbose, logPath: context?.logPath, traceLogPath: context?.traceLogPath },
-        );
-      } else {
-        await interactor.tap(x, y);
-      }
+      await interactor.tap(x, y);
       return { x, y };
     }
     case 'long-press': {
@@ -134,29 +136,13 @@ export async function dispatchCommand(
     case 'focus': {
       const [x, y] = positionals.map(Number);
       if (Number.isNaN(x) || Number.isNaN(y)) throw new AppError('INVALID_ARGS', 'focus requires x y');
-      if (device.platform === 'ios' && device.kind === 'simulator') {
-        await runIosRunnerCommand(
-          device,
-          { command: 'tap', x, y, appBundleId: context?.appBundleId },
-          { verbose: context?.verbose, logPath: context?.logPath, traceLogPath: context?.traceLogPath },
-        );
-      } else {
-        await interactor.focus(x, y);
-      }
+      await interactor.focus(x, y);
       return { x, y };
     }
     case 'type': {
       const text = positionals.join(' ');
       if (!text) throw new AppError('INVALID_ARGS', 'type requires text');
-      if (device.platform === 'ios' && device.kind === 'simulator') {
-        await runIosRunnerCommand(
-          device,
-          { command: 'type', text, appBundleId: context?.appBundleId },
-          { verbose: context?.verbose, logPath: context?.logPath, traceLogPath: context?.traceLogPath },
-        );
-      } else {
-        await interactor.type(text);
-      }
+      await interactor.type(text);
       return { text };
     }
     case 'fill': {
@@ -166,63 +152,21 @@ export async function dispatchCommand(
       if (Number.isNaN(x) || Number.isNaN(y) || !text) {
         throw new AppError('INVALID_ARGS', 'fill requires x y text');
       }
-      if (device.platform === 'ios' && device.kind === 'simulator') {
-        await runIosRunnerCommand(
-          device,
-          { command: 'tap', x, y, appBundleId: context?.appBundleId },
-          { verbose: context?.verbose, logPath: context?.logPath, traceLogPath: context?.traceLogPath },
-        );
-        await runIosRunnerCommand(
-          device,
-          { command: 'type', text, clearFirst: true, appBundleId: context?.appBundleId },
-          { verbose: context?.verbose, logPath: context?.logPath, traceLogPath: context?.traceLogPath },
-        );
-      } else {
-        await interactor.fill(x, y, text);
-      }
+      await interactor.fill(x, y, text);
       return { x, y, text };
     }
     case 'scroll': {
       const direction = positionals[0];
       const amount = positionals[1] ? Number(positionals[1]) : undefined;
       if (!direction) throw new AppError('INVALID_ARGS', 'scroll requires direction');
-      if (device.platform === 'ios' && device.kind === 'simulator') {
-        if (!['up', 'down', 'left', 'right'].includes(direction)) {
-          throw new AppError('INVALID_ARGS', `Unknown direction: ${direction}`);
-        }
-        const inverted = invertScrollDirection(direction as 'up' | 'down' | 'left' | 'right');
-        await runIosRunnerCommand(
-          device,
-          { command: 'swipe', direction: inverted, appBundleId: context?.appBundleId },
-          { verbose: context?.verbose, logPath: context?.logPath, traceLogPath: context?.traceLogPath },
-        );
-      } else {
-        await interactor.scroll(direction, amount);
-      }
+      await interactor.scroll(direction, amount);
       return { direction, amount };
     }
     case 'scrollintoview': {
       const text = positionals.join(' ').trim();
       if (!text) throw new AppError('INVALID_ARGS', 'scrollintoview requires text');
-      if (device.platform === 'ios' && device.kind === 'simulator') {
-        const maxAttempts = 8;
-        for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
-          const found = (await runIosRunnerCommand(
-            device,
-            { command: 'findText', text, appBundleId: context?.appBundleId },
-            { verbose: context?.verbose, logPath: context?.logPath, traceLogPath: context?.traceLogPath },
-          )) as { found?: boolean };
-          if (found?.found) return { text, attempts: attempt + 1 };
-          await runIosRunnerCommand(
-            device,
-            { command: 'swipe', direction: 'up', appBundleId: context?.appBundleId },
-            { verbose: context?.verbose, logPath: context?.logPath, traceLogPath: context?.traceLogPath },
-          );
-          await new Promise((resolve) => setTimeout(resolve, 300));
-        }
-        throw new AppError('COMMAND_FAILED', `scrollintoview could not find text: ${text}`);
-      }
-      await interactor.scrollIntoView(text);
+      const result = await interactor.scrollIntoView(text);
+      if (result?.attempts) return { text, attempts: result.attempts };
       return { text };
     }
     case 'pinch': {
@@ -232,27 +176,22 @@ export async function dispatchCommand(
       if (Number.isNaN(scale) || scale <= 0) {
         throw new AppError('INVALID_ARGS', 'pinch requires scale > 0');
       }
-      if (device.platform === 'ios' && device.kind === 'simulator') {
-        await runIosRunnerCommand(
-          device,
-          { command: 'pinch', scale, x, y, appBundleId: context?.appBundleId },
-          { verbose: context?.verbose, logPath: context?.logPath, traceLogPath: context?.traceLogPath },
-        );
-      } else {
-        throw new AppError('UNSUPPORTED_OPERATION', 'pinch is only supported on iOS simulators');
-      }
+      await runIosRunnerCommand(
+        device,
+        { command: 'pinch', scale, x, y, appBundleId: context?.appBundleId },
+        { verbose: context?.verbose, logPath: context?.logPath, traceLogPath: context?.traceLogPath },
+      );
       return { scale, x, y };
     }
     case 'screenshot': {
-      const path = outPath ?? `./screenshot-${Date.now()}.png`;
-      await interactor.screenshot(path);
-      return { path };
+      const positionalPath = positionals[0];
+      const screenshotPath = positionalPath ?? outPath ?? `./screenshot-${Date.now()}.png`;
+      await fs.mkdir(pathModule.dirname(screenshotPath), { recursive: true });
+      await interactor.screenshot(screenshotPath);
+      return { path: screenshotPath };
     }
     case 'back': {
       if (device.platform === 'ios') {
-        if (device.kind !== 'simulator') {
-          throw new AppError('UNSUPPORTED_OPERATION', 'back is only supported on iOS simulators in v1');
-        }
         await runIosRunnerCommand(
           device,
           { command: 'back', appBundleId: context?.appBundleId },
@@ -265,9 +204,6 @@ export async function dispatchCommand(
     }
     case 'home': {
       if (device.platform === 'ios') {
-        if (device.kind !== 'simulator') {
-          throw new AppError('UNSUPPORTED_OPERATION', 'home is only supported on iOS simulators in v1');
-        }
         await runIosRunnerCommand(
           device,
           { command: 'home', appBundleId: context?.appBundleId },
@@ -280,9 +216,6 @@ export async function dispatchCommand(
     }
     case 'app-switcher': {
       if (device.platform === 'ios') {
-        if (device.kind !== 'simulator') {
-          throw new AppError('UNSUPPORTED_OPERATION', 'app-switcher is only supported on iOS simulators in v1');
-        }
         await runIosRunnerCommand(
           device,
           { command: 'appSwitcher', appBundleId: context?.appBundleId },
@@ -305,12 +238,6 @@ export async function dispatchCommand(
     case 'snapshot': {
       const backend = context?.snapshotBackend ?? 'xctest';
       if (device.platform === 'ios') {
-        if (device.kind !== 'simulator') {
-          throw new AppError(
-            'UNSUPPORTED_OPERATION',
-            'snapshot is only supported on iOS simulators in v1',
-          );
-        }
         if (backend === 'ax') {
           const ax = await snapshotAx(device, { traceLogPath: context?.traceLogPath });
           return { nodes: ax.nodes ?? [], truncated: false, backend: 'ax' };
@@ -352,18 +279,3 @@ export async function dispatchCommand(
       throw new AppError('INVALID_ARGS', `Unknown command: ${command}`);
   }
 }
-
-function invertScrollDirection(direction: 'up' | 'down' | 'left' | 'right'): 'up' | 'down' | 'left' | 'right' {
-  switch (direction) {
-    case 'up':
-      return 'down';
-    case 'down':
-      return 'up';
-    case 'left':
-      return 'right';
-    case 'right':
-      return 'left';
-  }
-}
-
-// Runner-only input on iOS simulators (simctl io input is not supported).

package/src/daemon/__tests__/is-predicates.test.ts

@@ -0,0 +1,68 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { evaluateIsPredicate, isSupportedPredicate } from '../is-predicates.ts';
+
+const baseNode = {
+  ref: 'e1',
+  index: 0,
+  type: 'XCUIElementTypeTextField',
+  label: 'Email',
+  value: '',
+  identifier: 'login_email',
+  rect: { x: 0, y: 0, width: 100, height: 40 },
+  enabled: true,
+  hittable: true,
+};
+
+test('isSupportedPredicate validates supported predicates', () => {
+  assert.equal(isSupportedPredicate('visible'), true);
+  assert.equal(isSupportedPredicate('text'), true);
+  assert.equal(isSupportedPredicate('checked'), false);
+});
+
+test('evaluateIsPredicate visible and hidden', () => {
+  const visible = evaluateIsPredicate({
+    predicate: 'visible',
+    node: baseNode,
+    platform: 'ios',
+  });
+  const hidden = evaluateIsPredicate({
+    predicate: 'hidden',
+    node: { ...baseNode, rect: { ...baseNode.rect, width: 0 }, hittable: false },
+    platform: 'ios',
+  });
+  assert.equal(visible.pass, true);
+  assert.equal(hidden.pass, true);
+});
+
+test('evaluateIsPredicate editable and selected', () => {
+  const editable = evaluateIsPredicate({
+    predicate: 'editable',
+    node: baseNode,
+    platform: 'ios',
+  });
+  const selected = evaluateIsPredicate({
+    predicate: 'selected',
+    node: { ...baseNode, selected: true },
+    platform: 'ios',
+  });
+  assert.equal(editable.pass, true);
+  assert.equal(selected.pass, true);
+});
+
+test('evaluateIsPredicate text uses equality', () => {
+  const match = evaluateIsPredicate({
+    predicate: 'text',
+    node: baseNode,
+    expectedText: 'Email',
+    platform: 'ios',
+  });
+  const mismatch = evaluateIsPredicate({
+    predicate: 'text',
+    node: baseNode,
+    expectedText: 'email',
+    platform: 'ios',
+  });
+  assert.equal(match.pass, true);
+  assert.equal(mismatch.pass, false);
+});

package/src/daemon/__tests__/selectors.test.ts

@@ -0,0 +1,128 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import type { SnapshotState } from '../../utils/snapshot.ts';
+import {
+  buildSelectorChainForNode,
+  findSelectorChainMatch,
+  isSelectorToken,
+  parseSelectorChain,
+  resolveSelectorChain,
+  splitSelectorFromArgs,
+} from '../selectors.ts';
+
+const nodes: SnapshotState['nodes'] = [
+  {
+    ref: 'e1',
+    index: 0,
+    type: 'XCUIElementTypeTextField',
+    label: 'Email',
+    value: '',
+    identifier: 'login_email',
+    rect: { x: 0, y: 0, width: 200, height: 44 },
+    enabled: true,
+    hittable: true,
+  },
+  {
+    ref: 'e2',
+    index: 1,
+    type: 'XCUIElementTypeButton',
+    label: 'Continue',
+    identifier: 'auth_continue',
+    rect: { x: 0, y: 80, width: 200, height: 44 },
+    enabled: true,
+    hittable: true,
+  },
+  {
+    ref: 'e3',
+    index: 2,
+    type: 'XCUIElementTypeButton',
+    label: 'Continue',
+    identifier: 'secondary_continue',
+    rect: { x: 0, y: 140, width: 200, height: 44 },
+    enabled: true,
+    hittable: true,
+  },
+];
+
+test('parseSelectorChain parses fallback and boolean terms', () => {
+  const chain = parseSelectorChain('id=auth_continue || role=button label="Continue" visible=true');
+  assert.equal(chain.selectors.length, 2);
+  assert.equal(chain.selectors[0].terms[0].key, 'id');
+  assert.equal(chain.selectors[1].terms[2].key, 'visible');
+});
+
+test('resolveSelectorChain resolves unique match', () => {
+  const chain = parseSelectorChain('id=login_email');
+  const resolved = resolveSelectorChain(nodes, chain, {
+    platform: 'ios',
+    requireRect: true,
+    requireUnique: true,
+  });
+  assert.ok(resolved);
+  assert.equal(resolved.node.ref, 'e1');
+});
+
+test('resolveSelectorChain falls back when first selector is ambiguous', () => {
+  const chain = parseSelectorChain('label="Continue" || id=auth_continue');
+  const resolved = resolveSelectorChain(nodes, chain, {
+    platform: 'ios',
+    requireRect: true,
+    requireUnique: true,
+  });
+  assert.ok(resolved);
+  assert.equal(resolved.selectorIndex, 1);
+  assert.equal(resolved.node.ref, 'e2');
+});
+
+test('findSelectorChainMatch returns first matching selector for existence checks', () => {
+  const chain = parseSelectorChain('label="Continue" || id=auth_continue');
+  const match = findSelectorChainMatch(nodes, chain, {
+    platform: 'ios',
+  });
+  assert.ok(match);
+  assert.equal(match.selectorIndex, 0);
+  assert.equal(match.matches, 2);
+});
+
+test('splitSelectorFromArgs extracts selector prefix and trailing value', () => {
+  const split = splitSelectorFromArgs(['id=login_email', 'editable=true', 'qa@example.com']);
+  assert.ok(split);
+  assert.equal(split.selectorExpression, 'id=login_email editable=true');
+  assert.deepEqual(split.rest, ['qa@example.com']);
+});
+
+test('parseSelectorChain rejects unknown keys and malformed quotes', () => {
+  assert.throws(() => parseSelectorChain('foo=bar'), /Unknown selector key/i);
+  assert.throws(() => parseSelectorChain('label="unclosed'), /Unclosed quote/i);
+  assert.throws(() => parseSelectorChain(''), /cannot be empty/i);
+});
+
+test('isSelectorToken only accepts known keys for key=value tokens', () => {
+  assert.equal(isSelectorToken('id=foo'), true);
+  assert.equal(isSelectorToken('editable=true'), true);
+  assert.equal(isSelectorToken('foo=bar'), false);
+  assert.equal(isSelectorToken('a=b'), false);
+});
+
+test('text selector matches extractNodeText semantics (first non-empty field)', () => {
+  const chainByLabel = parseSelectorChain('text=Email');
+  const chainById = parseSelectorChain('text=login_email');
+  const resolvedLabel = resolveSelectorChain(nodes, chainByLabel, {
+    platform: 'ios',
+    requireUnique: true,
+  });
+  const resolvedId = resolveSelectorChain(nodes, chainById, {
+    platform: 'ios',
+    requireUnique: true,
+  });
+  assert.ok(resolvedLabel);
+  assert.equal(resolvedLabel.node.ref, 'e1');
+  assert.equal(resolvedId, null);
+});
+
+test('buildSelectorChainForNode prefers id and adds editable for fill action', () => {
+  const target = nodes[0];
+  const chain = buildSelectorChainForNode(target, 'ios', { action: 'fill' });
+  assert.ok(chain.some((entry) => entry.includes('id=')));
+  assert.ok(chain.some((entry) => entry.includes('editable=true')));
+});