fix: improve Maestro test suite replay

Author: thymikee

src/__tests__/client.test.ts

@@ -418,6 +418,23 @@ test('replay.test keeps backend alias for suite discovery', async () => {
   assert.equal(setup.calls[0]?.flags?.replayBackend, 'maestro');
 });
 
+test('structured replay.test command forwards Maestro backend for suite discovery', async () => {
+  const setup = createTransport(async () => ({ ok: true, data: {} }));
+  const client = createAgentDeviceClient(setup.config, { transport: setup.transport });
+
+  await runCommand(client, 'test', {
+    paths: ['./e2e/maestro'],
+    backend: 'maestro',
+    platform: 'android',
+  });
+
+  assert.equal(setup.calls.length, 1);
+  assert.equal(setup.calls[0]?.command, 'test');
+  assert.deepEqual(setup.calls[0]?.positionals, ['./e2e/maestro']);
+  assert.equal(setup.calls[0]?.flags?.replayBackend, 'maestro');
+  assert.equal(setup.calls[0]?.flags?.platform, 'android');
+});
+
 test('client.command.wait prepares selector options and rejects invalid selectors', async () => {
   const setup = createTransport(async () => ({
     ok: true,

src/cli-test.ts

@@ -182,6 +182,13 @@ function buildSystemOut(test: ReplaySuiteTestResult): string {
   if ('replayed' in test) lines.push(`replayed: ${test.replayed}`);
   if ('healed' in test) lines.push(`healed: ${test.healed}`);
   if ('artifactsDir' in test && test.artifactsDir) lines.push(`artifactsDir: ${test.artifactsDir}`);
+  if (test.status === 'failed') {
+    lines.push(`errorCode: ${test.error.code}`, `errorMessage: ${test.error.message}`);
+    if (test.error.hint) lines.push(`hint: ${test.error.hint}`);
+    if (test.error.diagnosticId) lines.push(`diagnosticId: ${test.error.diagnosticId}`);
+    if (test.error.logPath) lines.push(`logPath: ${test.error.logPath}`);
+    if (test.error.details) lines.push(`details: ${JSON.stringify(test.error.details)}`);
+  }
   if (test.status === 'passed' && test.attempts > 1) lines.push('flaky: true');
   return lines.join('\n');
 }

src/commands/client-command-contracts.ts

@@ -261,10 +261,12 @@ export const clientCommandDefinitions = [
   ),
   defineFieldCommand(
     'test',
-    'Run one or more .ad scripts.',
+    'Run one or more replay scripts.',
     {
       paths: requiredField(stringArrayField()),
       update: booleanField(),
+      backend: stringField(),
+      maestro: booleanField(),
       env: stringArrayField(),
       failFast: booleanField(),
       timeoutMs: integerField(),

src/compat/maestro/runtime-interactions.ts

@@ -218,7 +218,13 @@ async function resolveMaestroScreenSwipe(params: {
   }
 
   const [mode, ...args] = params.positionals;
-  if (mode === 'direction') return resolveDirectionalScreenSwipe(args, frame);
+  if (mode === 'direction') {
+    return resolveDirectionalScreenSwipe(
+      args,
+      frame,
+      readMaestroSelectorPlatform(params.baseReq.flags),
+    );
+  }
   if (mode === 'percent') {
     return resolvePercentScreenSwipe(
       args,
@@ -246,6 +252,7 @@ async function captureFrameForMaestroScreenSwipe(params: {
 function resolveDirectionalScreenSwipe(
   args: string[],
   frame: { referenceWidth: number; referenceHeight: number },
+  platform: string,
 ):
   | {
       ok: true;
@@ -267,10 +274,14 @@ function resolveDirectionalScreenSwipe(
       return { ok: true, start: point(50, 80), end: point(50, 20), durationMs };
     case 'down':
       return { ok: true, start: point(50, 20), end: point(50, 80), durationMs };
-    case 'left':
-      return { ok: true, start: point(80, 50), end: point(20, 50), durationMs };
-    case 'right':
-      return { ok: true, start: point(20, 50), end: point(80, 50), durationMs };
+    case 'left': {
+      const yPercent = androidHorizontalContentSwipeY(platform, 80, 50, 20, 50);
+      return { ok: true, start: point(80, yPercent), end: point(20, yPercent), durationMs };
+    }
+    case 'right': {
+      const yPercent = androidHorizontalContentSwipeY(platform, 20, 50, 80, 50);
+      return { ok: true, start: point(20, yPercent), end: point(80, yPercent), durationMs };
+    }
     default:
       return {
         ok: false,

src/compat/maestro/runtime-targets.ts

@@ -4,7 +4,7 @@ import { parseSelectorChain } from '../../daemon/selectors.ts';
 import { matchesSelector } from '../../daemon/selectors-match.ts';
 import { evaluateIsPredicate } from '../../utils/selector-is-predicates.ts';
 import { normalizeText } from '../../utils/finders.ts';
-import { extractNodeText } from '../../utils/snapshot-processing.ts';
+import { extractNodeText, normalizeType } from '../../utils/snapshot-processing.ts';
 import type { TouchReferenceFrame } from '../../daemon/touch-reference-frame.ts';
 import type { DaemonRequest } from '../../daemon/types.ts';
 import type { Selector, SelectorTerm } from '../../daemon/selectors-parse.ts';
@@ -74,6 +74,8 @@ export function resolveMaestroNodeFromSnapshot(
     options.index,
     extractMaestroVisibleTextQuery(selector),
     frame,
+    false,
+    true,
   );
   if (!target) {
     const index = options.index ?? 0;
@@ -93,7 +95,15 @@ export function resolveMaestroFuzzyTextNodeFromSnapshot(
   frame: TouchReferenceFrame | undefined,
 ): { ok: true; node: SnapshotNode; rect: Rect } | { ok: false; message: string } {
   const matches = findMaestroFuzzyTextMatches(snapshot, query);
-  const target = selectMaestroSnapshotMatch(snapshot.nodes, matches, undefined, query, frame);
+  const target = selectMaestroSnapshotMatch(
+    snapshot.nodes,
+    matches,
+    undefined,
+    query,
+    frame,
+    false,
+    true,
+  );
   if (!target) {
     return { ok: false, message: `Maestro fuzzy text did not match: ${query}` };
   }
@@ -308,6 +318,7 @@ function selectMaestroSnapshotMatch(
   visibleTextQuery: string | null,
   frame: TouchReferenceFrame | undefined,
   requireOnScreen = false,
+  promoteTapTarget = false,
 ): { node: SnapshotNode; rect: Rect } | null {
   const nodeByIndex = buildSnapshotNodeByIndex(nodes);
   const resolved = matches
@@ -321,12 +332,24 @@ function selectMaestroSnapshotMatch(
       ? preferOnScreenMatches(resolved, frame, requireOnScreen)
       : resolved;
   if (index !== undefined) {
-    return candidates[index] ?? null;
+    return promoteMaestroSnapshotMatch(
+      nodes,
+      candidates[index] ?? null,
+      nodeByIndex,
+      promoteTapTarget,
+      frame,
+    );
   }
   const sorted = candidates.sort((left, right) =>
     compareMaestroSnapshotMatches(left, right, visibleTextQuery),
   );
-  return sorted[0] ?? null;
+  return promoteMaestroSnapshotMatch(
+    nodes,
+    sorted[0] ?? null,
+    nodeByIndex,
+    promoteTapTarget,
+    frame,
+  );
 }
 
 function preferOnScreenMatches(
@@ -407,7 +430,78 @@ function rectArea(rect: Rect): number {
 }
 
 function maestroTapTargetTypeRank(node: SnapshotNode): number {
-  return MAESTRO_TAP_TARGET_TYPE_RANK.get(node.type?.toLowerCase() ?? '') ?? 3;
+  return MAESTRO_TAP_TARGET_TYPE_RANK.get(normalizeType(node.type ?? '')) ?? 3;
+}
+
+function promoteMaestroSnapshotMatch(
+  nodes: SnapshotState['nodes'],
+  match: MaestroResolvedSnapshotMatch | null,
+  nodeByIndex: SnapshotNodeByIndex,
+  promoteTapTarget: boolean,
+  frame: TouchReferenceFrame | undefined,
+): { node: SnapshotNode; rect: Rect } | null {
+  if (!match) return null;
+  if (!promoteTapTarget) {
+    return { node: match.node, rect: match.rect };
+  }
+  const ancestor = findMaestroTapAncestor(nodes, match, nodeByIndex, frame);
+  return ancestor ?? { node: match.node, rect: match.rect };
+}
+
+function findMaestroTapAncestor(
+  nodes: SnapshotState['nodes'],
+  match: MaestroResolvedSnapshotMatch,
+  nodeByIndex: SnapshotNodeByIndex,
+  frame: TouchReferenceFrame | undefined,
+): { node: SnapshotNode; rect: Rect } | null {
+  if (isActionableMaestroTapTarget(match.node)) return null;
+  return findSnapshotAncestor(nodes, match.node, nodeByIndex, (ancestor) => {
+    if (!isActionableMaestroTapTarget(ancestor)) return null;
+    const ancestorRect = resolveNodeRect(nodes, ancestor, nodeByIndex);
+    if (!ancestorRect || !isUsefulMaestroTapAncestorRect(match.rect, ancestorRect.rect, frame)) {
+      return null;
+    }
+    return { node: ancestor, rect: ancestorRect.rect };
+  });
+}
+
+function isActionableMaestroTapTarget(node: SnapshotNode): boolean {
+  const type = normalizeType(node.type ?? '');
+  return (
+    node.hittable === true ||
+    type === 'button' ||
+    type === 'link' ||
+    type === 'cell' ||
+    type === 'textfield' ||
+    type === 'searchfield' ||
+    type === 'switch' ||
+    type === 'slider'
+  );
+}
+
+function isUsefulMaestroTapAncestorRect(
+  matchRect: Rect,
+  ancestorRect: Rect,
+  frame: TouchReferenceFrame | undefined,
+): boolean {
+  if (!rectContains(ancestorRect, matchRect)) return false;
+  const ancestorArea = rectArea(ancestorRect);
+  const matchArea = rectArea(matchRect);
+  if (matchArea > 0 && ancestorArea > matchArea * 30) return false;
+  if (frame) {
+    const frameArea = frame.referenceWidth * frame.referenceHeight;
+    if (frameArea > 0 && ancestorArea > frameArea * 0.5) return false;
+  }
+  return true;
+}
+
+function rectContains(container: Rect, child: Rect): boolean {
+  return (
+    child.x >= container.x &&
+    child.y >= container.y &&
+    child.x + child.width <= container.x + container.width &&
+    child.y + child.height <= container.y + container.height
+  );
 }
 
 function maestroVisibleTextMatchRank(node: SnapshotNode, query: string): number {

src/daemon/handlers/__tests__/session-replay-vars.test.ts

@@ -730,6 +730,96 @@ test('runReplayScriptFile lets Maestro tapOn use fuzzy visible text matching', a
   assert.equal(calls[0]?.flags?.noRecord, true);
 });
 
+test('runReplayScriptFile promotes Maestro text tapOn to an actionable ancestor', async () => {
+  const calls: CapturedInvocation[] = [];
+  const { response } = await runReplayFixture({
+    label: 'maestro-tap-visible-text-actionable-ancestor',
+    script: ['appId: demo.app', '---', '- tapOn: Article', ''].join('\n'),
+    flags: { replayBackend: 'maestro', platform: 'ios' },
+    invoke: async (req) => {
+      calls.push({ command: req.command, positionals: req.positionals, flags: req.flags });
+      if (req.command === 'snapshot') {
+        return {
+          ok: true,
+          data: {
+            nodes: [
+              {
+                index: 1,
+                type: 'XCUIElementTypeButton',
+                rect: { x: 40, y: 100, width: 120, height: 48 },
+                hittable: true,
+              },
+              {
+                index: 2,
+                parentIndex: 1,
+                type: 'XCUIElementTypeStaticText',
+                label: 'Article',
+                rect: { x: 76, y: 114, width: 48, height: 20 },
+                hittable: false,
+              },
+            ],
+          },
+        };
+      }
+      return { ok: true, data: {} };
+    },
+  });
+
+  assert.equal(response.ok, true);
+  assert.deepEqual(
+    calls.map((call) => [call.command, call.positionals]),
+    [
+      ['snapshot', []],
+      ['click', ['100', '124']],
+    ],
+  );
+});
+
+test('runReplayScriptFile promotes Maestro id tapOn to an actionable ancestor', async () => {
+  const calls: CapturedInvocation[] = [];
+  const { response } = await runReplayFixture({
+    label: 'maestro-tap-id-actionable-ancestor',
+    script: ['appId: demo.app', '---', '- tapOn:', '    id: album-0', ''].join('\n'),
+    flags: { replayBackend: 'maestro', platform: 'android' },
+    invoke: async (req) => {
+      calls.push({ command: req.command, positionals: req.positionals, flags: req.flags });
+      if (req.command === 'snapshot') {
+        return {
+          ok: true,
+          data: {
+            nodes: [
+              {
+                index: 1,
+                type: 'android.widget.Button',
+                rect: { x: 24, y: 320, width: 312, height: 64 },
+                hittable: true,
+              },
+              {
+                index: 2,
+                parentIndex: 1,
+                type: 'android.widget.TextView',
+                identifier: 'album-0',
+                rect: { x: 44, y: 334, width: 80, height: 24 },
+                hittable: false,
+              },
+            ],
+          },
+        };
+      }
+      return { ok: true, data: {} };
+    },
+  });
+
+  assert.equal(response.ok, true);
+  assert.deepEqual(
+    calls.map((call) => [call.command, call.positionals]),
+    [
+      ['snapshot', []],
+      ['click', ['180', '352']],
+    ],
+  );
+});
+
 test('runReplayScriptFile reuses successful Maestro visibility snapshot for following tapOn', async () => {
   let snapshots = 0;
   const { response, calls } = await runReplayFixture({
@@ -1281,6 +1371,54 @@ test('runReplayScriptFile resolves Maestro screen swipes from the snapshot frame
   );
 });
 
+test('runReplayScriptFile uses Android content lane for Maestro horizontal screen swipes', async () => {
+  const calls: CapturedInvocation[] = [];
+  const { response } = await runReplayFixture({
+    label: 'maestro-screen-swipe-android-content-lane',
+    script: [
+      'appId: demo.app',
+      '---',
+      '- swipe:',
+      '    direction: LEFT',
+      '    duration: 300',
+      '- swipe:',
+      '    start: 90%,50%',
+      '    end: 10%,50%',
+      '    duration: 300',
+      '',
+    ].join('\n'),
+    flags: { replayBackend: 'maestro', platform: 'android' },
+    invoke: async (req) => {
+      calls.push({ command: req.command, positionals: req.positionals, flags: req.flags });
+      if (req.command === 'snapshot') {
+        return {
+          ok: true,
+          data: {
+            nodes: [
+              {
+                index: 0,
+                type: 'application',
+                rect: { x: 0, y: 0, width: 400, height: 800 },
+              },
+            ],
+          },
+        };
+      }
+      return { ok: true, data: {} };
+    },
+  });
+
+  assert.equal(response.ok, true);
+  assert.deepEqual(
+    calls.map((call) => [call.command, call.positionals]),
+    [
+      ['snapshot', []],
+      ['swipe', ['320', '520', '80', '520', '300']],
+      ['swipe', ['360', '520', '40', '520', '300']],
+    ],
+  );
+});
+
 test('runReplayScriptFile maps Maestro enter to keyboard enter', async () => {
   const calls: CapturedInvocation[] = [];
   const { response } = await runReplayFixture({