feat: for self-healing e2e tests; assertions

Author: thymikee

AGENTS.md

@@ -14,6 +14,9 @@ Minimal operating guide for AI coding agents in this repo.
 - Use daemon session flow for interactions (`open` before interactions, `close` after).
 - Do not remove shared snapshot/session model behavior without full migration.
 - If Swift runner code changes, run `pnpm build:xcuitest`.
+- Do not add command logic to `daemon.ts` — it is a thin router. Use handler modules.
+- Use `inferFillText` and `uniqueStrings` from `src/daemon/action-utils.ts`. Do not duplicate.
+- Use `evaluateIsPredicate` from `src/daemon/is-predicates.ts` for assertion logic. Do not inline.
 
 ## Architecture In One Screen
 
@@ -24,14 +27,18 @@ Minimal operating guide for AI coding agents in this repo.
 2. Daemon client transport:
    - `src/daemon-client.ts`
 3. Daemon server bootstrap/router:
-   - `src/daemon.ts`
+   - `src/daemon.ts` — thin router only, delegates to handler modules
 4. Daemon command families:
    - session/apps/appstate/open/close/replay: `src/daemon/handlers/session.ts`
+   - click/fill/get/is: `src/daemon/handlers/interaction.ts`
    - snapshot/wait/alert/settings: `src/daemon/handlers/snapshot.ts`
    - semantic find actions: `src/daemon/handlers/find.ts`
    - record/trace: `src/daemon/handlers/record-trace.ts`
 5. Daemon shared domain:
    - session state + logs: `src/daemon/session-store.ts`
+   - selector DSL (parse, resolve, build): `src/daemon/selectors.ts`
+   - `is` predicate evaluation: `src/daemon/is-predicates.ts`
+   - shared action helpers (inferFillText, uniqueStrings): `src/daemon/action-utils.ts`
    - snapshot tree shaping + label resolution: `src/daemon/snapshot-processing.ts`
    - handler context helpers: `src/daemon/context.ts`, `src/daemon/device-ready.ts`, `src/daemon/app-state.ts`
 6. Platform dispatch/backends:
@@ -55,34 +62,42 @@ Do not read both iOS and Android paths unless issue is explicitly cross-platform
 
 - `session list`, `devices`, `apps`, `appstate`, `open`, `close`, `replay`:
   - `src/daemon/handlers/session.ts`
+- `click`, `fill`, `get`, `is`:
+  - `src/daemon/handlers/interaction.ts`
 - `snapshot`, `wait`, `alert`, `settings`:
   - `src/daemon/handlers/snapshot.ts`
 - `find ...`:
   - `src/daemon/handlers/find.ts`
 - `record start|stop`, `trace start|stop`:
   - `src/daemon/handlers/record-trace.ts`
-- `click`, `fill`, `get`, generic passthrough:
-  - `src/daemon.ts` (remaining fallback logic)
+- Generic passthrough (press, scroll, type, etc.):
+  - `src/daemon.ts` (fallback after all handlers return null)
 
 ## Capability Source Of Truth
 
 - Command/device support must come from `src/core/capabilities.ts`.
 - Do not scatter new support checks across handlers.
 
+## Selector System Rules
+
+All interaction commands (`click`, `fill`, `get`, `is`) and `wait` accept selectors in addition to `@ref`.
+The selector pipeline is: **parse → resolve → act → record selectorChain → heal on replay**.
+
+- Selector DSL lives in `src/daemon/selectors.ts`. Do not duplicate parsing/matching logic elsewhere.
+- `buildSelectorChainForNode` generates fallback chains stored in action results. Always call it after resolving a node for an interaction — it powers replay healing.
+- When adding a new interaction command that targets a UI element: support both `@ref` and selector input, record `selectorChain`, and update replay healing (`healReplayAction` + `collectReplaySelectorCandidates` in `session.ts`).
+- When adding a new selector key: update `SelectorKey` type, `ALL_KEYS`/`TEXT_KEYS`/`BOOLEAN_KEYS` sets, `matchesTerm`, and `isSelectorToken` — all in `selectors.ts`.
+- When adding a new `is` predicate: update `IsPredicate` type and `evaluateIsPredicate` in `is-predicates.ts`, not in the handler.
+- `daemon.ts` must stay a thin router. Do not add command logic there — use the appropriate handler module.
+
 ## Testing Strategy
 
 ### Test placement policy
 
 - Unit tests are colocated with source files under `src/**`.
 - Use `__tests__` folders colocated with the related source folder.
 - The `test/**` tree is integration-only (including smoke integration tests).
-
-### Unit tests (default for all refactors, colocated)
-
-- `src/core/__tests__/capabilities.test.ts`
-- `src/daemon/handlers/__tests__/find.test.ts`
-- `src/daemon/__tests__/snapshot-processing.test.ts`
-- `src/daemon/__tests__/session-store.test.ts`
+- Example: tests for `src/daemon/selectors.ts` go in `src/daemon/__tests__/selectors.test.ts`.
 
 Add/extend colocated unit tests in the same PR for touched module logic.
 

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;

src/core/capabilities.ts

@@ -25,6 +25,7 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
   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 } },

src/core/dispatch.ts

@@ -37,6 +37,7 @@ export type CommandFlags = {
   recordJson?: boolean;
   appsFilter?: 'launchable' | 'user-installed' | 'all';
   appsMetadata?: boolean;
+  replayUpdate?: boolean;
 };
 
 export async function resolveTargetDevice(flags: CommandFlags): Promise<DeviceInfo> {

src/daemon.ts

@@ -7,16 +7,15 @@ import { fileURLToPath } from 'node:url';
 import { dispatchCommand, type CommandFlags } from './core/dispatch.ts';
 import { isCommandSupportedOnDevice } from './core/capabilities.ts';
 import { asAppError, AppError } from './utils/errors.ts';
-import { centerOfRect, findNodeByRef, normalizeRef } from './utils/snapshot.ts';
 import { stopIosRunnerSession } from './platforms/ios/runner-client.ts';
 import type { DaemonRequest, DaemonResponse } from './daemon/types.ts';
 import { SessionStore } from './daemon/session-store.ts';
-import { contextFromFlags as contextFromFlagsWithLog } from './daemon/context.ts';
+import { contextFromFlags as contextFromFlagsWithLog, type DaemonCommandContext } from './daemon/context.ts';
 import { handleSessionCommands } from './daemon/handlers/session.ts';
 import { handleSnapshotCommands } from './daemon/handlers/snapshot.ts';
 import { handleFindCommands } from './daemon/handlers/find.ts';
 import { handleRecordTraceCommands } from './daemon/handlers/record-trace.ts';
-import { findNodeByLabel, isFillableType, resolveRefLabel } from './daemon/snapshot-processing.ts';
+import { handleInteractionCommands } from './daemon/handlers/interaction.ts';
 import { assertSessionSelectorMatches } from './daemon/session-selector.ts';
 import { resolveEffectiveSessionName } from './daemon/session-routing.ts';
 
@@ -33,19 +32,7 @@ function contextFromFlags(
   flags: CommandFlags | undefined,
   appBundleId?: string,
   traceLogPath?: string,
-): {
-  appBundleId?: string;
-  activity?: string;
-  verbose?: boolean;
-  logPath?: string;
-  traceLogPath?: string;
-  snapshotInteractiveOnly?: boolean;
-  snapshotCompact?: boolean;
-  snapshotDepth?: number;
-  snapshotScope?: string;
-  snapshotBackend?: 'ax' | 'xctest';
-  snapshotRaw?: boolean;
-} {
+): DaemonCommandContext {
   return contextFromFlagsWithLog(logPath, flags, appBundleId, traceLogPath);
 }
 
@@ -94,139 +81,13 @@ async function handleRequest(req: DaemonRequest): Promise<DaemonResponse> {
   });
   if (findResponse) return findResponse;
 
-  if (command === 'click') {
-    const session = sessionStore.get(sessionName);
-    if (!session?.snapshot) {
-      return { ok: false, error: { code: 'INVALID_ARGS', message: 'No snapshot in session. Run snapshot first.' } };
-    }
-    const refInput = req.positionals?.[0] ?? '';
-    const ref = normalizeRef(refInput);
-    if (!ref) {
-      return { ok: false, error: { code: 'INVALID_ARGS', message: 'click requires a ref like @e2' } };
-    }
-    let node = findNodeByRef(session.snapshot.nodes, ref);
-    if (!node?.rect && req.positionals.length > 1) {
-      const fallbackLabel = req.positionals.slice(1).join(' ').trim();
-      if (fallbackLabel.length > 0) {
-        node = findNodeByLabel(session.snapshot.nodes, fallbackLabel);
-      }
-    }
-    if (!node?.rect) {
-      return { ok: false, error: { code: 'COMMAND_FAILED', message: `Ref ${refInput} not found or has no bounds` } };
-    }
-    const refLabel = resolveRefLabel(node, session.snapshot.nodes);
-    const { x, y } = centerOfRect(node.rect);
-    await dispatchCommand(session.device, 'press', [String(x), String(y)], req.flags?.out, {
-      ...contextFromFlags(req.flags, session.appBundleId, session.trace?.outPath),
-    });
-    sessionStore.recordAction(session, {
-      command,
-      positionals: req.positionals ?? [],
-      flags: req.flags ?? {},
-      result: { ref, x, y, refLabel },
-    });
-    return { ok: true, data: { ref, x, y } };
-  }
-
-  if (command === 'fill') {
-    const session = sessionStore.get(sessionName);
-    if (req.positionals?.[0]?.startsWith('@')) {
-      if (!session?.snapshot) {
-        return { ok: false, error: { code: 'INVALID_ARGS', message: 'No snapshot in session. Run snapshot first.' } };
-      }
-      const ref = normalizeRef(req.positionals[0]);
-      if (!ref) {
-        return { ok: false, error: { code: 'INVALID_ARGS', message: 'fill requires a ref like @e2' } };
-      }
-      const labelCandidate = req.positionals.length >= 3 ? req.positionals[1] : '';
-      const text = req.positionals.length >= 3 ? req.positionals.slice(2).join(' ') : req.positionals.slice(1).join(' ');
-      if (!text) {
-        return { ok: false, error: { code: 'INVALID_ARGS', message: 'fill requires text after ref' } };
-      }
-      let node = findNodeByRef(session.snapshot.nodes, ref);
-      if (!node?.rect && labelCandidate) {
-        node = findNodeByLabel(session.snapshot.nodes, labelCandidate);
-      }
-      if (!node?.rect) {
-        return { ok: false, error: { code: 'COMMAND_FAILED', message: `Ref ${req.positionals[0]} not found or has no bounds` } };
-      }
-      const nodeType = node.type ?? '';
-      const fillWarning =
-        nodeType && !isFillableType(nodeType, session.device.platform)
-          ? `fill target ${req.positionals[0]} resolved to "${nodeType}", attempting fill anyway.`
-          : undefined;
-      const refLabel = resolveRefLabel(node, session.snapshot.nodes);
-      const { x, y } = centerOfRect(node.rect);
-      const data = await dispatchCommand(
-        session.device,
-        'fill',
-        [String(x), String(y), text],
-        req.flags?.out,
-        {
-          ...contextFromFlags(req.flags, session.appBundleId, session.trace?.outPath),
-        },
-      );
-      const resultPayload: Record<string, unknown> = {
-        ...(data ?? { ref, x, y }),
-      };
-      if (fillWarning) {
-        resultPayload.warning = fillWarning;
-      }
-      sessionStore.recordAction(session, {
-        command,
-        positionals: req.positionals ?? [],
-        flags: req.flags ?? {},
-        result: { ...resultPayload, refLabel },
-      });
-      return { ok: true, data: resultPayload };
-    }
-  }
-
-  if (command === 'get') {
-    const sub = req.positionals?.[0];
-    const refInput = req.positionals?.[1];
-    if (sub !== 'text' && sub !== 'attrs') {
-      return { ok: false, error: { code: 'INVALID_ARGS', message: 'get only supports text or attrs' } };
-    }
-    const session = sessionStore.get(sessionName);
-    if (!session?.snapshot) {
-      return { ok: false, error: { code: 'INVALID_ARGS', message: 'No snapshot in session. Run snapshot first.' } };
-    }
-    const ref = normalizeRef(refInput ?? '');
-    if (!ref) {
-      return { ok: false, error: { code: 'INVALID_ARGS', message: 'get text requires a ref like @e2' } };
-    }
-    let node = findNodeByRef(session.snapshot.nodes, ref);
-    if (!node && req.positionals.length > 2) {
-      const labelCandidate = req.positionals.slice(2).join(' ').trim();
-      if (labelCandidate.length > 0) {
-        node = findNodeByLabel(session.snapshot.nodes, labelCandidate);
-      }
-    }
-    if (!node) {
-      return { ok: false, error: { code: 'COMMAND_FAILED', message: `Ref ${refInput} not found` } };
-    }
-    if (sub === 'attrs') {
-      sessionStore.recordAction(session, {
-        command,
-        positionals: req.positionals ?? [],
-        flags: req.flags ?? {},
-        result: { ref },
-      });
-      return { ok: true, data: { ref, node } };
-    }
-    const candidates = [node.label, node.value, node.identifier]
-      .map((value) => (typeof value === 'string' ? value.trim() : ''))
-      .filter((value) => value.length > 0);
-    const text = candidates[0] ?? '';
-    sessionStore.recordAction(session, {
-      command,
-      positionals: req.positionals ?? [],
-      flags: req.flags ?? {},
-      result: { ref, text, refLabel: text || undefined },
-    });
-    return { ok: true, data: { ref, text, node } };
-  }
+  const interactionResponse = await handleInteractionCommands({
+    req,
+    sessionName,
+    sessionStore,
+    contextFromFlags,
+  });
+  if (interactionResponse) return interactionResponse;
 
 
   const session = sessionStore.get(sessionName);

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);
+});