fix: improve Android helper snapshot stability (#529)

Author: thymikee

src/__tests__/runtime-snapshot.test.ts

@@ -108,6 +108,24 @@ test('runtime snapshot emits filtered Android guidance from backend analysis', a
   ]);
 });
 
+test('runtime snapshot warns when Android helper falls back to stock UIAutomator', async () => {
+  const device = createSnapshotOnlyDevice({
+    nodes: [{ ref: 'e1', index: 0, depth: 0, type: 'Window', label: 'Home' }],
+    truncated: false,
+    backend: 'android',
+    androidSnapshot: {
+      backend: 'uiautomator-dump',
+      fallbackReason: 'helper artifact missing',
+    },
+  });
+
+  const result = await device.capture.snapshot({ session: 'default', interactiveOnly: true });
+
+  assert.deepEqual(result.warnings, [
+    'Android snapshot helper unavailable; using stock UIAutomator dump, which can time out on busy React Native UIs. Reason: helper artifact missing',
+  ]);
+});
+
 test('runtime snapshot warns when Android hierarchy looks like a React Native overlay', async () => {
   const device = createSnapshotOnlyDevice({
     nodes: [

src/commands/capture-snapshot.ts

@@ -194,6 +194,7 @@ function buildSnapshotWarnings(params: {
   const warnings = [...(params.result.warnings ?? [])];
   const interactiveOnly = params.options.interactiveOnly === true;
   const analysis = params.result.analysis;
+  const androidSnapshot = params.result.androidSnapshot;
 
   if (
     params.snapshot.backend === 'android' &&
@@ -216,6 +217,15 @@ function buildSnapshotWarnings(params: {
     }
   }
 
+  if (androidSnapshot?.backend === 'uiautomator-dump') {
+    const reason = androidSnapshot.fallbackReason
+      ? ` Reason: ${androidSnapshot.fallbackReason}`
+      : '';
+    warnings.push(
+      `Android snapshot helper unavailable; using stock UIAutomator dump, which can time out on busy React Native UIs.${reason}`,
+    );
+  }
+
   if (hasReactNativeOverlay(params.snapshot.nodes)) {
     warnings.push(
       'Possible React Native warning/error overlay detected. Capture screenshot --overlay-refs, check react-devtools errors if connected, dismiss Dismiss/Close only if unrelated, re-snapshot, and report it.',

src/platforms/android/__tests__/snapshot.test.ts

@@ -260,7 +260,7 @@ test('snapshotAndroid uses injected helper artifact before stock uiautomator', a
   assert.equal(result.androidSnapshot.installReason, 'current');
   assert.equal(result.androidSnapshot.captureMode, 'interactive-windows');
   assert.equal(result.androidSnapshot.windowCount, 1);
-  assert.deepEqual(timeouts, [30000, 13000]);
+  assert.deepEqual(timeouts, [30000, 30000]);
   assert.equal(mockRunCmd.mock.calls.length, 0);
 });
 
@@ -347,6 +347,45 @@ test('snapshotAndroid falls back to stock uiautomator when helper fails', async
   assert.equal(mockRunCmd.mock.calls.length, 0);
 });
 
+test('snapshotAndroid preserves helper failure reason when stock fallback fails', async () => {
+  const helperAdb: AndroidAdbExecutor = async (args) => {
+    if (args.includes('--show-versioncode')) {
+      return {
+        exitCode: 0,
+        stdout: 'package:com.callstack.agentdevice.snapshothelper versionCode:13003',
+        stderr: '',
+      };
+    }
+    if (args.includes('exec-out')) {
+      throw new AppError('COMMAND_FAILED', 'stock dump timed out', { hint: 'stock hint' });
+    }
+    return { exitCode: 1, stdout: '', stderr: 'instrumentation failed' };
+  };
+
+  await assert.rejects(
+    () =>
+      snapshotAndroid(device, {
+        helperAdb,
+        helperArtifact: {
+          apkPath: '/tmp/helper.apk',
+          manifest: helperManifest,
+        },
+      }),
+    (error) => {
+      assert.ok(error instanceof AppError);
+      assert.match(error.message, /stock dump timed out/);
+      assert.match(error.message, /Android snapshot helper failed before stock fallback/);
+      assert.match(error.message, /failed before returning parseable output/);
+      assert.equal(
+        error.details?.androidSnapshotHelperFallbackReason,
+        'Android snapshot helper failed before returning parseable output',
+      );
+      assert.equal(error.details?.hint, 'stock hint');
+      return true;
+    },
+  );
+});
+
 test('snapshotAndroid re-probes helper install after helper capture failure', async () => {
   let versionProbeCount = 0;
   let instrumentAttempts = 0;

src/platforms/android/snapshot.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { withRetry } from '../../utils/retry.ts';
-import { AppError, normalizeError } from '../../utils/errors.ts';
+import { AppError, normalizeError, toAppErrorCode } from '../../utils/errors.ts';
 import type { DeviceInfo } from '../../utils/device.ts';
 import { findProjectRoot, readVersion } from '../../utils/version.ts';
 import {
@@ -39,7 +39,9 @@ import {
 
 const UI_HIERARCHY_DUMP_TIMEOUT_MS = 8_000;
 const HELPER_INSTALL_TIMEOUT_MS = 30_000;
-const HELPER_COMMAND_TIMEOUT_MS = UI_HIERARCHY_DUMP_TIMEOUT_MS + 5_000;
+// Large React Native trees can legitimately exceed the stock dump timeout while
+// the helper is still making progress; keep this below the full fallback path.
+const HELPER_COMMAND_TIMEOUT_MS = 30_000;
 
 type AndroidSnapshotOptions = SnapshotOptions & {
   helperArtifact?: AndroidSnapshotHelperArtifact;
@@ -182,15 +184,41 @@ async function captureStockUiHierarchy(
   fallbackReason?: string,
   adb?: AndroidAdbExecutor,
 ): Promise<{ xml: string; metadata: AndroidSnapshotBackendMetadata }> {
+  let xml: string;
+  try {
+    xml = await dumpUiHierarchy(device, adb);
+  } catch (error) {
+    if (fallbackReason) {
+      throw enrichStockSnapshotFailureWithHelperReason(error, fallbackReason);
+    }
+    throw error;
+  }
   return {
-    xml: await dumpUiHierarchy(device, adb),
+    xml,
     metadata: {
       backend: 'uiautomator-dump',
       ...(fallbackReason ? { fallbackReason } : {}),
     },
   };
 }
 
+function enrichStockSnapshotFailureWithHelperReason(
+  error: unknown,
+  fallbackReason: string,
+): AppError {
+  const normalized = normalizeError(error);
+  return new AppError(
+    toAppErrorCode(normalized.code),
+    `${normalized.message} Android snapshot helper failed before stock fallback: ${fallbackReason}`,
+    {
+      ...normalized.details,
+      androidSnapshotHelperFallbackReason: fallbackReason,
+      ...(normalized.hint ? { hint: normalized.hint } : {}),
+    },
+    error,
+  );
+}
+
 function getAndroidSnapshotHelperDeviceKey(device: DeviceInfo): string {
   // Emulator serials are port-based and can be reused after restart; capture failure invalidates
   // this key before falling back so stale process-local entries self-heal on the next snapshot.

src/utils/__tests__/args.test.ts

@@ -970,6 +970,10 @@ test('usageForCommand resolves react-devtools help topic', () => {
     /agent-device react-devtools profile diff before\.json after\.json --limit 10/,
   );
   assert.match(help, /render causes and changed props\/state\/hooks/);
+  assert.match(help, /logs clear --restart before the first logs mark/);
+  assert.match(help, /agent-device logs mark "before catalog search"/);
+  assert.match(help, /Do not write agent-devtools/);
+  assert.match(help, /agent-device network dump --include headers/);
   assert.match(help, /@c refs reset after reload\/remount/);
   assert.match(help, /isolated --state-dir/);
   assert.match(help, /local service tunnel/);

src/utils/__tests__/output.test.ts

@@ -301,6 +301,185 @@ test('formatSnapshotText keeps zero-height visible nodes out of off-screen summa
   assert.match(text, /\[off-screen below\] 1 interactive item: "Later"/);
 });
 
+test('formatSnapshotText collapses inactive Android helper nodes in human output', () => {
+  const nodes = [
+    {
+      ref: 'e1',
+      index: 0,
+      depth: 0,
+      type: 'Window',
+      rect: { x: 0, y: 0, width: 390, height: 844 },
+    },
+    {
+      ref: 'e2',
+      index: 1,
+      depth: 1,
+      parentIndex: 0,
+      type: 'android.widget.Button',
+      label: 'Alice, Today, filed the expense',
+      rect: { x: 0, y: 420, width: 390, height: 96 },
+      hittable: true,
+    },
+    {
+      ref: 'e3',
+      index: 2,
+      depth: 2,
+      parentIndex: 1,
+      type: 'android.widget.Button',
+      label: 'alice@example.com',
+      rect: { x: 16, y: 432, width: 48, height: 48 },
+      hittable: true,
+    },
+    {
+      ref: 'e4',
+      index: 3,
+      depth: 2,
+      parentIndex: 1,
+      type: 'android.widget.Button',
+      label: 'alice@example.com',
+      rect: { x: 80, y: 432, width: 120, height: 48 },
+      hittable: true,
+    },
+    {
+      ref: 'e5',
+      index: 4,
+      depth: 3,
+      parentIndex: 3,
+      type: 'android.widget.TextView',
+      label: 'Alice',
+      rect: { x: 80, y: 432, width: 120, height: 48 },
+    },
+    {
+      ref: 'e6',
+      index: 5,
+      depth: 1,
+      parentIndex: 0,
+      type: 'android.widget.Button',
+      label: 'Invisible stale action',
+      rect: { x: 0, y: 160, width: 390, height: 0 },
+      hittable: true,
+    },
+    {
+      ref: 'e7',
+      index: 6,
+      depth: 1,
+      parentIndex: 0,
+      type: 'android.widget.EditText',
+      label: 'Write something...',
+      identifier: 'composer',
+      rect: { x: 72, y: 760, width: 240, height: 44 },
+      hittable: true,
+    },
+    {
+      ref: 'e8',
+      index: 7,
+      depth: 1,
+      parentIndex: 0,
+      type: 'android.view.View',
+      label: 'Dashboard',
+      rect: { x: 0, y: 720, width: 78, height: 96 },
+      hittable: true,
+    },
+    {
+      ref: 'e9',
+      index: 8,
+      depth: 2,
+      parentIndex: 7,
+      type: 'android.widget.TextView',
+      label: 'Dashboard',
+      rect: { x: 20, y: 780, width: 40, height: 24 },
+    },
+    {
+      ref: 'e10',
+      index: 9,
+      depth: 1,
+      parentIndex: 0,
+      type: 'android.view.View',
+      label: 'Messages. Your review is required',
+      rect: { x: 78, y: 720, width: 78, height: 96 },
+      hittable: true,
+    },
+    {
+      ref: 'e11',
+      index: 10,
+      depth: 2,
+      parentIndex: 9,
+      type: 'android.widget.TextView',
+      label: 'Messages',
+      rect: { x: 98, y: 780, width: 40, height: 24 },
+    },
+    {
+      ref: 'e12',
+      index: 11,
+      depth: 1,
+      parentIndex: 0,
+      type: 'android.view.View',
+      label: 'Billing',
+      rect: { x: 156, y: 720, width: 78, height: 96 },
+      hittable: true,
+    },
+    {
+      ref: 'e13',
+      index: 12,
+      depth: 2,
+      parentIndex: 11,
+      type: 'android.widget.TextView',
+      label: 'Billing',
+      rect: { x: 176, y: 780, width: 40, height: 24 },
+    },
+    {
+      ref: 'e14',
+      index: 13,
+      depth: 1,
+      parentIndex: 0,
+      type: 'android.view.View',
+      label: 'Profile, My settings.',
+      rect: { x: 312, y: 720, width: 78, height: 96 },
+      hittable: true,
+    },
+    {
+      ref: 'e15',
+      index: 14,
+      depth: 2,
+      parentIndex: 13,
+      type: 'android.widget.TextView',
+      label: 'Profile',
+      rect: { x: 332, y: 780, width: 40, height: 24 },
+    },
+  ];
+  const text = withNoColor(() =>
+    formatSnapshotText({
+      nodes,
+      truncated: false,
+      androidSnapshot: { backend: 'android-helper' },
+    }),
+  );
+
+  assert.match(text, /Snapshot: 4 visible nodes \(15 total\)/);
+  assert.match(text, /Collapsed 11 inactive Android helper nodes from text output/);
+  assert.match(text, /@e3 \[button\] "alice@example\.com"/);
+  assert.doesNotMatch(text, /@e4 \[button\] "alice@example\.com"/);
+  assert.doesNotMatch(text, /Invisible stale action/);
+  assert.doesNotMatch(text, /\[group\] "Dashboard"/);
+  assert.doesNotMatch(text, /\[group\] "Messages/);
+  assert.doesNotMatch(text, /\[group\] "Billing"/);
+  assert.doesNotMatch(text, /\[group\] "Profile/);
+  assert.doesNotMatch(text, /possible repeated nav subtree/);
+
+  const raw = withNoColor(() =>
+    formatSnapshotText(
+      {
+        nodes,
+        truncated: false,
+        androidSnapshot: { backend: 'android-helper' },
+      },
+      { raw: true },
+    ),
+  );
+  assert.match(raw, /"Invisible stale action"/);
+  assert.match(raw, /"Messages\. Your review is required"/);
+});
+
 test('formatSnapshotText renders explicit hidden scroll-area content hints', () => {
   const text = withNoColor(() =>
     formatSnapshotText({