fix: align web snapshot and capability support (#828)

* fix: align web snapshot and capability support

* test: cover desktop snapshot presentation

Author: thymikee

src/core/__tests__/capabilities.test.ts

@@ -393,6 +393,7 @@ test('web supports only the initial browser interaction slice', () => {
       'click',
       'close',
       'fill',
+      'focus',
       'find',
       'get',
       'is',
@@ -416,7 +417,6 @@ test('web supports only the initial browser interaction slice', () => {
       'clipboard',
       'diff',
       'fling',
-      'focus',
       'home',
       'install',
       'install-from-source',

src/core/capabilities.ts

@@ -41,16 +41,20 @@ const synthesisGestureUnsupportedHint = (device: DeviceInfo): string | undefined
 const LINUX_DEVICE: KindMatrix = { device: true };
 const LINUX_NONE: KindMatrix = {};
 const WEB_DEVICE: KindMatrix = { device: true };
+const WEB_RUNTIME_COMMANDS = ['open', 'close'] as const;
+const WEB_QUERY_COMMANDS = ['find', 'get', 'is', 'screenshot', 'snapshot', 'wait'] as const;
+const WEB_INTERACTION_COMMANDS = ['click', 'fill', 'focus', 'press', 'scroll', 'type'] as const;
+const WEB_SUPPORTED_COMMANDS = new Set<string>([
+  ...WEB_RUNTIME_COMMANDS,
+  ...WEB_QUERY_COMMANDS,
+  ...WEB_INTERACTION_COMMANDS,
+]);
 const ALL_DEVICE_COMMAND_CAPABILITY = {
   apple: { simulator: true, device: true },
   android: { emulator: true, device: true, unknown: true },
   linux: LINUX_DEVICE,
 } as const satisfies CommandCapability;
-const WEB_COMMAND_CAPABILITY = {
-  ...ALL_DEVICE_COMMAND_CAPABILITY,
-  web: WEB_DEVICE,
-} as const satisfies CommandCapability;
-const APP_RUNTIME_CAPABILITY = WEB_COMMAND_CAPABILITY;
+const APP_RUNTIME_CAPABILITY = ALL_DEVICE_COMMAND_CAPABILITY;
 const APP_INVENTORY_CAPABILITY = {
   apple: { simulator: true, device: true },
   android: { emulator: true, device: true, unknown: true },
@@ -63,7 +67,7 @@ const APP_INSTALL_CAPABILITY = {
   supports: isNotMacOs,
 } as const satisfies CommandCapability;
 
-const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
+const BASE_COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
   // Apple simulator-only.
   alert: {
     // macOS desktop targets report kind=device, so this stays enabled here and the
@@ -130,7 +134,6 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
     apple: { simulator: true, device: true },
     android: { emulator: true, device: true, unknown: true },
     linux: LINUX_DEVICE,
-    web: WEB_DEVICE,
   },
   clipboard: {
     apple: { simulator: true, device: true },
@@ -154,20 +157,19 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
     apple: { simulator: true, device: true },
     android: { emulator: true, device: true, unknown: true },
     linux: LINUX_DEVICE,
-    web: WEB_DEVICE,
   },
   fling: {
     apple: { simulator: true, device: true },
     android: { emulator: true, device: true, unknown: true },
     linux: LINUX_NONE,
   },
-  snapshot: WEB_COMMAND_CAPABILITY,
+  snapshot: ALL_DEVICE_COMMAND_CAPABILITY,
   diff: ALL_DEVICE_COMMAND_CAPABILITY,
-  screenshot: WEB_COMMAND_CAPABILITY,
-  wait: WEB_COMMAND_CAPABILITY,
-  get: WEB_COMMAND_CAPABILITY,
-  find: WEB_COMMAND_CAPABILITY,
-  is: WEB_COMMAND_CAPABILITY,
+  screenshot: ALL_DEVICE_COMMAND_CAPABILITY,
+  wait: ALL_DEVICE_COMMAND_CAPABILITY,
+  get: ALL_DEVICE_COMMAND_CAPABILITY,
+  find: ALL_DEVICE_COMMAND_CAPABILITY,
+  is: ALL_DEVICE_COMMAND_CAPABILITY,
   focus: {
     apple: { simulator: true, device: true },
     android: { emulator: true, device: true, unknown: true },
@@ -208,7 +210,6 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
     apple: { simulator: true, device: true },
     android: { emulator: true, device: true, unknown: true },
     linux: LINUX_DEVICE,
-    web: WEB_DEVICE,
   },
   push: {
     apple: { simulator: true },
@@ -237,7 +238,6 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
     apple: { simulator: true, device: true },
     android: { emulator: true, device: true, unknown: true },
     linux: LINUX_DEVICE,
-    web: WEB_DEVICE,
   },
   swipe: {
     apple: { simulator: true, device: true },
@@ -256,9 +256,28 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
     android: { emulator: true, device: true, unknown: true },
     linux: LINUX_NONE,
   },
-  type: WEB_COMMAND_CAPABILITY,
+  type: ALL_DEVICE_COMMAND_CAPABILITY,
 };
 
+const COMMAND_CAPABILITY_MATRIX = addWebCommandCapabilities(BASE_COMMAND_CAPABILITY_MATRIX);
+
+function addWebCommandCapabilities(
+  matrix: Record<string, CommandCapability>,
+): Record<string, CommandCapability> {
+  const result: Record<string, CommandCapability> = {};
+  for (const [command, capability] of Object.entries(matrix)) {
+    result[command] = WEB_SUPPORTED_COMMANDS.has(command)
+      ? { ...capability, web: WEB_DEVICE }
+      : capability;
+  }
+  for (const command of WEB_SUPPORTED_COMMANDS) {
+    if (!(command in matrix)) {
+      throw new Error(`Web command "${command}" missing from capability matrix`);
+    }
+  }
+  return result;
+}
+
 export function isCommandSupportedOnDevice(command: string, device: DeviceInfo): boolean {
   const capability = COMMAND_CAPABILITY_MATRIX[command];
   if (!capability) return true;

src/utils/__tests__/output.test.ts

@@ -121,6 +121,71 @@ test('formatSnapshotText summarizes large Android TextView surfaces with preview
   assert.match(text, /\[truncated\]/);
 });
 
+test('formatSnapshotText keeps web backend output as a full tree', () => {
+  const text = withNoColor(() =>
+    formatSnapshotText({
+      backend: 'web',
+      nodes: [
+        {
+          ref: 'e1',
+          index: 0,
+          depth: 0,
+          role: 'document',
+          rect: { x: 0, y: 0, width: 390, height: 844 },
+        },
+        {
+          ref: 'e2',
+          index: 1,
+          depth: 1,
+          parentIndex: 0,
+          role: 'button',
+          label: 'Offscreen web action',
+          rect: { x: 0, y: 1200, width: 140, height: 44 },
+        },
+      ],
+      truncated: false,
+    }),
+  );
+
+  assert.match(text, /Snapshot: 2 nodes/);
+  assert.match(text, /Offscreen web action/);
+  assert.doesNotMatch(text, /visible nodes/);
+  assert.doesNotMatch(text, /\[off-screen below\]/);
+});
+
+test('formatSnapshotText keeps linux-atspi backend output as a full tree', () => {
+  const text = withNoColor(() =>
+    formatSnapshotText({
+      backend: 'linux-atspi',
+      nodes: [
+        {
+          ref: 'e1',
+          index: 0,
+          depth: 0,
+          type: 'Window',
+          label: 'Browser',
+          rect: { x: 0, y: 0, width: 390, height: 844 },
+        },
+        {
+          ref: 'e2',
+          index: 1,
+          depth: 1,
+          parentIndex: 0,
+          role: 'button',
+          label: 'Offscreen desktop action',
+          rect: { x: 0, y: 1200, width: 140, height: 44 },
+        },
+      ],
+      truncated: false,
+    }),
+  );
+
+  assert.match(text, /Snapshot: 2 nodes/);
+  assert.match(text, /Offscreen desktop action/);
+  assert.doesNotMatch(text, /visible nodes/);
+  assert.doesNotMatch(text, /\[off-screen below\]/);
+});
+
 test('formatSnapshotText omits unlabeled group wrappers while preserving labeled groups', () => {
   const text = withNoColor(() =>
     formatSnapshotText({

src/utils/__tests__/snapshot-visibility.test.ts

@@ -0,0 +1,53 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { buildSnapshotVisibility } from '../snapshot-visibility.ts';
+import type { SnapshotNode } from '../snapshot.ts';
+
+const FULLSCREEN_ROOT = { x: 0, y: 0, width: 390, height: 844 };
+const OFFSCREEN_RECT = { x: 0, y: 1200, width: 120, height: 44 };
+
+function nodesWithOffscreenChild(): SnapshotNode[] {
+  return [
+    {
+      ref: 'e1',
+      index: 0,
+      depth: 0,
+      type: 'Window',
+      role: 'document',
+      rect: FULLSCREEN_ROOT,
+    },
+    {
+      ref: 'e2',
+      index: 1,
+      depth: 1,
+      parentIndex: 0,
+      type: 'web.button',
+      role: 'button',
+      label: 'Offscreen action',
+      rect: OFFSCREEN_RECT,
+    },
+  ];
+}
+
+test('buildSnapshotVisibility treats web snapshots as full-tree output', () => {
+  const visibility = buildSnapshotVisibility({
+    nodes: nodesWithOffscreenChild(),
+    backend: 'web',
+  });
+
+  assert.deepEqual(visibility, {
+    partial: false,
+    visibleNodeCount: 2,
+    totalNodeCount: 2,
+    reasons: [],
+  });
+});
+
+test('buildSnapshotVisibility keeps legacy missing backend snapshots in mobile presentation mode', () => {
+  const visibility = buildSnapshotVisibility({ nodes: nodesWithOffscreenChild() });
+
+  assert.equal(visibility.partial, true);
+  assert.equal(visibility.visibleNodeCount, 1);
+  assert.equal(visibility.totalNodeCount, 2);
+  assert.deepEqual(visibility.reasons, ['offscreen-nodes']);
+});

src/utils/output.ts

@@ -6,7 +6,14 @@ import {
 import { AppError, normalizeError, type NormalizedError } from './errors.ts';
 import { detectPossibleRepeatedNavSubtree } from './repeated-nav-subtree.ts';
 import { buildSnapshotDisplayLines, formatSnapshotLine } from './snapshot-lines.ts';
-import type { Rect, SnapshotNode, SnapshotUnchanged, SnapshotVisibility } from './snapshot.ts';
+import {
+  isSnapshotBackend,
+  usesMobileSnapshotPresentation,
+  type Rect,
+  type SnapshotNode,
+  type SnapshotUnchanged,
+  type SnapshotVisibility,
+} from './snapshot.ts';
 import type { MovementRange } from './screenshot-diff-ocr.ts';
 import type { ScreenshotDiffResult } from './screenshot-diff.ts';
 import type { ScreenshotDiffRegion } from './screenshot-diff-regions.ts';
@@ -62,7 +69,8 @@ export function formatSnapshotText(
 ): string {
   const rawNodes = data.nodes;
   const nodes = Array.isArray(rawNodes) ? (rawNodes as SnapshotNode[]) : [];
-  const backend = typeof data.backend === 'string' ? data.backend : undefined;
+  const backend = isSnapshotBackend(data.backend) ? data.backend : undefined;
+  const useMobilePresentation = usesMobileSnapshotPresentation(backend);
   const helperPresentation = buildAndroidHelperPresentationInput(data, nodes, options);
   const prefix = formatSnapshotMetaPrefix(data);
   const notices = buildSnapshotNotices(data, nodes, options, helperPresentation);
@@ -72,13 +80,13 @@ export function formatSnapshotText(
     return `${prefix}${noticesBlock}${formatUnchangedSnapshotText(unchanged)}\n`;
   }
   const visiblePresentation =
-    options.raw || backend === 'macos-helper'
+    options.raw || !useMobilePresentation
       ? null
       : buildMobileSnapshotPresentation(helperPresentation.nodes);
   const truncated = Boolean(data.truncated);
   const displayedNodes = visiblePresentation?.nodes ?? nodes;
   const visibility =
-    options.raw || backend === 'macos-helper'
+    options.raw || !useMobilePresentation
       ? null
       : readSnapshotVisibility(
           data,

src/utils/snapshot-visibility.ts

@@ -1,17 +1,17 @@
 import { buildMobileSnapshotPresentation } from './mobile-snapshot-semantics.ts';
-import type { SnapshotBackend, SnapshotState, SnapshotVisibility } from './snapshot.ts';
-
-function isDesktopBackend(backend: SnapshotBackend | undefined): boolean {
-  return backend === 'macos-helper' || backend === 'linux-atspi';
-}
+import {
+  usesMobileSnapshotPresentation,
+  type SnapshotState,
+  type SnapshotVisibility,
+} from './snapshot.ts';
 
 export function buildSnapshotVisibility(params: {
   nodes: SnapshotState['nodes'];
   backend?: SnapshotState['backend'];
   snapshotRaw?: boolean;
 }): SnapshotVisibility {
   const { nodes, backend, snapshotRaw } = params;
-  if (snapshotRaw || isDesktopBackend(backend)) {
+  if (snapshotRaw || !usesMobileSnapshotPresentation(backend)) {
     return {
       partial: false,
       visibleNodeCount: nodes.length,

src/utils/snapshot.ts

@@ -64,6 +64,20 @@ export type SnapshotNode = RawSnapshotNode & {
 
 export type SnapshotBackend = 'xctest' | 'android' | 'macos-helper' | 'linux-atspi' | 'web';
 
+export function isSnapshotBackend(value: unknown): value is SnapshotBackend {
+  return (
+    value === 'xctest' ||
+    value === 'android' ||
+    value === 'macos-helper' ||
+    value === 'linux-atspi' ||
+    value === 'web'
+  );
+}
+
+export function usesMobileSnapshotPresentation(backend: SnapshotBackend | undefined): boolean {
+  return backend === undefined || backend === 'xctest' || backend === 'android';
+}
+
 export type SnapshotState = {
   nodes: SnapshotNode[];
   createdAt: number;