fix: stabilize Maestro visibility resolution

Author: thymikee

src/compat/maestro/__tests__/runtime-assertions.test.ts

@@ -70,21 +70,58 @@ test('invokeMaestroAssertNotVisible passes after a slow hidden sample exhausts t
     invoke: async (req): Promise<DaemonResponse> => {
       calls.push(req);
       return {
-        ok: false,
-        error: {
-          code: 'COMMAND_FAILED',
-          message: 'Selector did not match: id="tab-4"',
-          details: { command: 'is', reason: 'selector_not_found' },
+        ok: true,
+        data: {
+          createdAt: 1,
+          nodes: [],
         },
       };
     },
   });
 
   assert.equal(response.ok, true);
-  assert.deepEqual(calls.map((call) => call.positionals), [['visible', 'id="tab-4"']]);
+  assert.deepEqual(calls.map((call) => [call.command, call.positionals]), [
+    ['snapshot', []],
+  ]);
   if (response.ok) {
     assert.ok(response.data);
     assert.equal(response.data.stableSamples, 1);
     assert.equal(response.data.waitedMs, 3500);
   }
 });
+
+test('invokeMaestroAssertNotVisible ignores matched nodes without visible rects', async () => {
+  vi.spyOn(Date, 'now').mockReturnValueOnce(0).mockReturnValueOnce(0).mockReturnValueOnce(3500);
+
+  const response = await invokeMaestroAssertNotVisible({
+    baseReq: {
+      token: 't',
+      session: 's',
+      flags: { platform: 'android' },
+    },
+    positionals: ['label="📌" || text="📌" || id="📌"'],
+    invoke: async (): Promise<DaemonResponse> => ({
+      ok: true,
+      data: {
+        createdAt: 1,
+        nodes: [
+          {
+            index: 1,
+            ref: 'e1',
+            type: 'android.widget.TextView',
+            label: '📌',
+            value: '📌',
+            enabled: true,
+            depth: 21,
+          },
+        ],
+      },
+    }),
+  });
+
+  assert.equal(response.ok, true);
+  if (response.ok) {
+    assert.ok(response.data);
+    assert.equal(response.data.stableSamples, 1);
+  }
+});

src/compat/maestro/__tests__/runtime-targets.test.ts

@@ -315,6 +315,60 @@ test('resolveMaestroNodeFromSnapshot prefers concrete Android tab rect over hidd
   });
 });
 
+test('resolveMaestroNodeFromSnapshot prefers exact Android tab label over normalized header icon text', () => {
+  const snapshot: SnapshotState = {
+    createdAt: Date.now(),
+    nodes: [
+      {
+        index: 1,
+        ref: 'e1',
+        type: 'android.widget.FrameLayout',
+        label: 'Search',
+        rect: { x: 810, y: 2054, width: 270, height: 132 },
+        enabled: true,
+        hittable: true,
+        depth: 16,
+      },
+      {
+        index: 2,
+        ref: 'e2',
+        type: 'android.widget.Button',
+        label: 'search',
+        rect: { x: 673, y: 165, width: 132, height: 132 },
+        enabled: true,
+        hittable: true,
+        depth: 22,
+      },
+      {
+        index: 3,
+        ref: 'e3',
+        type: 'android.widget.TextView',
+        label: 'search',
+        value: 'search',
+        rect: { x: 706, y: 198, width: 66, height: 66 },
+        enabled: true,
+        depth: 23,
+        parentIndex: 2,
+      },
+    ],
+  };
+
+  const target = resolveMaestroNodeFromSnapshot(
+    snapshot,
+    'label="Search" || text="Search" || id="Search"',
+    {},
+    'android',
+    { referenceWidth: 1080, referenceHeight: 2340 },
+    { promoteTapTarget: true },
+  );
+
+  expect(target).toMatchObject({
+    ok: true,
+    node: expect.objectContaining({ index: 1 }),
+    rect: { x: 810, y: 2054, width: 270, height: 132 },
+  });
+});
+
 test('resolveMaestroNodeFromSnapshot infers missing selected tab slot from tab-strip children', () => {
   const snapshot: SnapshotState = {
     createdAt: Date.now(),

src/compat/maestro/runtime-assertions.ts

@@ -149,16 +149,11 @@ export async function invokeMaestroAssertNotVisible(params: {
   let hiddenSamples = 0;
   let lastVisibleResponse: DaemonResponse | undefined;
   while (Date.now() - startedAt <= MAESTRO_ASSERTION_POLICY.assertNotVisibleTimeoutMs) {
-    const response = await params.invoke({
-      ...params.baseReq,
-      command: 'is',
-      positionals: ['visible', selector],
-      flags: { ...params.baseReq.flags, noRecord: true },
-    });
-    if (response.ok) {
+    const attempt = await readAssertNotVisibleAttempt(params, selector);
+    if (attempt.visible) {
       hiddenSamples = 0;
-      lastVisibleResponse = response;
-    } else if (isMaestroVisibilityMiss(response)) {
+      lastVisibleResponse = attempt.response;
+    } else if (attempt.hidden) {
       hiddenSamples += 1;
       const waitedMs = Date.now() - startedAt;
       if (
@@ -177,7 +172,7 @@ export async function invokeMaestroAssertNotVisible(params: {
         };
       }
     } else {
-      return response;
+      return attempt.response;
     }
     await sleep(MAESTRO_ASSERTION_POLICY.assertNotVisiblePollMs);
   }
@@ -188,6 +183,59 @@ export async function invokeMaestroAssertNotVisible(params: {
   });
 }
 
+async function readAssertNotVisibleAttempt(
+  params: {
+    baseReq: ReplayBaseRequest;
+    positionals: string[];
+    invoke: MaestroRuntimeInvoke;
+  },
+  selector: string,
+): Promise<
+  | { visible: true; hidden: false; response: DaemonResponse }
+  | { visible: false; hidden: true; response: DaemonResponse }
+  | { visible: false; hidden: false; response: DaemonResponse }
+> {
+  const response = await captureMaestroRawSnapshot(params);
+  if (!response.ok) return { visible: false, hidden: false, response };
+  const snapshot = readSnapshotState(response.data);
+  if (!snapshot) {
+    return {
+      visible: false,
+      hidden: false,
+      response: errorResponse('COMMAND_FAILED', 'Unable to read snapshot data for assertNotVisible.'),
+    };
+  }
+  const target = resolveVisibleMaestroNodeFromSnapshot(
+    snapshot,
+    selector,
+    readMaestroSelectorPlatform(params.baseReq.flags),
+    getSnapshotReferenceFrame(snapshot),
+  );
+  if (!target.ok) {
+    return {
+      visible: false,
+      hidden: true,
+      response: errorResponse('COMMAND_FAILED', target.message, { selector }),
+    };
+  }
+  return {
+    visible: true,
+    hidden: false,
+    response: {
+      ok: true,
+      data: {
+        selector,
+        matches: target.matches,
+        nodeIndex: target.node.index,
+        nodeType: target.node.type,
+        nodeLabel: target.node.label,
+        nodeIdentifier: target.node.identifier,
+        rect: target.rect,
+      },
+    },
+  };
+}
+
 export async function invokeMaestroWaitForAnimationToEnd(params: {
   baseReq: ReplayBaseRequest;
   positionals: string[];
@@ -215,14 +263,6 @@ export async function invokeMaestroWaitForAnimationToEnd(params: {
     : { ok: true, data: { stable: false, timeoutMs } };
 }
 
-function isMaestroVisibilityMiss(response: Extract<DaemonResponse, { ok: false }>): boolean {
-  const details = response.error.details;
-  return (
-    details?.command === 'is' &&
-    (details.reason === 'selector_not_found' || details.reason === 'predicate_failed')
-  );
-}
-
 function readAnimationPollResult(
   response: DaemonResponse,
   previousSignature: string | undefined,

src/compat/maestro/runtime-targets.ts

@@ -428,15 +428,35 @@ function selectLocalizedMaestroVisibleTextMatch(
   query: string,
 ): MaestroResolvedSnapshotMatch | null {
   const exactMatches = candidates.filter(
-    (candidate) => maestroVisibleTextMatchRank(candidate.node, query) <= 1,
+    (candidate) => maestroVisibleTextMatchRank(candidate.node, query) === 0,
   );
-  if (exactMatches.length < 2) return null;
+  if (exactMatches.length >= 2) {
+    const localizedExact = selectLocalizedMaestroVisibleTextMatchFromCandidates(
+      nodes,
+      exactMatches,
+      query,
+    );
+    if (localizedExact) return localizedExact;
+  }
+
+  const normalizedMatches = candidates.filter(
+    (candidate) => maestroVisibleTextMatchRank(candidate.node, query) === 1,
+  );
+  if (exactMatches.length > 0 || normalizedMatches.length < 2) return null;
+
+  return selectLocalizedMaestroVisibleTextMatchFromCandidates(nodes, normalizedMatches, query);
+}
 
+function selectLocalizedMaestroVisibleTextMatchFromCandidates(
+  nodes: SnapshotState['nodes'],
+  candidates: MaestroResolvedSnapshotMatch[],
+  query: string,
+): MaestroResolvedSnapshotMatch | null {
   const nodeByIndex = buildSnapshotNodeByIndex(nodes);
-  const localized = exactMatches.filter(
+  const localized = candidates.filter(
     (candidate) =>
       isLocalizedMaestroVisibleTextCandidate(candidate) &&
-      exactMatches.some((container) =>
+      candidates.some((container) =>
         isMaestroVisibleTextContainerForCandidate(nodes, container, candidate, nodeByIndex),
       ),
   );

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

@@ -888,11 +888,10 @@ test('runReplayScriptFile treats absent Maestro assertNotVisible targets as pass
     invoke: async (req) => {
       calls.push({ command: req.command, positionals: req.positionals, flags: req.flags });
       return {
-        ok: false,
-        error: {
-          code: 'COMMAND_FAILED',
-          message: 'Selector did not match',
-          details: { command: 'is', reason: 'selector_not_found' },
+        ok: true,
+        data: {
+          createdAt: 1,
+          nodes: [],
         },
       };
     },
@@ -902,14 +901,8 @@ test('runReplayScriptFile treats absent Maestro assertNotVisible targets as pass
   assert.deepEqual(
     calls.map((call) => [call.command, call.positionals]),
     [
-      [
-        'is',
-        ['visible', 'label="Archived banner" || text="Archived banner" || id="Archived banner"'],
-      ],
-      [
-        'is',
-        ['visible', 'label="Archived banner" || text="Archived banner" || id="Archived banner"'],
-      ],
+      ['snapshot', []],
+      ['snapshot', []],
     ],
   );
   assert.equal(calls[0]?.flags?.noRecord, true);
@@ -940,21 +933,34 @@ test('runReplayScriptFile propagates Maestro assertNotVisible infrastructure fai
 
 test('runReplayScriptFile waits briefly for Maestro assertNotVisible to stabilize', async () => {
   const calls: CapturedInvocation[] = [];
-  let visibleChecks = 0;
+  let snapshots = 0;
   const { response } = await runReplayFixture({
     label: 'maestro-assert-not-visible-stable',
     script: ['appId: demo.app', '---', '- assertNotVisible: Archived banner', ''].join('\n'),
     flags: { replayBackend: 'maestro' },
     invoke: async (req) => {
       calls.push({ command: req.command, positionals: req.positionals, flags: req.flags });
-      visibleChecks += 1;
-      if (visibleChecks === 1) return { ok: true, data: { pass: true } };
+      snapshots += 1;
+      if (snapshots === 1) {
+        return {
+          ok: true,
+          data: {
+            createdAt: 1,
+            nodes: [
+              {
+                index: 1,
+                label: 'Archived banner',
+                rect: { x: 10, y: 20, width: 180, height: 44 },
+              },
+            ],
+          },
+        };
+      }
       return {
-        ok: false,
-        error: {
-          code: 'COMMAND_FAILED',
-          message: 'is visible failed',
-          details: { command: 'is', reason: 'predicate_failed' },
+        ok: true,
+        data: {
+          createdAt: snapshots,
+          nodes: [],
         },
       };
     },