fix: improve Maestro test suite replay

Author: thymikee

src/__tests__/cli-network.test.ts

@@ -153,6 +153,44 @@ test('test command reports flaky passed-on-retry cases in the default summary',
   assert.match(result.stdout, /Test summary: 1 passed, 0 failed, 1 flaky in 25ms/);
 });
 
+test('test --maestro forwards Maestro backend and platform for directory suites', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-cli-maestro-suite-'));
+  await fs.writeFile(
+    path.join(tmpDir, 'auth-flow.yml'),
+    ['appId: demo.app', '---', '- launchApp', ''].join('\n'),
+  );
+
+  try {
+    const result = await runCliCapture(
+      ['test', '--maestro', '--platform', 'android', tmpDir],
+      async () => ({
+        ok: true,
+        data: {
+          total: 1,
+          executed: 1,
+          passed: 1,
+          failed: 0,
+          skipped: 0,
+          notRun: 0,
+          durationMs: 5,
+          failures: [],
+          tests: [],
+        },
+      }),
+    );
+
+    assert.equal(result.code, null);
+    assert.equal(result.calls.length, 1);
+    assert.equal(result.calls[0]?.command, 'test');
+    assert.deepEqual(result.calls[0]?.positionals, [tmpDir]);
+    assert.equal(result.calls[0]?.flags?.replayBackend, 'maestro');
+    assert.equal(result.calls[0]?.flags?.platform, 'android');
+    assert.match(result.stderr, /Running replay suite\.\.\./);
+  } finally {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+});
+
 test('test command writes JUnit report with failure metadata', async () => {
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-junit-test-'));
   const reportPath = path.join(tmpDir, 'replays.junit.xml');

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 {