test(android): add comprehensive emulator E2E coverage

.github/actions/setup-android-replay-host/action.yml

@@ -1,5 +1,5 @@
 name: 'Setup Android Replay Host'
-description: 'Prepare the Android CI host for replay tests and expose the agent-device home path'
+description: 'Prepare the Android CI host for replay tests and expose the daemon state path'
 
 inputs:
   package-helpers:
@@ -8,19 +8,19 @@ inputs:
     default: 'false'
 
 outputs:
-  agent-home-dir:
-    description: 'Resolved agent-device home directory'
-    value: ${{ steps.agent-home.outputs.dir }}
+  agent-state-dir:
+    description: 'Resolved agent-device daemon state directory'
+    value: ${{ steps.agent-state.outputs.dir }}
   helpers-cache-hit:
     description: 'Whether packaged Android helpers were restored from cache'
     value: ${{ steps.android-helpers-cache.outputs.cache-hit }}
 
 runs:
   using: 'composite'
   steps:
-    - name: Resolve agent-device home
-      id: agent-home
-      run: echo "dir=$HOME/.agent-device" >> "$GITHUB_OUTPUT"
+    - name: Resolve agent-device daemon state
+      id: agent-state
+      run: echo "dir=$(pnpm --silent daemon:state-dir)" >> "$GITHUB_OUTPUT"
       shell: bash
 
     - name: Enable KVM

.github/actions/upload-agent-device-artifacts/action.yml

@@ -5,7 +5,7 @@ inputs:
   artifact-name:
     description: 'Artifact name'
     required: true
-  agent-home-dir:
+  agent-state-dir:
     description: 'Resolved agent-device daemon state directory'
     required: true
   runner-derived-path:
@@ -23,9 +23,9 @@ runs:
         if-no-files-found: ignore
         include-hidden-files: true
         path: |
-          ${{ inputs.agent-home-dir }}/daemon.log
+          ${{ inputs.agent-state-dir }}/daemon.log
           ~/.agent-device/logs/**
-          ${{ inputs.agent-home-dir }}/sessions/**
+          ${{ inputs.agent-state-dir }}/sessions/**
           ${{ inputs.runner-derived-path }}/.agent-device-runner-cache.json
           ${{ inputs.runner-derived-path }}/Logs/**
           test/artifacts/**

.github/workflows/android.yml

@@ -51,6 +51,15 @@ jobs:
       - name: Report fixture cache source
         run: echo "Android fixture APK source=${{ steps.fixture-app.outputs.source }}"
 
+      - name: Run Android emulator catalog coverage contract
+        run: node --test test/integration/smoke-android-emulator-coverage.test.ts
+
+      - name: Build agent-device CLI
+        run: pnpm build
+
+      - name: Reset daemon state
+        run: pnpm clean:daemon
+
       - name: Run Android smoke checks
         uses: reactivecircus/android-emulator-runner@b530d96654c385303d652368551fb075bc2f0b6b # v2.35.0
         with:
@@ -60,13 +69,15 @@ jobs:
           target: google_apis_playstore
           emulator-options: -no-window -gpu swiftshader_indirect -no-snapshot -noaudio -no-boot-anim -no-metrics
           script: |
-            sh ./test/scripts/android-fixture-cache-smoke.sh "${{ steps.fixture-app.outputs.apk-path }}" "${{ steps.fixture-app.outputs.app-id }}"
+            set -eu
+            ANDROID_SERIAL="$(adb devices | awk 'NR > 1 && $2 == "device" { print $1; exit }')"
+            test -n "$ANDROID_SERIAL"
+            AGENT_DEVICE_ANDROID_E2E=1 AGENT_DEVICE_ANDROID_SERIAL="$ANDROID_SERIAL" AGENT_DEVICE_FIXTURE_APP_PATH="${{ steps.fixture-app.outputs.apk-path }}" AGENT_DEVICE_FIXTURE_APP_ID="${{ steps.fixture-app.outputs.app-id }}" node --test test/integration/smoke-android-emulator.test.ts
             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()
         uses: ./.github/actions/upload-agent-device-artifacts
         with:
           artifact-name: android-artifacts
-          agent-home-dir: ${{ steps.android-replay-host.outputs.agent-home-dir }}
+          agent-state-dir: ${{ steps.android-replay-host.outputs.agent-state-dir }}

.github/workflows/ios.yml

@@ -155,5 +155,5 @@ jobs:
         uses: ./.github/actions/upload-agent-device-artifacts
         with:
           artifact-name: ios-artifacts
-          agent-home-dir: ${{ env.AGENT_DEVICE_STATE_DIR }}
+          agent-state-dir: ${{ env.AGENT_DEVICE_STATE_DIR }}
           runner-derived-path: ${{ env.AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH }}

.github/workflows/macos.yml

@@ -56,5 +56,5 @@ jobs:
         uses: ./.github/actions/upload-agent-device-artifacts
         with:
           artifact-name: macos-artifacts
-          agent-home-dir: ${{ env.AGENT_DEVICE_STATE_DIR }}
+          agent-state-dir: ${{ env.AGENT_DEVICE_STATE_DIR }}
           runner-derived-path: ${{ env.AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH }}

.github/workflows/replays-nightly.yml

@@ -121,7 +121,7 @@ jobs:
         uses: ./.github/actions/upload-agent-device-artifacts
         with:
           artifact-name: replay-nightly-android-artifacts
-          agent-home-dir: ${{ steps.android-replay-host.outputs.agent-home-dir }}
+          agent-state-dir: ${{ steps.android-replay-host.outputs.agent-state-dir }}
 
   nightly-ios:
     name: iOS Replay Suite
@@ -202,7 +202,7 @@ jobs:
         uses: ./.github/actions/upload-agent-device-artifacts
         with:
           artifact-name: replay-nightly-ios-artifacts
-          agent-home-dir: ${{ env.AGENT_DEVICE_STATE_DIR }}
+          agent-state-dir: ${{ env.AGENT_DEVICE_STATE_DIR }}
           runner-derived-path: ${{ env.AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH }}
 
   nightly-macos:
@@ -239,5 +239,5 @@ jobs:
         uses: ./.github/actions/upload-agent-device-artifacts
         with:
           artifact-name: replay-nightly-macos-artifacts
-          agent-home-dir: ${{ env.AGENT_DEVICE_STATE_DIR }}
+          agent-state-dir: ${{ env.AGENT_DEVICE_STATE_DIR }}
           runner-derived-path: ${{ env.AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH }}

android/snapshot-helper/README.md

@@ -44,7 +44,9 @@ Devices or providers that block test-package installs must allow this package be
 can run.
 
 `waitForIdleTimeoutMs` defaults to `500`, which is a maximum wait, not a fixed sleep. Direct helper
-invocations can pass `0` when immediate capture during ongoing animation is preferred.
+invocations can pass `0` when immediate capture during ongoing animation is preferred. Root
+acquisition has a separate 500 ms stabilization bound that is used only when no root is available or
+an active/focused window is temporarily missing its root; complete captures pay no additional wait.
 
 ## One-Shot Modes
 

android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/AccessibilityCaptureStabilizer.java

@@ -0,0 +1,80 @@
+package com.callstack.agentdevice.snapshothelper;
+
+final class AccessibilityCaptureStabilizer {
+  private static final long RETRY_INTERVAL_MS = 50;
+
+  interface Capture {
+    boolean isComplete();
+  }
+
+  interface Attempt<T extends Capture> {
+    T capture();
+  }
+
+  interface Clock {
+    long nowMs();
+  }
+
+  interface Sleeper {
+    void sleep(long durationMs) throws InterruptedException;
+  }
+
+  static final class IncompleteCaptureException extends Exception {
+    IncompleteCaptureException(long timeoutMs) {
+      super("Android accessibility capture remained incomplete after " + timeoutMs + " ms");
+    }
+  }
+
+  private AccessibilityCaptureStabilizer() {}
+
+  static boolean requiresActiveWindowFallback(
+      int capturedWindowCount, boolean activeWindowRootMissing) {
+    return capturedWindowCount == 0 || activeWindowRootMissing;
+  }
+
+  static boolean canAppendActiveWindowFallback(
+      int capturedWindowCount, boolean activeWindowMetadataAvailable) {
+    return capturedWindowCount == 0 || activeWindowMetadataAvailable;
+  }
+
+  static <T extends Capture> T capture(Attempt<T> attempt, long timeoutMs)
+      throws InterruptedException, IncompleteCaptureException {
+    return capture(
+        attempt,
+        timeoutMs,
+        () -> System.nanoTime() / 1_000_000,
+        Thread::sleep);
+  }
+
+  static <T extends Capture> T capture(
+      Attempt<T> attempt, long timeoutMs, Clock clock, Sleeper sleeper)
+      throws InterruptedException, IncompleteCaptureException {
+    T capture = attempt.capture();
+    if (capture.isComplete()) {
+      return capture;
+    }
+    if (timeoutMs <= 0) {
+      throw new IncompleteCaptureException(timeoutMs);
+    }
+
+    long startedAtMs = clock.nowMs();
+    long deadlineMs = startedAtMs + timeoutMs;
+    if (deadlineMs < startedAtMs) {
+      deadlineMs = Long.MAX_VALUE;
+    }
+    while (!capture.isComplete()) {
+      long remainingMs = deadlineMs - clock.nowMs();
+      if (remainingMs <= 0) {
+        throw new IncompleteCaptureException(timeoutMs);
+      }
+      try {
+        sleeper.sleep(Math.min(RETRY_INTERVAL_MS, remainingMs));
+      } catch (InterruptedException error) {
+        Thread.currentThread().interrupt();
+        throw error;
+      }
+      capture = attempt.capture();
+    }
+    return capture;
+  }
+}