fix: cache Android snapshot helper installs

Author: thymikee

.github/workflows/android.yml

@@ -29,15 +29,18 @@ jobs:
         id: android-replay-host
         uses: ./.github/actions/setup-android-replay-host
 
-      - name: Run Android smoke replay
+      - 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: |
+            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
+            pnpm package:android-snapshot-helper:npm
+            sh ./test/scripts/android-snapshot-helper-release-smoke.sh
 
       - name: Upload Android artifacts
         if: always()

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,72 @@ 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('verifyAndroidSnapshotHelperArtifact rejects checksum mismatch', async () => {
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'snapshot-helper-sha-'));
   const apkPath = path.join(tmpDir, 'helper.apk');

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);

src/platforms/android/snapshot-helper-install.ts

@@ -13,6 +13,7 @@ import type {
 export async function ensureAndroidSnapshotHelper(options: {
   adb: AndroidAdbExecutor;
   artifact: AndroidSnapshotHelperArtifact;
+  deviceKey?: string;
   installPolicy?: AndroidSnapshotHelperInstallPolicy;
   timeoutMs?: number;
 }): Promise<AndroidSnapshotHelperInstallResult> {
@@ -28,10 +29,26 @@ export async function ensureAndroidSnapshotHelper(options: {
       reason: 'skipped',
     };
   }
+  const installCacheKey = getInstallCacheKey(options.deviceKey, packageName, versionCode);
+  if (
+    installCacheKey &&
+    installPolicy !== 'always' &&
+    installedSnapshotHelpers.has(installCacheKey)
+  ) {
+    const installedVersionCode = installedSnapshotHelpers.get(installCacheKey);
+    return {
+      packageName,
+      versionCode,
+      installedVersionCode,
+      installed: false,
+      reason: 'current',
+    };
+  }
   const installedVersionCode = await readInstalledVersionCode(adb, packageName, options.timeoutMs);
   const reason = getInstallReason(installPolicy, installedVersionCode, versionCode);
 
   if (reason === 'current') {
+    rememberInstalledSnapshotHelper(installCacheKey, installedVersionCode ?? versionCode);
     return {
       packageName,
       versionCode,
@@ -51,6 +68,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 +78,7 @@ export async function ensureAndroidSnapshotHelper(options: {
     });
   }
 
+  rememberInstalledSnapshotHelper(installCacheKey, versionCode);
   return {
     packageName,
     versionCode,
@@ -69,6 +88,45 @@ export async function ensureAndroidSnapshotHelper(options: {
   };
 }
 
+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);
+  }
+}
+
 async function readInstalledVersionCode(
   adb: AndroidAdbExecutor,
   packageName: string,

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,

src/platforms/android/snapshot.ts

@@ -27,6 +27,7 @@ import {
   captureAndroidSnapshotWithHelper,
   ANDROID_SNAPSHOT_HELPER_WAIT_FOR_IDLE_TIMEOUT_MS,
   ensureAndroidSnapshotHelper,
+  forgetAndroidSnapshotHelperInstall,
   parseAndroidSnapshotHelperManifest,
   type AndroidAdbExecutor,
   type AndroidSnapshotHelperArtifact,
@@ -89,11 +90,13 @@ async function captureAndroidUiHierarchy(
 ): Promise<{ xml: string; metadata: AndroidSnapshotBackendMetadata }> {
   const helper = await resolveAndroidSnapshotHelperArtifact(options.helperArtifact);
   if (helper.artifact) {
+    const helperDeviceKey = getAndroidSnapshotHelperDeviceKey(device);
     try {
       const adb = options.helperAdb ?? createDeviceAdbExecutor(device);
       const install = await ensureAndroidSnapshotHelper({
         adb,
         artifact: helper.artifact,
+        deviceKey: helperDeviceKey,
         installPolicy: options.helperInstallPolicy,
         timeoutMs: HELPER_INSTALL_TIMEOUT_MS,
       });
@@ -125,6 +128,11 @@ async function captureAndroidUiHierarchy(
         },
       };
     } catch (error) {
+      forgetAndroidSnapshotHelperInstall({
+        deviceKey: helperDeviceKey,
+        packageName: helper.artifact.manifest.packageName,
+        versionCode: helper.artifact.manifest.versionCode,
+      });
       return await captureStockUiHierarchy(device, normalizeError(error).message);
     }
   }
@@ -184,6 +192,10 @@ function createDeviceAdbExecutor(device: DeviceInfo): AndroidAdbExecutor {
   return async (args, options) => await runCmd('adb', adbArgs(device, args), options);
 }
 
+function getAndroidSnapshotHelperDeviceKey(device: DeviceInfo): string {
+  return `${device.platform}:${device.id}`;
+}
+
 async function deriveScrollableContentHintsIfNeeded(
   device: DeviceInfo,
   nodes: RawSnapshotNode[],