test(android): cold boot emulator for reliable test runs

Force Detox TestingAVD launches and Jet retries to skip Quick Boot snapshot
restore, which could leave the emulator offline on a gray screen.

Author: mikehardy

okf-bundle/testing/running-e2e.md

@@ -502,7 +502,34 @@ See also: [unit-focused-tier loop](#unit-focused-tier-iteration-loop), [dispatch
 - **adb empty** — `adb kill-server && adb start-server && adb devices`
 - **Stale processes** — one Metro (`:8081`), one emulator set (`:8080`, `:9099`, `:9000`, `:4400`, …). Stray listener on `:8090` after a run → [pre-flight recovery](#pre-flight-recovery), then restart background services with [Rules §1–2](#rules) (`yarn tests:packager:jet`, `yarn tests:emulator:start`).
 
-### iOS Detox framework cache (blocking)
+### Android emulator gray screen / Quick Boot (blocking)
+
+Detox's default emulator launch **restores the AVD Quick Boot snapshot** unless told otherwise. On `TestingAVD` that can leave the device **`offline` on a gray screen** — `adb devices` shows `emulator-XXXX offline` and Detox hangs on `wait-for-device`.
+
+**Root cause:** warm boot paths — Quick Boot snapshot restore on Detox launch, and (pre-fix) `adb reboot` on Jet retry — skip a full cold boot.
+
+**Fix (committed):** [`tests/.detoxrc.js`](../../tests/.detoxrc.js) sets `bootArgs: '-no-snapshot-load -no-snapshot-save'` on the `TestingAVD` device. Jet retry in [`tests/e2e/firebase.test.js`](../../tests/e2e/firebase.test.js) cold-restarts the same emulator (kill + relaunch with the same args) instead of `adb reboot`.
+
+**Detect:**
+
+```bash
+adb devices -l   # emulator-XXXX offline
+pgrep -fl 'qemu-system.*TestingAVD'
+rg 'SPAWN_CMD.*@TestingAVD' /tmp/rnfb-e2e-android.log   # no -no-snapshot-load → stale runbook / config
+```
+
+**Recovery before `:test-cover`:**
+
+```bash
+adb -s emulator-5554 emu kill 2>/dev/null || true
+pkill -f 'qemu-system.*TestingAVD' 2>/dev/null || true
+adb kill-server && adb start-server && adb devices   # must be empty
+# If gray screen persists after cold-boot config, wipe Quick Boot snapshots:
+# rm -rf ~/.android/avd/TestingAVD.avd/snapshots
+```
+
+Then rerun [pre-flight](#pre-flight-is-the-host-clear-to-start) and `yarn tests:android:test-cover`. Cold boot adds ~30–60s to the first Android launch vs Quick Boot — expected.
+
 
 Detox injects a prebuilt **`Detox.framework`** and XCUITest runner from a versioned cache under **`~/Library/Detox/ios/`** (hashed by Xcode version). iOS `:test-cover` / `:build` **fail before any test runs** if that cache is missing or stale (common after Xcode upgrade, first checkout, or a failed Detox postinstall).
 

tests/.detoxrc.js

@@ -62,6 +62,10 @@ module.exports = {
       device: {
         avdName: 'TestingAVD',
       },
+      // Quick Boot snapshot restore (default emulator start) can leave TestingAVD stuck
+      // offline on a gray screen; force full cold boot for every Detox launch.
+      bootArgs:
+        process.env.RNFB_ANDROID_EMULATOR_BOOT_ARGS || '-no-snapshot-load -no-snapshot-save',
     },
   },
   configurations: {

tests/README.md

@@ -105,6 +105,7 @@ This action will launch a new simulator (if not already open) and run the tests
 > Or you can change this name in the `package.json` of the tests project (don't commit the change though please).
 > **DO NOT** rename an existing AVD to this name - it will not work, rename does not change the file path currently so Detox will
 > fail to find the AVD in the correct directory. Create a new one with Google Play Services.
+> Detox cold-boots `TestingAVD` on every run (`-no-snapshot-load`) to avoid Quick Boot gray-screen failures — see [running e2e § Android gray screen](../okf-bundle/testing/running-e2e.md#android-emulator-gray-screen--quick-boot-blocking).
 
 #### Android
 

tests/e2e/firebase.test.js

@@ -67,6 +67,10 @@ const ANDROID_PACKAGE_HANDLER_TIMEOUT_MS = parseInt(
   10,
 );
 const ANDROID_BOOT_SETTLE_MS = parseInt(process.env.RNFB_ANDROID_BOOT_SETTLE_MS || '30000', 10);
+const ANDROID_AVD_NAME = process.env.RNFB_ANDROID_AVD_NAME || 'TestingAVD';
+const ANDROID_EMULATOR_COLD_BOOT_ARGS = (
+  process.env.RNFB_ANDROID_EMULATOR_BOOT_ARGS || '-no-snapshot-load -no-snapshot-save'
+).trim();
 const DRAIN_ORCHESTRATE_TIMEOUT_MS = parseInt(
   process.env.RNFB_DRAIN_ORCHESTRATE_TIMEOUT_MS || '30000',
   10,
@@ -277,6 +281,31 @@ function resolveAdbPath() {
   return sdkRoot ? path.join(sdkRoot, 'platform-tools', 'adb') : 'adb';
 }
 
+function resolveEmulatorPath() {
+  const sdkRoot = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT;
+  if (!sdkRoot) {
+    throw new Error('ANDROID_HOME or ANDROID_SDK_ROOT is required to cold boot the Android emulator');
+  }
+  return path.join(sdkRoot, 'emulator', 'emulator');
+}
+
+function resolveAndroidEmulatorPort(serial) {
+  const portMatch = serial.match(/^emulator-(\d+)$/);
+  return portMatch ? portMatch[1] : '5554';
+}
+
+function adbDeviceState(serial) {
+  const adb = resolveAdbPath();
+  try {
+    return execSync(`${adb} -s ${serial} get-state`, {
+      encoding: 'utf8',
+      timeout: 5000,
+    }).trim();
+  } catch (_) {
+    return 'unknown';
+  }
+}
+
 function resolveAndroidSerial() {
   try {
     if (typeof device !== 'undefined' && device?.id) {
@@ -409,13 +438,49 @@ async function ensureAndroidJetHostClear(label = 'android-jet-host-clear') {
   console.log(`[rnfb-e2e] ${label}: host clear`);
 }
 
-function rebootAndroidEmulator() {
+function coldBootAndroidEmulator() {
   const adb = resolveAdbPath();
   const serial = resolveAndroidSerial();
-  console.warn(`[rnfb-e2e] Rebooting Android emulator serial=${serial} via adb reboot`);
+  const port = resolveAndroidEmulatorPort(serial);
+  const coldBootSerial = `emulator-${port}`;
+  const emulatorPath = resolveEmulatorPath();
+  const extraBootArgs = ANDROID_EMULATOR_COLD_BOOT_ARGS.split(/\s+/).filter(Boolean);
+
+  console.warn(
+    `[rnfb-e2e] Cold booting Android emulator serial=${serial} avd=${ANDROID_AVD_NAME} ` +
+      `(kill + relaunch with ${extraBootArgs.join(' ')})`,
+  );
 
-  execSync(`${adb} -s ${serial} reboot`, { stdio: 'inherit' });
-  execSync(`${adb} -s ${serial} wait-for-device`, {
+  try {
+    execSync(`${adb} -s ${serial} emu kill`, { stdio: 'inherit', timeout: 60000 });
+  } catch (err) {
+    console.warn(`[rnfb-e2e] emu kill failed (continuing): ${err?.message || err}`);
+  }
+
+  try {
+    execSync(`pkill -f "qemu-system.*@${ANDROID_AVD_NAME}"`, { stdio: 'ignore', timeout: 5000 });
+  } catch (_) {
+    // No matching emulator process.
+  }
+
+  const emulatorArgs = [
+    '-verbose',
+    '-no-audio',
+    '-no-boot-anim',
+    '-read-only',
+    '-port',
+    port,
+    ...extraBootArgs,
+    `@${ANDROID_AVD_NAME}`,
+  ];
+
+  const child = spawn(emulatorPath, emulatorArgs, {
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+
+  execSync(`${adb} -s ${coldBootSerial} wait-for-device`, {
     stdio: 'inherit',
     timeout: REBOOT_ANDROID_EMULATOR_TIMEOUT_MS,
   });
@@ -430,6 +495,17 @@ async function waitForAndroidEmulatorReady() {
 
   while (Date.now() < deadline) {
     try {
+      const deviceState = adbDeviceState(serial);
+      if (deviceState === 'offline') {
+        stableLoadPolls = 0;
+        console.warn(
+          `[rnfb-e2e] android-ready probe serial=${serial} state=offline (Quick Boot gray screen?) — ` +
+            'kill emulator and rerun; Detox should cold boot with -no-snapshot-load',
+        );
+        await sleep(ANDROID_READY_POLL_MS);
+        continue;
+      }
+
       const bootCompleted = adbShell(serial, 'getprop sys.boot_completed');
       const bootDev = adbShell(serial, 'getprop dev.bootcomplete');
       const provisioned = adbShell(serial, 'settings get global device_provisioned');
@@ -1079,7 +1155,7 @@ describe('Jet Tests', function () {
           if (platform === 'ios' && process.platform === 'darwin') {
             await rebootIosSimulator(testsDir);
           } else if (platform === 'android') {
-            rebootAndroidEmulator();
+            coldBootAndroidEmulator();
             await waitForAndroidEmulatorReady();
           } else {
             try {