fix: make helper-backed CI deterministic

thymikee · thymikee · commit 3682be6d84c4 · 2026-07-14T08:24:54.000+02:00
diff --git a/apple-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/apple-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
@@ -263,7 +263,7 @@ extension RunnerTests {
     }
     let command = try runnerCommandFixture(
       """
-      {"command":"gesture","commandId":"gesture-fling-fallback","gesturePlan":{"topology":"single","intent":"fling","durationMs":100,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":100,"point":{"x":40,"y":150}}]}]}}
+      {"command":"gesture","commandId":"gesture-fling-fallback","gesturePlan":{"topology":"single","intent":"fling","executionProfile":"endpoint-hold","durationMs":100,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":100,"point":{"x":40,"y":150}}]}]}}
       """
     )
 
diff --git a/src/__tests__/test-utils/android-snapshot-helper.ts b/src/__tests__/test-utils/android-snapshot-helper.ts
@@ -1,6 +1,31 @@
 import type { AndroidAdbExecutor } from '../../platforms/android/adb-executor.ts';
+import type { AndroidSnapshotHelperArtifact } from '../../platforms/android/snapshot-helper-types.ts';
+import { fileURLToPath } from 'node:url';
 
 const SNAPSHOT_HELPER_PACKAGE = 'com.callstack.agentdevice.snapshothelper';
+const SNAPSHOT_HELPER_FIXTURE_APK_PATH = fileURLToPath(
+  new URL('./fixtures/android-helper-apk.fixture', import.meta.url),
+);
+const SNAPSHOT_HELPER_FIXTURE_APK_SHA256 =
+  'a5f6a2fba1163bba2f13026bd3a192f52ba2816524b7cfa83c6b7ca568f6710a';
+
+export const ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT: AndroidSnapshotHelperArtifact = {
+  apkPath: SNAPSHOT_HELPER_FIXTURE_APK_PATH,
+  manifest: {
+    name: 'android-snapshot-helper',
+    version: '0.13.3',
+    apkUrl: null,
+    sha256: SNAPSHOT_HELPER_FIXTURE_APK_SHA256,
+    packageName: SNAPSHOT_HELPER_PACKAGE,
+    versionCode: 13003,
+    instrumentationRunner: `${SNAPSHOT_HELPER_PACKAGE}/.SnapshotInstrumentation`,
+    minSdk: 23,
+    targetSdk: 36,
+    outputFormat: 'uiautomator-xml',
+    statusProtocol: 'android-snapshot-helper-v1',
+    installArgs: ['install', '-r', '-t'],
+  },
+};
 
 export function createAndroidSnapshotHelperExecutor(options: {
   readonly exec: AndroidAdbExecutor;
diff --git a/src/__tests__/test-utils/fixtures/android-helper-apk.fixture b/src/__tests__/test-utils/fixtures/android-helper-apk.fixture
diff --git a/src/__tests__/test-utils/index.ts b/src/__tests__/test-utils/index.ts
@@ -21,6 +21,7 @@ export {
 export { makeSnapshotState } from './snapshot-builders.ts';
 
 export {
+  ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT,
   androidSnapshotHelperOutput,
   createAndroidSnapshotHelperExecutor,
   isAndroidSnapshotHelperCapture,
diff --git a/src/compat/maestro/support-matrix.ts b/src/compat/maestro/support-matrix.ts
@@ -18,8 +18,6 @@ export const MAESTRO_COMPAT_SUPPORTED_CAPABILITIES = [
 
 export const MAESTRO_COMPAT_TRACKER_URL = 'https://github.com/callstack/agent-device/issues/558';
 
-export const MAESTRO_NEW_ISSUE_URL = 'https://github.com/callstack/agent-device/issues/new';
-
 export function formatMaestroSupportedSubsetForCli(): string {
   return `Supported subset: ${formatMaestroCapabilityList(MAESTRO_COMPAT_SUPPORTED_CAPABILITIES)}.`;
 }
diff --git a/src/contracts/scroll-gesture.test.ts b/src/contracts/scroll-gesture.test.ts
@@ -6,7 +6,6 @@ import {
   buildInPageSwipeGesturePlan,
   buildScrollGesturePlan,
   clampGestureCoordinate,
-  pointFromPercentInFrame,
 } from './scroll-gesture.ts';
 
 test('buildInPageSwipeGesturePlan applies one inset lane policy in every direction', () => {
@@ -201,14 +200,6 @@ test('assertScrollGestureInput rejects non-positive or non-finite pixels', () =>
   }
 });
 
-test('pointFromPercentInFrame preserves authored percentages within valid pixel bounds', () => {
-  const frame = { referenceWidth: 400, referenceHeight: 800 };
-
-  assert.deepEqual(pointFromPercentInFrame(frame, 10, 30), { x: 40, y: 240 });
-  assert.deepEqual(pointFromPercentInFrame(frame, 100, 0), { x: 399, y: 0 });
-  assert.deepEqual(pointFromPercentInFrame(frame, -10, 100), { x: 0, y: 799 });
-});
-
 test('clampGestureCoordinate rounds values and clamps them into the safe gesture band', () => {
   assert.equal(clampGestureCoordinate(10.4, 8, 100), 10);
   assert.equal(clampGestureCoordinate(10.6, 8, 100), 11);
diff --git a/src/contracts/scroll-gesture.ts b/src/contracts/scroll-gesture.ts
@@ -247,19 +247,6 @@ function pointFromPercent(
   };
 }
 
-export function pointFromPercentInFrame(
-  frame: GestureReferenceFrame,
-  xPercent: number,
-  yPercent: number,
-): GesturePoint {
-  const point = pointFromPercent(frame, xPercent, yPercent);
-  // Frame dimensions are exclusive upper bounds for zero-based input coordinates.
-  return {
-    x: clampToRange(point.x, 0, Math.max(0, Math.round(frame.referenceWidth) - 1)),
-    y: clampToRange(point.y, 0, Math.max(0, Math.round(frame.referenceHeight) - 1)),
-  };
-}
-
 function clampGesturePoint(
   point: GesturePoint,
   frame: GestureReferenceFrame,
diff --git a/src/platforms/android/__tests__/android-helper-artifact.fixtures.ts b/src/platforms/android/__tests__/android-helper-artifact.fixtures.ts
diff --git a/src/platforms/android/__tests__/ime-lifecycle.test.ts b/src/platforms/android/__tests__/ime-lifecycle.test.ts
@@ -12,16 +12,16 @@ const PENDING_DIR = 'android-test-ime-pending';
 // the suite passes on a fresh checkout that hasn't packaged android-ime-helper/dist (CI Coverage).
 vi.mock('../ime-helper.ts', async (importOriginal) => {
   const actual = await importOriginal<typeof import('../ime-helper.ts')>();
-  const fixture = await import('./android-helper-artifact.fixtures.ts');
+  const fixture = await import('../../../__tests__/test-utils/android-snapshot-helper.ts');
   return {
     ...actual,
     resolveAndroidImeHelperArtifact: vi.fn(async () => ({
-      apkPath: fixture.ANDROID_HELPER_FIXTURE_APK_PATH,
+      apkPath: fixture.ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT.apkPath,
       manifest: {
         name: 'android-ime-helper' as const,
         version: '0.0.0',
         assetName: 'helper.apk',
-        sha256: fixture.ANDROID_HELPER_FIXTURE_APK_SHA256,
+        sha256: fixture.ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT.manifest.sha256,
         packageName: 'com.callstack.agentdevice.imehelper',
         versionCode: 1,
         serviceComponent: HELPER_SERVICE,
diff --git a/src/platforms/android/__tests__/input-actions-fill.test.ts b/src/platforms/android/__tests__/input-actions-fill.test.ts
@@ -2,6 +2,7 @@ import { test } from 'vitest';
 import assert from 'node:assert/strict';
 import {
   ANDROID_EMULATOR,
+  ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT,
   createAndroidSnapshotHelperExecutor,
 } from '../../../__tests__/test-utils/index.ts';
 import { AppError } from '../../../kernel/errors.ts';
@@ -180,6 +181,7 @@ test('fillAndroid delegates target replacement to provider-native text injection
   let value = '';
   await withAndroidAdbProvider(
     {
+      snapshotHelperArtifact: ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT,
       exec: createAndroidSnapshotHelperExecutor({
         exec: async (args) => {
           throw new Error(`unexpected adb call: ${args.join(' ')}`);
@@ -376,7 +378,10 @@ async function withFillAdb(
       };
   const fn = maybeFn ?? (captureXmlOrFn as () => Promise<void>);
   await withAndroidAdbProvider(
-    { exec: createAndroidSnapshotHelperExecutor({ exec, captureXml }) },
+    {
+      exec: createAndroidSnapshotHelperExecutor({ exec, captureXml }),
+      snapshotHelperArtifact: ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT,
+    },
     { serial: ANDROID_EMULATOR.id },
     fn,
   );
diff --git a/src/platforms/android/__tests__/input-actions-test-ime.test.ts b/src/platforms/android/__tests__/input-actions-test-ime.test.ts
@@ -27,6 +27,7 @@ vi.mock('../ime-helper.ts', async (importOriginal) => {
 
 import {
   ANDROID_EMULATOR,
+  ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT,
   createAndroidSnapshotHelperExecutor,
 } from '../../../__tests__/test-utils/index.ts';
 import { fillAndroid, typeAndroid } from '../input-actions.ts';
@@ -102,9 +103,13 @@ test('fillAndroid clears then commits non-ASCII text through the test IME and ve
     captureXml: () => androidInputXml({ text: currentText }),
   });
 
-  await withAndroidAdbProvider(adb, { serial: ANDROID_EMULATOR.id }, async () => {
-    await fillAndroid(ANDROID_EMULATOR, 10, 10, 'Café ☕ 🎉 你好');
-  });
+  await withAndroidAdbProvider(
+    { exec: adb, snapshotHelperArtifact: ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT },
+    { serial: ANDROID_EMULATOR.id },
+    async () => {
+      await fillAndroid(ANDROID_EMULATOR, 10, 10, 'Café ☕ 🎉 你好');
+    },
+  );
 
   assert.equal(currentText, 'Café ☕ 🎉 你好');
   assert.equal(
diff --git a/src/platforms/android/__tests__/snapshot.test.ts b/src/platforms/android/__tests__/snapshot.test.ts
@@ -26,16 +26,13 @@ import { runCmd } from '../../../utils/exec.ts';
 import { sleep } from '../adb.ts';
 import { resetAndroidSnapshotHelperInstallCache } from '../snapshot-helper-install.ts';
 import { resetAndroidSnapshotHelperSessions } from '../snapshot-helper-session.ts';
-import { type AndroidAdbExecutor, type AndroidSnapshotHelperManifest } from '../snapshot-helper.ts';
+import { type AndroidAdbExecutor } from '../snapshot-helper.ts';
+import { ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT } from '../../../__tests__/test-utils/index.ts';
 import {
   withAndroidAdbProvider,
   type AndroidAdbProcess,
   type AndroidAdbProvider,
 } from '../adb-executor.ts';
-import {
-  ANDROID_HELPER_FIXTURE_APK_PATH,
-  ANDROID_HELPER_FIXTURE_APK_SHA256,
-} from './android-helper-artifact.fixtures.ts';
 
 const VALID_PNG = Buffer.from(
   'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+b9xkAAAAASUVORK5CYII=',
@@ -52,25 +49,7 @@ const device: DeviceInfo = {
   booted: true,
 };
 
-const helperManifest: AndroidSnapshotHelperManifest = {
-  name: 'android-snapshot-helper',
-  version: '0.13.3',
-  apkUrl: null,
-  sha256: ANDROID_HELPER_FIXTURE_APK_SHA256,
-  packageName: 'com.callstack.agentdevice.snapshothelper',
-  versionCode: 13003,
-  instrumentationRunner: 'com.callstack.agentdevice.snapshothelper/.SnapshotInstrumentation',
-  minSdk: 23,
-  targetSdk: 36,
-  outputFormat: 'uiautomator-xml',
-  statusProtocol: 'android-snapshot-helper-v1',
-  installArgs: ['install', '-r', '-t'],
-};
-
-const helperArtifact = {
-  apkPath: ANDROID_HELPER_FIXTURE_APK_PATH,
-  manifest: helperManifest,
-};
+const helperArtifact = ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT;
 const installedHelperProbe = {
   exitCode: 0,
   stdout: 'package:com.callstack.agentdevice.snapshothelper versionCode:13004',
@@ -606,6 +585,7 @@ test('snapshotAndroid emits helper phase diagnostics', async () => {
 test('snapshotAndroid resolves helper adb through scoped provider', async () => {
   const adbCalls: string[][] = [];
   const provider: AndroidAdbProvider = {
+    snapshotHelperArtifact: helperArtifact,
     exec: async (args) => {
       adbCalls.push(args);
       if (args.includes('--show-versioncode')) {
@@ -635,13 +615,12 @@ test('snapshotAndroid resolves helper adb through scoped provider', async () =>
   };
 
   const result = await withAndroidAdbProvider(provider, { serial: device.id }, async () =>
-    snapshotAndroid(device, {
-      helperArtifact,
-    }),
+    snapshotAndroid(device),
   );
 
   assert.equal(result.nodes[0]?.label, 'provider-helper');
   assert.equal(result.androidSnapshot.backend, 'android-helper');
+  assert.equal(result.androidSnapshot.helperVersion, helperArtifact.manifest.version);
   assert.deepEqual(
     adbCalls.map((args) => args[0]),
     ['shell', 'shell'],
diff --git a/src/platforms/android/__tests__/touch-executor-helper.test.ts b/src/platforms/android/__tests__/touch-executor-helper.test.ts
@@ -19,15 +19,15 @@ vi.mock('../snapshot-helper.ts', async (importOriginal) => ({
 
 vi.mock('../helper-package-install.ts', async (importOriginal) => {
   const actual = await importOriginal<typeof import('../helper-package-install.ts')>();
-  const fixture = await import('./android-helper-artifact.fixtures.ts');
+  const fixture = await import('../../../__tests__/test-utils/android-snapshot-helper.ts');
   const multitouchFixture = await import('./multitouch-helper.fixtures.ts');
   return {
     ...actual,
     resolveAndroidHelperArtifact: vi.fn(async () => ({
-      apkPath: fixture.ANDROID_HELPER_FIXTURE_APK_PATH,
+      apkPath: fixture.ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT.apkPath,
       manifest: {
         ...multitouchFixture.ANDROID_MULTITOUCH_HELPER_MANIFEST,
-        sha256: fixture.ANDROID_HELPER_FIXTURE_APK_SHA256,
+        sha256: fixture.ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT.manifest.sha256,
       },
     })),
   };
diff --git a/src/platforms/android/adb-executor.ts b/src/platforms/android/adb-executor.ts
@@ -2,6 +2,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import type { Readable, Writable } from 'node:stream';
 import type { DeviceInfo } from '../../kernel/device.ts';
 import type { Rect } from '../../kernel/snapshot.ts';
+import type { AndroidSnapshotHelperArtifact } from './snapshot-helper-types.ts';
 import type { AndroidProviderTouchPlan } from './touch-plan.ts';
 import {
   coerceExecResult,
@@ -143,6 +144,7 @@ type AndroidAdbProviderBase = {
   install?: AndroidAdbInstaller;
   installBundle?: AndroidBundleInstaller;
   text?: AndroidTextInjector;
+  snapshotHelperArtifact?: AndroidSnapshotHelperArtifact;
 };
 
 type AndroidTouchCapabilities =
diff --git a/src/platforms/android/snapshot.ts b/src/platforms/android/snapshot.ts
@@ -180,9 +180,13 @@ async function captureAndroidUiHierarchy(
   options: AndroidSnapshotOptions,
   adb: AndroidAdbExecutor,
 ): Promise<{ xml: string; metadata: AndroidSnapshotBackendMetadata }> {
+  const adbProvider = resolveAndroidAdbProvider(device, options.helperAdb);
   const helper = await withDiagnosticTimer(
     'android_snapshot_helper_artifact_resolution',
-    async () => await resolveAndroidSnapshotHelperArtifact(options.helperArtifact),
+    async () =>
+      await resolveAndroidSnapshotHelperArtifact(
+        options.helperArtifact ?? adbProvider.snapshotHelperArtifact,
+      ),
   );
   if (helper.artifact) {
     return await captureAndroidUiHierarchyWithHelper(device, options, adb, helper.artifact);
diff --git a/test/integration/provider-scenarios/android-world.ts b/test/integration/provider-scenarios/android-world.ts
@@ -9,6 +9,7 @@ import type {
   AndroidAdbProvider,
 } from '../../../src/platforms/android/adb-executor.ts';
 import type { DeviceInventoryRequest } from '../../../src/core/dispatch-resolve.ts';
+import { ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT } from '../../../src/__tests__/test-utils/index.ts';
 import { runCmd } from '../../../src/utils/exec.ts';
 import { validPng } from './assertions.ts';
 import { PROVIDER_SCENARIO_ANDROID } from './fixtures.ts';
@@ -78,6 +79,7 @@ export async function createAndroidSettingsWorld(options?: {
     packageName: 'io.example.demo_manifest',
   });
   const adbProvider: AndroidAdbProvider = {
+    snapshotHelperArtifact: ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT,
     gestureViewport: async () => {
       gestureViewportCalls += 1;
       return { x: 0, y: 0, width: 390, height: 600 };

Original file line number	Diff line number	Diff line change
`@@ -263,7 +263,7 @@ extension RunnerTests {`
`263`	`263`	`}`
`264`	`264`	`let command = try runnerCommandFixture(`
`265`	`265`	`"""`
`266`		`- {"command":"gesture","commandId":"gesture-fling-fallback","gesturePlan":{"topology":"single","intent":"fling","durationMs":100,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":100,"point":{"x":40,"y":150}}]}]}}`
	`266`	`+ {"command":"gesture","commandId":"gesture-fling-fallback","gesturePlan":{"topology":"single","intent":"fling","executionProfile":"endpoint-hold","durationMs":100,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":100,"point":{"x":40,"y":150}}]}]}}`
`267`	`267`	`"""`
`268`	`268`	`)`
`269`	`269`
Original file line number	Diff line number	Diff line change
`@@ -18,8 +18,6 @@ export const MAESTRO_COMPAT_SUPPORTED_CAPABILITIES = [`
`18`	`18`
`19`	`19`	`export const MAESTRO_COMPAT_TRACKER_URL = 'https://github.com/callstack/agent-device/issues/558';`
`20`	`20`
`21`		`-export const MAESTRO_NEW_ISSUE_URL = 'https://github.com/callstack/agent-device/issues/new';`
`22`		`-`
`23`	`21`	`export function formatMaestroSupportedSubsetForCli(): string {`
`24`	`22`	return `Supported subset: ${formatMaestroCapabilityList(MAESTRO_COMPAT_SUPPORTED_CAPABILITIES)}.`;
`25`	`23`	`}`