test(capture-kit,maestro,selectors,provider-limrun): cover shared-package CRAP functions through public entries

packages/capture-kit/src/png-rgb-difference.test.ts

@@ -0,0 +1,66 @@
+import { expect, test } from 'vitest';
+import { computePngRgbDifference, type PngRgbImage } from './png-rgb-difference.ts';
+
+function image(width: number, height: number, data: number[]): PngRgbImage {
+  return { width, height, data: Uint8Array.from(data) };
+}
+
+test('computePngRgbDifference answers 0 for pixel-identical images and ignores alpha', () => {
+  const first = image(2, 1, [10, 20, 30, 0, 200, 100, 50, 255]);
+  const second = image(2, 1, [10, 20, 30, 255, 200, 100, 50, 0]);
+
+  expect(computePngRgbDifference(first, second)).toEqual({
+    status: 'compared',
+    differencePercent: 0,
+    first: { width: 2, height: 1, dataLength: 8 },
+    second: { width: 2, height: 1, dataLength: 8 },
+  });
+});
+
+test('computePngRgbDifference normalizes the absolute RGB difference over 3 x 255 per pixel', () => {
+  // One pixel differs by 255 on one channel: 100 * 255 / (3 * 255 * 1) = 33 1/3 %.
+  const black = image(1, 1, [0, 0, 0, 255]);
+  const red = image(1, 1, [255, 0, 0, 255]);
+  const result = computePngRgbDifference(black, red);
+
+  expect(result.status).toBe('compared');
+  if (result.status !== 'compared') return;
+  expect(result.differencePercent).toBeCloseTo(100 / 3, 10);
+});
+
+test('computePngRgbDifference reports a dimension mismatch without touching pixel data', () => {
+  const result = computePngRgbDifference(
+    image(2, 1, [0, 0, 0, 255, 0, 0, 0, 255]),
+    image(1, 2, [0, 0, 0, 255, 0, 0, 0, 255]),
+  );
+
+  expect(result).toEqual({
+    status: 'dimension_mismatch',
+    first: { width: 2, height: 1, dataLength: 8 },
+    second: { width: 1, height: 2, dataLength: 8 },
+  });
+});
+
+test('computePngRgbDifference reports mismatched RGBA buffer lengths', () => {
+  // Same declared dimensions, but one side carries fewer RGBA rows than the other.
+  const result = computePngRgbDifference(
+    image(2, 1, [0, 0, 0, 255]),
+    image(2, 1, [0, 0, 0, 255, 0, 0, 0, 255]),
+  );
+
+  expect(result).toEqual({
+    status: 'data_length_mismatch',
+    first: { width: 2, height: 1, dataLength: 4 },
+    second: { width: 2, height: 1, dataLength: 8 },
+  });
+});
+
+test('computePngRgbDifference refuses a buffer that disagrees with its own dimensions', () => {
+  // Equal lengths on both sides, but one RGBA row cannot cover a 2 x 1 image.
+  const short = image(2, 1, [0, 0, 0, 255]);
+  expect(computePngRgbDifference(short, image(2, 1, [0, 0, 0, 255]))).toEqual({
+    status: 'data_length_mismatch',
+    first: { width: 2, height: 1, dataLength: 4 },
+    second: { width: 2, height: 1, dataLength: 4 },
+  });
+});

packages/capture-kit/src/react-native-overlay.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from 'vitest';
+import type { SnapshotNode } from '@agent-device/kernel/snapshot';
+import {
+  analyzeReactNativeOverlay,
+  formatReactNativeOverlayWarning,
+} from './react-native-overlay.ts';
+
+/**
+ * Exercises the collapsed-warning scoring seam through the package's public analyzer. The
+ * scoring comparators only run once two or more banner candidates are tied for dismissal, so
+ * the single-banner daemon-handler tests never reach them.
+ */
+
+function node(overrides: Partial<SnapshotNode> & { ref: string; index: number }): SnapshotNode {
+  return { kind: 'Unknown', ...overrides } as SnapshotNode;
+}
+
+const collapsedBannerRect = { x: 0, y: 794, width: 402, height: 52 };
+
+describe('React Native collapsed warning dismissal', () => {
+  test('a hittable banner wins dismissal over a non-hittable one at any position', () => {
+    const state = analyzeReactNativeOverlay([
+      node({
+        index: 0,
+        ref: 'e1',
+        label: '!, Warning at the very bottom',
+        rect: { ...collapsedBannerRect, y: 900 },
+        hittable: false,
+      }),
+      node({
+        index: 1,
+        ref: 'e2',
+        label: '!, Warning above it',
+        rect: { ...collapsedBannerRect, y: 794 },
+        hittable: true,
+      }),
+    ]);
+
+    expect(state.detected).toBe(true);
+    // Hittability outranks position: the tappable banner wins even though the other sits lower.
+    expect(state.primaryAction).toMatchObject({
+      action: 'close-collapsed-banner',
+      ref: 'e2',
+      label: '!, Warning above it',
+    });
+  });
+
+  test('between two equally hittable banners the wider one is dismissed first', () => {
+    const state = analyzeReactNativeOverlay([
+      node({
+        index: 0,
+        ref: 'e1',
+        label: '!, Narrow warning',
+        rect: { x: 0, y: 500, width: 200, height: 52 },
+        hittable: true,
+      }),
+      node({
+        index: 1,
+        ref: 'e2',
+        label: '!, Wide warning',
+        rect: { x: 0, y: 400, width: 402, height: 52 },
+        hittable: true,
+      }),
+    ]);
+
+    expect(state.primaryAction?.ref).toBe('e2');
+  });
+
+  test('two banners without a hittable fact fall back to width and then the lower position', () => {
+    const state = analyzeReactNativeOverlay([
+      node({
+        index: 0,
+        ref: 'e1',
+        label: '!, Upper warning',
+        rect: { x: 0, y: 300, width: 402, height: 52 },
+      }),
+      node({
+        index: 1,
+        ref: 'e2',
+        label: '!, Lower warning',
+        rect: { x: 0, y: 794, width: 402, height: 52 },
+      }),
+    ]);
+
+    // Both score 0 on hittable and width, so the greater y — the banner the user sees last — wins.
+    expect(state.primaryAction?.ref).toBe('e2');
+  });
+
+  test('formatReactNativeOverlayWarning answers only for a detected overlay', () => {
+    const warning = formatReactNativeOverlayWarning([
+      node({
+        index: 0,
+        ref: 'e1',
+        label: '!, Open debugger to view warnings.',
+        rect: collapsedBannerRect,
+        hittable: true,
+      }),
+    ]);
+    expect(warning).toContain('agent-device react-native dismiss-overlay');
+
+    expect(formatReactNativeOverlayWarning([node({ index: 0, ref: 'e1', label: 'Save' })])).toBe(
+      undefined,
+    );
+  });
+});

packages/maestro/src/internal/__tests__/facade-failure-suggestions.test.ts

@@ -0,0 +1,219 @@
+import { describe, expect, test } from 'vitest';
+import type { SnapshotNode, SnapshotState } from '@agent-device/kernel/snapshot';
+import {
+  collectMaestroFailureSuggestions,
+  executeMaestroFlow,
+  inspectMaestroFlow,
+  type MaestroRuntimePort,
+} from '../../index.ts';
+
+/**
+ * Drives `collectMaestroFailureSuggestions` through the real engine: the flow is parsed, planned,
+ * and executed against a port whose every call fails, so the failure event carries the same
+ * runtime command the daemon's divergence report ranks against a snapshot.
+ */
+
+const noMaestroSources = () => {
+  throw new Error('test flows declare no includes');
+};
+
+function failingPort(): MaestroRuntimePort {
+  const error = new Error('fixture command failed');
+  return {
+    execute: async () => {
+      throw error;
+    },
+    observe: async () => {
+      throw error;
+    },
+  };
+}
+
+function snapshot(nodes: SnapshotNode[]): SnapshotState {
+  return { createdAt: 0, nodes };
+}
+
+const saveButton: SnapshotNode = {
+  ref: 'e1',
+  index: 0,
+  type: 'Button',
+  identifier: 'save',
+  label: 'Save',
+  rect: { x: 0, y: 0, width: 100, height: 40 },
+  hittable: true,
+};
+
+async function suggestionsFor(
+  flowYaml: string,
+  platform: 'android' | 'ios' | 'web',
+  nodes: SnapshotNode[],
+) {
+  const flow = inspectMaestroFlow(flowYaml, '/flows/suggestions.yaml');
+  const outcome = await executeMaestroFlow(flow, failingPort(), {
+    platform,
+    readSource: noMaestroSources,
+  });
+  if (outcome.ok || !outcome.failure) throw new Error('expected the flow to fail');
+  return collectMaestroFailureSuggestions(outcome.failure, snapshot(nodes));
+}
+
+describe('Maestro failure suggestion queries', () => {
+  test('a target tapOn suggests ranked candidates for its selector', async () => {
+    const suggestions = await suggestionsFor(
+      ['appId: com.example.app', '---', '- tapOn:', '    id: save', ''].join('\n'),
+      'android',
+      [saveButton],
+    );
+    expect(suggestions.map(({ node, basis }) => [node.ref, basis])).toEqual([['e1', 'id']]);
+  });
+
+  test('a coordinate tapOn has no selector to suggest from', async () => {
+    const suggestions = await suggestionsFor(
+      ['appId: com.example.app', '---', '- tapOn:', '    point: 50%,50%', ''].join('\n'),
+      'android',
+      [saveButton],
+    );
+    expect(suggestions).toEqual([]);
+  });
+
+  test.each([
+    ['doubleTapOn', '- doubleTapOn:\n    id: save\n'],
+    ['longPressOn', '- longPressOn:\n    id: save\n'],
+    ['assertVisible', '- assertVisible:\n    id: save\n'],
+    ['assertNotVisible', '- assertNotVisible:\n    id: save\n'],
+    ['scrollUntilVisible', '- scrollUntilVisible:\n    element:\n      id: save\n'],
+  ])('%s failure suggests from its target selector', async (_name, authored) => {
+    const suggestions = await suggestionsFor(
+      `appId: com.example.app\n---\n${authored}`,
+      'android',
+      [saveButton],
+    );
+    expect(suggestions.map(({ node, basis }) => [node.ref, basis])).toEqual([['e1', 'id']]);
+  });
+
+  test('a coordinate doubleTapOn has no selector to suggest from', async () => {
+    const suggestions = await suggestionsFor(
+      ['appId: com.example.app', '---', '- doubleTapOn:', '    point: 100,200', ''].join('\n'),
+      'android',
+      [saveButton],
+    );
+    expect(suggestions).toEqual([]);
+  });
+
+  test('extendedWaitUntil suggests from its visible condition', async () => {
+    const suggestions = await suggestionsFor(
+      [
+        'appId: com.example.app',
+        '---',
+        '- extendedWaitUntil:',
+        '    visible:',
+        '      id: save',
+        '    timeout: 1',
+        '',
+      ].join('\n'),
+      'android',
+      [saveButton],
+    );
+    expect(suggestions.map(({ node }) => node.ref)).toEqual(['e1']);
+  });
+
+  test('extendedWaitUntil falls back to its notVisible condition', async () => {
+    const suggestions = await suggestionsFor(
+      [
+        'appId: com.example.app',
+        '---',
+        '- extendedWaitUntil:',
+        '    notVisible:',
+        '      id: save',
+        '    timeout: 1',
+        '',
+      ].join('\n'),
+      'android',
+      [saveButton],
+    );
+    expect(suggestions.map(({ node }) => node.ref)).toEqual(['e1']);
+  });
+
+  test('a target swipe suggests from its from-selector', async () => {
+    const suggestions = await suggestionsFor(
+      [
+        'appId: com.example.app',
+        '---',
+        '- swipe:',
+        '    direction: UP',
+        '    from:',
+        '      id: save',
+        '',
+      ].join('\n'),
+      'android',
+      [saveButton],
+    );
+    expect(suggestions.map(({ node }) => node.ref)).toEqual(['e1']);
+  });
+
+  test('a screen swipe has no selector to suggest from', async () => {
+    const suggestions = await suggestionsFor(
+      ['appId: com.example.app', '---', '- swipe:', '    direction: UP', ''].join('\n'),
+      'android',
+      [saveButton],
+    );
+    expect(suggestions).toEqual([]);
+  });
+
+  test('a command without any target yields no suggestions', async () => {
+    const suggestions = await suggestionsFor(
+      ['appId: com.example.app', '---', '- back', ''].join('\n'),
+      'android',
+      [saveButton],
+    );
+    expect(suggestions).toEqual([]);
+  });
+
+  test('suggestions stay empty on a platform the snapshot ranking does not cover', async () => {
+    const suggestions = await suggestionsFor(
+      ['appId: com.example.app', '---', '- assertVisible:', '    id: save', ''].join('\n'),
+      'web',
+      [saveButton],
+    );
+    expect(suggestions).toEqual([]);
+  });
+
+  test('a text selector against a label match reports the `label` basis', async () => {
+    const suggestions = await suggestionsFor(
+      ['appId: com.example.app', '---', '- assertVisible:', '    text: Save', ''].join('\n'),
+      'android',
+      [{ ...saveButton, identifier: undefined }],
+    );
+    // With no identifier to match, the candidate matches on its label, so the basis is `label`.
+    expect(suggestions.map(({ basis }) => basis)).toEqual(['label']);
+  });
+
+  test('a text selector the candidate carries as visible text reports the `id` basis', async () => {
+    const suggestions = await suggestionsFor(
+      ['appId: com.example.app', '---', '- assertVisible:', '    text: Save', ''].join('\n'),
+      'android',
+      [
+        {
+          ref: 'e1',
+          index: 0,
+          type: 'Button',
+          // No label: the text "Save" is the node's identifier, i.e. its visible text.
+          identifier: 'Save',
+          rect: { x: 0, y: 0, width: 100, height: 40 },
+          hittable: true,
+        },
+      ],
+    );
+    expect(suggestions.map(({ basis }) => basis)).toEqual(['id']);
+  });
+
+  test('a selector with neither text nor id still ranks nodes under the `other` basis', async () => {
+    const suggestions = await suggestionsFor(
+      ['appId: com.example.app', '---', '- assertVisible:', '    enabled: true', ''].join('\n'),
+      'android',
+      [{ ...saveButton, identifier: undefined }],
+    );
+    expect(suggestions.length).toBeGreaterThan(0);
+    expect(suggestions.every(({ basis }) => basis === 'other')).toBe(true);
+  });
+});