fix: cache Android snapshot helper installs (#470)

thymikee · web-flow · commit 3fee9d6d86fb · 2026-04-28T18:29:10.000-04:00
diff --git a/.github/workflows/android.yml b/.github/workflows/android.yml
@@ -29,15 +29,35 @@ jobs:
         id: android-replay-host
         uses: ./.github/actions/setup-android-replay-host
 
-      - name: Run Android smoke replay
+      - name: Install Android SDK packages
+        run: |
+          SDK_ROOT="${ANDROID_HOME:-${ANDROID_SDK_ROOT:-/usr/local/lib/android/sdk}}"
+          SDKMANAGER="$SDK_ROOT/cmdline-tools/latest/bin/sdkmanager"
+          if [ ! -x "$SDKMANAGER" ]; then
+            SDKMANAGER="$SDK_ROOT/cmdline-tools/bin/sdkmanager"
+          fi
+          if [ ! -x "$SDKMANAGER" ]; then
+            echo "sdkmanager not found under $SDK_ROOT" >&2
+            exit 1
+          fi
+          yes | "$SDKMANAGER" --licenses >/dev/null
+          "$SDKMANAGER" "platforms;android-36" "build-tools;36.0.0"
+
+      - name: Package npm-bundled Android snapshot helper
+        run: pnpm package:android-snapshot-helper:npm
+
+      - name: Run Android smoke checks
         uses: reactivecircus/android-emulator-runner@b530d96654c385303d652368551fb075bc2f0b6b # v2.35.0
         with:
           api-level: 36
           arch: x86_64
           profile: pixel_7
           target: google_apis_playstore
           emulator-options: -no-window -gpu swiftshader_indirect -no-snapshot -noaudio -no-boot-anim -no-metrics
-          script: node --experimental-strip-types src/bin.ts test test/integration/replays/android/01-settings.ad --retries 2 --report-junit test/artifacts/replays-android-smoke.junit.xml
+          script: |
+            set -e
+            node --experimental-strip-types src/bin.ts test test/integration/replays/android/01-settings.ad --retries 2 --report-junit test/artifacts/replays-android-smoke.junit.xml
+            sh ./test/scripts/android-snapshot-helper-release-smoke.sh
 
       - name: Upload Android artifacts
         if: always()
diff --git a/src/platforms/android/__tests__/snapshot-helper.test.ts b/src/platforms/android/__tests__/snapshot-helper.test.ts
@@ -3,14 +3,16 @@ import crypto from 'node:crypto';
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { test } from 'vitest';
+import { beforeEach, test } from 'vitest';
 import {
   captureAndroidSnapshotWithHelper,
   ensureAndroidSnapshotHelper,
+  forgetAndroidSnapshotHelperInstall,
   parseAndroidSnapshotHelperManifest,
   parseAndroidSnapshotHelperOutput,
   parseAndroidSnapshotHelperXml,
   prepareAndroidSnapshotHelperArtifactFromManifestUrl,
+  resetAndroidSnapshotHelperInstallCache,
   verifyAndroidSnapshotHelperArtifact,
   type AndroidAdbExecutor,
   type AndroidSnapshotHelperManifest,
@@ -31,6 +33,10 @@ const manifest: AndroidSnapshotHelperManifest = {
   installArgs: ['install', '-r', '-t'],
 };
 
+beforeEach(() => {
+  resetAndroidSnapshotHelperInstallCache();
+});
+
 test('parseAndroidSnapshotHelperOutput reconstructs XML chunks and metadata', () => {
   const xml = '<?xml version="1.0"?><hierarchy><node text="first&#10;second" /></hierarchy>';
   const output = helperOutput({
@@ -212,6 +218,132 @@ test('ensureAndroidSnapshotHelper installs when missing and skips current versio
   assert.equal(skipped.reason, 'current');
 });
 
+test('ensureAndroidSnapshotHelper caches successful install checks per device and helper version', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'snapshot-helper-install-cache-'));
+  const apkPath = path.join(tmpDir, 'helper.apk');
+  await fs.writeFile(apkPath, 'helper-apk');
+  const localManifest = {
+    ...manifest,
+    sha256: sha256Text('helper-apk'),
+  };
+  const calls: string[][] = [];
+  const adb: AndroidAdbExecutor = async (args) => {
+    calls.push(args);
+    if (args.includes('--show-versioncode')) {
+      return { exitCode: 1, stdout: '', stderr: 'not found' };
+    }
+    return { exitCode: 0, stdout: '', stderr: '' };
+  };
+  const artifact = { apkPath, manifest: localManifest };
+
+  const installed = await ensureAndroidSnapshotHelper({
+    adb,
+    artifact,
+    deviceKey: 'android:emulator-5554',
+  });
+  const cached = await ensureAndroidSnapshotHelper({
+    adb,
+    artifact,
+    deviceKey: 'android:emulator-5554',
+  });
+
+  assert.equal(installed.reason, 'missing');
+  assert.equal(cached.reason, 'current');
+  assert.equal(cached.installed, false);
+  assert.equal(cached.installedVersionCode, localManifest.versionCode);
+  assert.deepEqual(calls, [
+    [
+      'shell',
+      'cmd',
+      'package',
+      'list',
+      'packages',
+      '--show-versioncode',
+      localManifest.packageName,
+    ],
+    ['install', '-r', '-t', apkPath],
+  ]);
+
+  await ensureAndroidSnapshotHelper({
+    adb,
+    artifact,
+    deviceKey: 'android:device-2',
+  });
+  assert.equal(calls.length, 4);
+
+  forgetAndroidSnapshotHelperInstall({
+    deviceKey: 'android:emulator-5554',
+    packageName: localManifest.packageName,
+    versionCode: localManifest.versionCode,
+  });
+  await ensureAndroidSnapshotHelper({
+    adb,
+    artifact,
+    deviceKey: 'android:emulator-5554',
+  });
+  assert.equal(calls.length, 6);
+});
+
+test('ensureAndroidSnapshotHelper always policy bypasses cached install result', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'snapshot-helper-install-always-'));
+  const apkPath = path.join(tmpDir, 'helper.apk');
+  await fs.writeFile(apkPath, 'helper-apk');
+  const localManifest = {
+    ...manifest,
+    sha256: sha256Text('helper-apk'),
+  };
+  const calls: string[][] = [];
+  const adb: AndroidAdbExecutor = async (args) => {
+    calls.push(args);
+    if (args.includes('--show-versioncode')) {
+      return {
+        exitCode: 0,
+        stdout: `package:${localManifest.packageName} versionCode:${localManifest.versionCode}`,
+        stderr: '',
+      };
+    }
+    return { exitCode: 0, stdout: '', stderr: '' };
+  };
+  const artifact = { apkPath, manifest: localManifest };
+
+  const cached = await ensureAndroidSnapshotHelper({
+    adb,
+    artifact,
+    deviceKey: 'android:emulator-5554',
+  });
+  const forced = await ensureAndroidSnapshotHelper({
+    adb,
+    artifact,
+    deviceKey: 'android:emulator-5554',
+    installPolicy: 'always',
+  });
+
+  assert.equal(cached.reason, 'current');
+  assert.equal(forced.reason, 'forced');
+  assert.equal(forced.installed, true);
+  assert.deepEqual(calls, [
+    [
+      'shell',
+      'cmd',
+      'package',
+      'list',
+      'packages',
+      '--show-versioncode',
+      localManifest.packageName,
+    ],
+    [
+      'shell',
+      'cmd',
+      'package',
+      'list',
+      'packages',
+      '--show-versioncode',
+      localManifest.packageName,
+    ],
+    ['install', '-r', '-t', apkPath],
+  ]);
+});
+
 test('verifyAndroidSnapshotHelperArtifact rejects checksum mismatch', async () => {
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'snapshot-helper-sha-'));
   const apkPath = path.join(tmpDir, 'helper.apk');
diff --git a/src/platforms/android/__tests__/snapshot.test.ts b/src/platforms/android/__tests__/snapshot.test.ts
@@ -20,7 +20,11 @@ import type { DeviceInfo } from '../../../utils/device.ts';
 import { AppError } from '../../../utils/errors.ts';
 import { runCmd } from '../../../utils/exec.ts';
 import { sleep } from '../adb.ts';
-import type { AndroidAdbExecutor, AndroidSnapshotHelperManifest } from '../snapshot-helper.ts';
+import {
+  resetAndroidSnapshotHelperInstallCache,
+  type AndroidAdbExecutor,
+  type AndroidSnapshotHelperManifest,
+} from '../snapshot-helper.ts';
 
 const VALID_PNG = Buffer.from(
   'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+b9xkAAAAASUVORK5CYII=',
@@ -53,6 +57,7 @@ const helperManifest: AndroidSnapshotHelperManifest = {
 };
 
 beforeEach(() => {
+  resetAndroidSnapshotHelperInstallCache();
   mockRunCmd.mockReset();
   mockSleep.mockReset();
   mockSleep.mockResolvedValue(undefined);
@@ -294,6 +299,56 @@ test('snapshotAndroid falls back to stock uiautomator when helper fails', async
   );
 });
 
+test('snapshotAndroid re-probes helper install after helper capture failure', async () => {
+  let versionProbeCount = 0;
+  let instrumentAttempts = 0;
+  const helperAdb: AndroidAdbExecutor = async (args) => {
+    if (args.includes('--show-versioncode')) {
+      versionProbeCount += 1;
+      return {
+        exitCode: 0,
+        stdout: 'package:com.callstack.agentdevice.snapshothelper versionCode:13003',
+        stderr: '',
+      };
+    }
+    if (args.includes('instrument')) {
+      instrumentAttempts += 1;
+      if (instrumentAttempts === 1) {
+        return { exitCode: 1, stdout: '', stderr: 'instrumentation failed' };
+      }
+      return {
+        exitCode: 0,
+        stdout: helperOutput('<hierarchy><node text="helper" bounds="[0,0][10,10]" /></hierarchy>'),
+        stderr: '',
+      };
+    }
+    throw new Error(`unexpected helper adb args: ${args.join(' ')}`);
+  };
+  const stockXml =
+    '<?xml version="1.0" encoding="UTF-8"?><hierarchy><node text="stock" bounds="[0,0][10,10]" /></hierarchy>';
+  mockRunCmd.mockImplementation(async (_cmd, args) => {
+    if (args.includes('exec-out')) {
+      return { exitCode: 0, stdout: stockXml, stderr: '' };
+    }
+    return { exitCode: 0, stdout: '', stderr: '' };
+  });
+  const helperOptions = {
+    helperAdb,
+    helperArtifact: {
+      apkPath: '/tmp/helper.apk',
+      manifest: helperManifest,
+    },
+  };
+
+  const fallback = await snapshotAndroid(device, helperOptions);
+  const helper = await snapshotAndroid(device, helperOptions);
+
+  assert.equal(fallback.androidSnapshot.backend, 'uiautomator-dump');
+  assert.equal(helper.androidSnapshot.backend, 'android-helper');
+  assert.equal(helper.nodes[0]?.label, 'helper');
+  assert.equal(versionProbeCount, 2);
+});
+
 test('dumpUiHierarchy reads fallback XML when dump exits non-zero', async () => {
   const xml =
     '<?xml version="1.0" encoding="UTF-8"?><hierarchy><node text="fallback"/></hierarchy>';
diff --git a/src/platforms/android/snapshot-helper-install.ts b/src/platforms/android/snapshot-helper-install.ts
@@ -10,9 +10,49 @@ import type {
   AndroidSnapshotHelperInstallResult,
 } from './snapshot-helper-types.ts';
 
+const installedSnapshotHelpers = new Map<string, number>();
+
+export function forgetAndroidSnapshotHelperInstall(options: {
+  deviceKey: string;
+  packageName: string;
+  versionCode: number;
+}): void {
+  forgetInstalledSnapshotHelper(
+    getInstallCacheKey(options.deviceKey, options.packageName, options.versionCode),
+  );
+}
+
+export function resetAndroidSnapshotHelperInstallCache(): void {
+  installedSnapshotHelpers.clear();
+}
+
+function getInstallCacheKey(
+  deviceKey: string | undefined,
+  packageName: string,
+  versionCode: number,
+): string | undefined {
+  return deviceKey ? `${deviceKey}\0${packageName}\0${versionCode}` : undefined;
+}
+
+function rememberInstalledSnapshotHelper(
+  cacheKey: string | undefined,
+  installedVersionCode: number,
+): void {
+  if (cacheKey) {
+    installedSnapshotHelpers.set(cacheKey, installedVersionCode);
+  }
+}
+
+function forgetInstalledSnapshotHelper(cacheKey: string | undefined): void {
+  if (cacheKey) {
+    installedSnapshotHelpers.delete(cacheKey);
+  }
+}
+
 export async function ensureAndroidSnapshotHelper(options: {
   adb: AndroidAdbExecutor;
   artifact: AndroidSnapshotHelperArtifact;
+  deviceKey?: string;
   installPolicy?: AndroidSnapshotHelperInstallPolicy;
   timeoutMs?: number;
 }): Promise<AndroidSnapshotHelperInstallResult> {
@@ -28,10 +68,27 @@ export async function ensureAndroidSnapshotHelper(options: {
       reason: 'skipped',
     };
   }
+  const installCacheKey = getInstallCacheKey(options.deviceKey, packageName, versionCode);
+  const cachedVersionCode = installCacheKey
+    ? installedSnapshotHelpers.get(installCacheKey)
+    : undefined;
+  if (installCacheKey && installPolicy !== 'always' && cachedVersionCode !== undefined) {
+    return {
+      packageName,
+      versionCode,
+      installedVersionCode: cachedVersionCode,
+      installed: false,
+      reason: 'current',
+    };
+  }
   const installedVersionCode = await readInstalledVersionCode(adb, packageName, options.timeoutMs);
   const reason = getInstallReason(installPolicy, installedVersionCode, versionCode);
 
   if (reason === 'current') {
+    if (installedVersionCode === undefined) {
+      throw new Error('Expected installed versionCode for current Android snapshot helper');
+    }
+    rememberInstalledSnapshotHelper(installCacheKey, installedVersionCode);
     return {
       packageName,
       versionCode,
@@ -51,6 +108,7 @@ export async function ensureAndroidSnapshotHelper(options: {
     timeoutMs: options.timeoutMs,
   });
   if (result.exitCode !== 0) {
+    forgetInstalledSnapshotHelper(installCacheKey);
     throw new AppError('COMMAND_FAILED', 'Failed to install Android snapshot helper', {
       packageName,
       versionCode,
@@ -60,6 +118,7 @@ export async function ensureAndroidSnapshotHelper(options: {
     });
   }
 
+  rememberInstalledSnapshotHelper(installCacheKey, versionCode);
   return {
     packageName,
     versionCode,
diff --git a/src/platforms/android/snapshot-helper.ts b/src/platforms/android/snapshot-helper.ts
@@ -8,7 +8,11 @@ export {
   parseAndroidSnapshotHelperOutput,
   parseAndroidSnapshotHelperXml,
 } from './snapshot-helper-capture.ts';
-export { ensureAndroidSnapshotHelper } from './snapshot-helper-install.ts';
+export {
+  ensureAndroidSnapshotHelper,
+  forgetAndroidSnapshotHelperInstall,
+  resetAndroidSnapshotHelperInstallCache,
+} from './snapshot-helper-install.ts';
 export {
   ANDROID_SNAPSHOT_HELPER_NAME,
   ANDROID_SNAPSHOT_HELPER_OUTPUT_FORMAT,
diff --git a/src/platforms/android/snapshot.ts b/src/platforms/android/snapshot.ts
diff --git a/test/scripts/android-snapshot-helper-release-smoke.sh b/test/scripts/android-snapshot-helper-release-smoke.sh
