@react-native-harness/platform-android 1.4.0-rc.1 → 1.4.1

package/src/adb.ts

@@ -1,8 +1,10 @@
 import { type AndroidAppLaunchOptions } from '@react-native-harness/platforms';
 import {
+  delay,
   logger,
   spawn,
   SubprocessError,
+  waitForAbort,
   type Subprocess,
 } from '@react-native-harness/tools';
 import { spawn as nodeSpawn } from 'node:child_process';
@@ -25,6 +27,7 @@ import {
   getRequiredAndroidSdkPackages,
 } from './environment.js';
 import {
+  getEmulatorCpuCores,
   getEmulatorStartupArgs,
   type EmulatorBootMode,
 } from './emulator-startup.js';
@@ -33,37 +36,26 @@ import {
   AdbPermissionGrantError,
 } from './adb-errors.js';
 
-const wait = async (ms: number): Promise<void> => {
-  await new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-};
-
-const waitForAbort = (signal: AbortSignal): Promise<never> => {
-  if (signal.aborted) {
-    return Promise.reject(signal.reason);
-  }
-
-  return new Promise((_, reject) => {
-    signal.addEventListener(
-      'abort',
-      () => {
-        reject(signal.reason);
-      },
-      { once: true },
-    );
-  });
-};
-
 const waitWithSignal = async (
   ms: number,
-  signal: AbortSignal,
+  signal: AbortSignal
 ): Promise<void> => {
   if (signal.aborted) {
     throw signal.reason;
   }
 
-  await Promise.race([wait(ms), waitForAbort(signal)]);
+  // Both sides of this race must be torn down explicitly when they lose:
+  // an uncancelled timer keeps a ref'd Timeout alive, and an uncancelled
+  // abort wait leaks a listener on `signal`, which is a session-lifetime
+  // signal here and gets polled against once per second.
+  const timer = delay(ms);
+  const abort = waitForAbort(signal);
+  try {
+    await Promise.race([timer.promise, abort.promise]);
+  } finally {
+    timer.cancel();
+    abort.cancel();
+  }
 };
 
 const EMULATOR_STARTUP_OBSERVATION_TIMEOUT_MS = 5000;
@@ -73,7 +65,7 @@ const androidAdbLogger = logger.child('android-adb');
 export const emulatorProcess = {
   startDetachedProcess: (
     file: string,
-    args: readonly string[],
+    args: readonly string[]
   ): ChildProcessByStdio<null, Readable, Readable> =>
     nodeSpawn(file, args, {
       detached: true,
@@ -84,7 +76,7 @@ export const emulatorProcess = {
 const appendBoundedOutput = (
   output: string,
   chunk: string,
-  limit: number = EMULATOR_OUTPUT_BUFFER_LIMIT,
+  limit: number = EMULATOR_OUTPUT_BUFFER_LIMIT
 ): string => {
   const nextOutput = output + chunk;
 
@@ -165,7 +157,7 @@ export const getRequiredEmulatorPackages = (apiLevel: number): string[] => {
 };
 
 export const verifyAndroidEmulatorSdk = async (
-  apiLevel: number,
+  apiLevel: number
 ): Promise<void> => {
   await ensureAndroidSdkPackages(getRequiredEmulatorPackages(apiLevel));
 };
@@ -192,7 +184,7 @@ const ensureAvdProfileAvailable = async (profile: string): Promise<void> => {
       : 'None reported by avdmanager.';
 
   throw new Error(
-    `Android AVD profile "${profile}" is not available on this machine. Available profiles: ${availableProfilesList}`,
+    `Android AVD profile "${profile}" is not available on this machine. Available profiles: ${availableProfilesList}`
   );
 };
 
@@ -201,7 +193,7 @@ const ensureAvdConfigExists = async (name: string): Promise<string> => {
 
   if ((await readAvdConfig(name)) == null) {
     throw new Error(
-      `Android AVD "${name}" was created, but config.ini was not found at ${configPath}.`,
+      `Android AVD "${name}" was created, but config.ini was not found at ${configPath}.`
     );
   }
 
@@ -235,7 +227,7 @@ const ensureAvdIniExists = async ({
 export const getStartAppArgs = (
   bundleId: string,
   activityName: string,
-  options?: AndroidAppLaunchOptions,
+  options?: AndroidAppLaunchOptions
 ): string[] => {
   const args = [
     'shell',
@@ -264,7 +256,7 @@ export const getStartAppArgs = (
 
     if (!Number.isSafeInteger(value)) {
       throw new Error(
-        `Android app launch option "${key}" must be a safe integer.`,
+        `Android app launch option "${key}" must be a safe integer.`
       );
     }
 
@@ -276,7 +268,7 @@ export const getStartAppArgs = (
 
 export const isAppInstalled = async (
   adbId: string,
-  bundleId: string,
+  bundleId: string
 ): Promise<boolean> => {
   const { stdout } = await spawn(getAdbBinaryPath(), [
     '-s',
@@ -293,7 +285,7 @@ export const isAppInstalled = async (
 export const reversePort = async (
   adbId: string,
   port: number,
-  hostPort: number = port,
+  hostPort: number = port
 ): Promise<void> => {
   await spawn(getAdbBinaryPath(), [
     '-s',
@@ -306,7 +298,7 @@ export const reversePort = async (
 
 export const stopApp = async (
   adbId: string,
-  bundleId: string,
+  bundleId: string
 ): Promise<void> => {
   await spawn(getAdbBinaryPath(), [
     '-s',
@@ -322,7 +314,7 @@ export const startApp = async (
   adbId: string,
   bundleId: string,
   activityName: string,
-  options?: AndroidAppLaunchOptions,
+  options?: AndroidAppLaunchOptions
 ): Promise<void> => {
   await spawn(getAdbBinaryPath(), [
     '-s',
@@ -341,7 +333,7 @@ export const getDeviceIds = async (): Promise<string[]> => {
 };
 
 export const getEmulatorName = async (
-  adbId: string,
+  adbId: string
 ): Promise<string | null> => {
   const { stdout } = await spawn(getAdbBinaryPath(), [
     '-s',
@@ -355,7 +347,7 @@ export const getEmulatorName = async (
 
 export const getShellProperty = async (
   adbId: string,
-  property: string,
+  property: string
 ): Promise<string | null> => {
   const { stdout } = await spawn(getAdbBinaryPath(), [
     '-s',
@@ -377,7 +369,7 @@ export type DeviceInfo = {
 };
 
 export const getDeviceInfo = async (
-  adbId: string,
+  adbId: string
 ): Promise<DeviceInfo | null> => {
   const manufacturer = await getShellProperty(adbId, 'ro.product.manufacturer');
   const model = await getShellProperty(adbId, 'ro.product.model');
@@ -386,7 +378,7 @@ export const getDeviceInfo = async (
 
 const getRequestedPermissions = async (
   adbId: string,
-  bundleId: string,
+  bundleId: string
 ): Promise<string[]> => {
   const { stdout } = await spawn(getAdbBinaryPath(), [
     '-s',
@@ -476,14 +468,14 @@ export const stopEmulator = async (adbId: string): Promise<void> => {
 
 export const installApp = async (
   adbId: string,
-  appPath: string,
+  appPath: string
 ): Promise<void> => {
   await spawn(getAdbBinaryPath(), ['-s', adbId, 'install', '-r', appPath]);
 };
 
 export const uninstallApp = async (
   adbId: string,
-  bundleId: string,
+  bundleId: string
 ): Promise<void> => {
   await spawn(getAdbBinaryPath(), ['-s', adbId, 'uninstall', bundleId]);
 };
@@ -502,20 +494,27 @@ export const createAvd = async ({
 }: CreateAvdOptions): Promise<void> => {
   const systemImagePackage = getAndroidSystemImagePackage(
     apiLevel,
-    getHostAndroidSystemImageArch(),
+    getHostAndroidSystemImageArch()
   );
 
   await verifyAndroidEmulatorSdk(apiLevel);
   await ensureAvdProfileAvailable(profile);
   await spawn('bash', [
     '-lc',
-    `printf 'no\n' | "${getAvdManagerBinaryPath()}" create avd --force --name "${name}" --package "${systemImagePackage}" --device "${profile}" -p "${getAvdDirectory(name)}"`,
+    `printf 'no\n' | "${getAvdManagerBinaryPath()}" create avd --force --name "${name}" --package "${systemImagePackage}" --device "${profile}" -p "${getAvdDirectory(
+      name
+    )}"`,
   ]);
   await ensureAvdIniExists({ name, apiLevel });
   const configPath = await ensureAvdConfigExists(name);
+  // hw.cpu.ncore is baked into config.ini (rather than passed as a `-cores`
+  // boot flag) so it's part of the AVD's persisted hardware profile: boot
+  // snapshots require an identical hardware config to load, so the vCPU
+  // count must be fixed at AVD-creation time and stay consistent across
+  // boots.
   await spawn('bash', [
     '-lc',
-    `printf '%s\n%s\n' 'disk.dataPartition.size=${diskSize}' 'vm.heapSize=${heapSize}' >> "${configPath}"`,
+    `printf '%s\n%s\n%s\n' 'disk.dataPartition.size=${diskSize}' 'vm.heapSize=${heapSize}' 'hw.cpu.ncore=${getEmulatorCpuCores()}' >> "${configPath}"`,
   ]);
 };
 
@@ -527,7 +526,7 @@ export const deleteAvd = async (name: string): Promise<void> => {
     {
       force: true,
       recursive: true,
-    },
+    }
   );
   await rm(
     `${
@@ -535,18 +534,18 @@ export const deleteAvd = async (name: string): Promise<void> => {
     }/${name}.ini`,
     {
       force: true,
-    },
+    }
   );
 };
 
 export const startEmulator = async (
   name: string,
-  mode: EmulatorBootMode = 'default-boot',
+  mode: EmulatorBootMode = 'default-boot'
 ): Promise<void> => {
   const emulatorBinaryPath = await ensureEmulatorInstalled();
   const childProcess = emulatorProcess.startDetachedProcess(
     emulatorBinaryPath,
-    getEmulatorStartupArgs(name, mode),
+    getEmulatorStartupArgs(name, mode)
   );
 
   let stdout = '';
@@ -582,7 +581,7 @@ export const startEmulator = async (
           stdout,
           stderr,
           error,
-        }),
+        })
       );
     });
 
@@ -594,7 +593,7 @@ export const startEmulator = async (
           stderr,
           exitCode,
           signal,
-        }),
+        })
       );
     });
   });
@@ -609,13 +608,19 @@ export const startEmulator = async (
       throw error;
     });
 
-  const observationTimeout = wait(EMULATOR_STARTUP_OBSERVATION_TIMEOUT_MS).then(
-    () => 'timeout' as const,
+  const observationTimer = delay(EMULATOR_STARTUP_OBSERVATION_TIMEOUT_MS);
+  const observationTimeout = observationTimer.promise.then(
+    () => 'timeout' as const
   );
 
   try {
     await Promise.race([earlyExit, observedBoot, observationTimeout]);
   } finally {
+    // If `earlyExit` or `observedBoot` won the race, this timer would
+    // otherwise sit ref'd in the event loop for the rest of its 5s;
+    // cancelling here is a no-op on the happy "proceed detached" path
+    // where the timer itself won.
+    observationTimer.cancel();
     cleanup();
   }
 
@@ -626,7 +631,7 @@ export const startEmulator = async (
 
 export const waitForEmulator = async (
   name: string,
-  signal: AbortSignal,
+  signal: AbortSignal
 ): Promise<string> => {
   while (!signal.aborted) {
     const adbIds = await getDeviceIds();
@@ -651,7 +656,7 @@ export const waitForEmulator = async (
 
 export const waitForEmulatorDisconnect = async (
   adbId: string,
-  signal: AbortSignal,
+  signal: AbortSignal
 ): Promise<void> => {
   while (!signal.aborted) {
     const adbIds = await getDeviceIds();
@@ -668,7 +673,7 @@ export const waitForEmulatorDisconnect = async (
 
 export const waitForBoot = async (
   name: string,
-  signal: AbortSignal,
+  signal: AbortSignal
 ): Promise<string> => {
   while (!signal.aborted) {
     const adbIds = await getDeviceIds();
@@ -697,14 +702,14 @@ export const waitForBoot = async (
 
 export const isAppRunning = async (
   adbId: string,
-  bundleId: string,
+  bundleId: string
 ): Promise<boolean> => {
   return (await getAppPid(adbId, bundleId)) != null;
 };
 
 export const getAppPid = async (
   adbId: string,
-  bundleId: string,
+  bundleId: string
 ): Promise<number | null> => {
   try {
     const { stdout } = await spawn(getAdbBinaryPath(), [
@@ -731,7 +736,7 @@ export const getAppPid = async (
 
 export const getAppUid = async (
   adbId: string,
-  bundleId: string,
+  bundleId: string
 ): Promise<number> => {
   const { stdout } = await spawn(getAdbBinaryPath(), [
     '-s',
@@ -756,7 +761,7 @@ export const getAppUid = async (
 
 export const setHideErrorDialogs = async (
   adbId: string,
-  hide: boolean,
+  hide: boolean
 ): Promise<void> => {
   await spawn(getAdbBinaryPath(), [
     '-s',
@@ -785,10 +790,12 @@ export const getLogcatTimestamp = async (adbId: string): Promise<string> => {
 export const startLogcat = (
   adbId: string,
   args: readonly string[],
+  options?: { signal?: AbortSignal }
 ): Subprocess =>
   spawn(getAdbBinaryPath(), ['-s', adbId, ...args], {
     stdout: 'pipe',
     stderr: 'pipe',
+    signal: options?.signal,
   });
 
 export const DROPBOX_CRASH_TAGS = [
@@ -798,7 +805,7 @@ export const DROPBOX_CRASH_TAGS = [
 
 export const getDropboxPrint = async (
   adbId: string,
-  tags: readonly string[] = DROPBOX_CRASH_TAGS,
+  tags: readonly string[] = DROPBOX_CRASH_TAGS
 ): Promise<string> => {
   // Android treats multiple args after --print as one search string, so each
   // tag must be queried separately and merged on the host.
@@ -815,7 +822,7 @@ export const getDropboxPrint = async (
       ]);
 
       return stdout;
-    }),
+    })
   );
 
   return outputs.join('\n');
@@ -823,7 +830,7 @@ export const getDropboxPrint = async (
 
 export const getActivityExitInfo = async (
   adbId: string,
-  bundleId: string,
+  bundleId: string
 ): Promise<string> => {
   const { stdout } = await spawn(getAdbBinaryPath(), [
     '-s',
@@ -891,7 +898,7 @@ export const getConnectedDevices = async (): Promise<AdbDevice[]> => {
 
 export const grantPermissions = async (
   adbId: string,
-  bundleId: string,
+  bundleId: string
 ): Promise<void> => {
   androidAdbLogger.debug('grantPermissions:start %o', {
     adbId,
@@ -908,7 +915,7 @@ export const grantPermissions = async (
     getDangerousPermissions(adbId),
   ]);
   const permissions = requestedPermissions.filter((permission) =>
-    dangerousPermissions.has(permission),
+    dangerousPermissions.has(permission)
   );
 
   androidAdbLogger.debug('grantPermissions:resolved %o', {
@@ -944,7 +951,7 @@ export const grantPermissions = async (
     });
 
     await Promise.all(
-      grantCommands.map((args) => spawn(getAdbBinaryPath(), args as string[])),
+      grantCommands.map((args) => spawn(getAdbBinaryPath(), args as string[]))
     );
 
     androidAdbLogger.debug('grantPermissions:success %o', {

package/src/app-session.ts

@@ -62,14 +62,6 @@ const isCrashSignal = (line: string, bundleId: string): boolean => {
   );
 };
 
-const stopSubprocess = async (child: Subprocess) => {
-  try {
-    (await child.nodeChildProcess).kill();
-  } catch {
-    // Ignore termination failures for already-ended background processes.
-  }
-};
-
 const isExitedState = (
   state: AppSessionState
 ): state is Extract<AppSessionState, { status: 'exited' }> =>
@@ -82,10 +74,20 @@ type CreateAndroidAppSessionOptions = {
   stopApp: () => Promise<void>;
   getAppPid: () => Promise<number | null>;
   getLogcatTimestamp: () => Promise<string>;
-  startLogcat: (args: readonly string[]) => Subprocess;
+  startLogcat: (
+    args: readonly string[],
+    options: { signal: AbortSignal }
+  ) => Subprocess;
   getDropboxOutput?: () => Promise<string>;
   getExitInfo?: () => Promise<string>;
   crashArtifactWriter?: CrashArtifactWriter;
+  /**
+   * Session-lifetime abort signal (see HarnessPlatformInitOptions.signal).
+   * Combined with the app session's own logcatAbortController so that
+   * aborting the session stops the logcat stream even if dispose() hasn't
+   * been called yet (e.g. SIGTERM during teardown of other resources).
+   */
+  signal?: AbortSignal;
 };
 
 export const createAndroidAppSession = async ({
@@ -99,6 +101,7 @@ export const createAndroidAppSession = async ({
   getDropboxOutput,
   getExitInfo,
   crashArtifactWriter,
+  signal,
 }: CreateAndroidAppSessionOptions): Promise<AppSession> => {
   const emitter = createAppSessionEmitter();
   const logBuffer = createBoundedLogBuffer();
@@ -193,7 +196,20 @@ export const createAndroidAppSession = async ({
 
   const logcatTimestamp = await getLogcatTimestamp();
   const sessionStartedAt = Date.now();
-  const logcatProcess = startLogcat(getLogcatArgs(appUid, logcatTimestamp));
+  const logcatAbortController = new AbortController();
+  const logcatSignal = signal
+    ? AbortSignal.any([signal, logcatAbortController.signal])
+    : logcatAbortController.signal;
+  const logcatProcess = startLogcat(getLogcatArgs(appUid, logcatTimestamp), {
+    signal: logcatSignal,
+  });
+  // Aborting is nano-spawn's own cancellation path, so the resulting
+  // SubprocessError is settled the same way regardless of which of the
+  // merged stdout/stderr iterators observes it first. Without this, killing
+  // the underlying process directly can make both iterators reject at once,
+  // and nano-spawn's internal `Promise.race` only reports one of them,
+  // leaving the other an unhandled rejection.
+  logcatProcess.catch(() => undefined);
   const crashReporter = createAndroidCrashReporter({
     bundleId,
     crashArtifactWriter,
@@ -239,7 +255,7 @@ export const createAndroidAppSession = async ({
     disposed = true;
     stopPolling = true;
     emitter.clear();
-    await stopSubprocess(logcatProcess);
+    logcatAbortController.abort();
     await Promise.allSettled([logTask]);
     throw error;
   }
@@ -287,7 +303,7 @@ export const createAndroidAppSession = async ({
       cancelPendingPollDelay();
 
       emitter.clear();
-      await stopSubprocess(logcatProcess);
+      logcatAbortController.abort();
       await stopApp();
       await Promise.allSettled([logTask, pollTask]);
     },

package/src/avd-config.ts

@@ -1,6 +1,7 @@
 import { access, readFile } from 'node:fs/promises';
 import type { AndroidSystemImageArch } from './environment.js';
 import type { AndroidEmulator, AndroidEmulatorAVDConfig } from './config.js';
+import { getEmulatorCpuCores } from './emulator-startup.js';
 
 export type AvdConfig = {
   imageSysdir1?: string;
@@ -8,6 +9,7 @@ export type AvdConfig = {
   hwDeviceName?: string;
   diskDataPartitionSize?: string;
   vmHeapSize?: string;
+  hwCpuNcore?: string;
 };
 
 export type AvdCompatibilityResult =
@@ -123,6 +125,9 @@ export const parseAvdConfig = (contents: string): AvdConfig => {
       case 'vm.heapSize':
         config.vmHeapSize = value;
         break;
+      case 'hw.cpu.ncore':
+        config.hwCpuNcore = value;
+        break;
       default:
         break;
     }
@@ -235,6 +240,18 @@ export const isAvdCompatible = ({
     };
   }
 
+  if (
+    normalizeConfigValue(avdConfig.hwCpuNcore ?? '') !==
+    normalizeConfigValue(String(getEmulatorCpuCores()))
+  ) {
+    return {
+      compatible: false,
+      reason: `CPU core count mismatch: expected ${getEmulatorCpuCores()}, got ${
+        avdConfig.hwCpuNcore ?? 'missing'
+      }.`,
+    };
+  }
+
   return { compatible: true };
 };
 

package/src/emulator-startup.ts

@@ -1,14 +1,37 @@
+import {
+  getDeviceCoreBudget,
+  logger,
+  spawn,
+  SubprocessError,
+} from '@react-native-harness/tools';
+import os from 'node:os';
+import { getEmulatorBinaryPath } from './environment.js';
+
+const emulatorStartupLogger = logger.child('android-emulator-startup');
+
 export type EmulatorBootMode =
   | 'default-boot'
   | 'clean-snapshot-generation'
   | 'snapshot-reuse';
 
+/**
+ * Returns the vCPU count baked into an AVD for this runner.
+ *
+ * AVD snapshots require an identical hardware configuration to load, so all
+ * AVD creation, compatibility, and cache-key callers must use this value on
+ * the same host.
+ */
+export const getEmulatorCpuCores = (): number => {
+  return getDeviceCoreBudget(os.availableParallelism());
+};
+
 const COMMON_EMULATOR_ARGS = [
   '-no-window',
   '-gpu',
   'swiftshader_indirect',
   '-noaudio',
   '-no-boot-anim',
+  '-no-metrics',
 ] as const;
 
 export const getEmulatorStartupArgs = (
@@ -24,3 +47,54 @@ export const getEmulatorStartupArgs = (
 
   return [`@${name}`, ...modeArgs, ...COMMON_EMULATOR_ARGS];
 };
+
+/**
+ * Parses the output of `emulator -accel-check` to determine whether
+ * hardware acceleration (KVM on Linux, HVF on macOS) is usable. The
+ * emulator prints a message containing "is installed and usable" when
+ * acceleration is available.
+ */
+export const isAccelerationUsable = (accelCheckOutput: string): boolean => {
+  return accelCheckOutput.includes('is installed and usable');
+};
+
+/**
+ * Runs `emulator -accel-check` and logs a non-fatal warning when hardware
+ * acceleration (KVM/HVF) appears unavailable, in which case the emulator
+ * falls back to very slow software emulation. This check must never fail or
+ * block emulator startup - any error running it is swallowed and only
+ * debug-logged.
+ */
+export const warnIfEmulatorAccelerationUnavailable =
+  async (): Promise<void> => {
+    let combinedOutput: string;
+
+    try {
+      const emulatorBinaryPath = getEmulatorBinaryPath();
+      const { stdout, stderr } = await spawn(emulatorBinaryPath, [
+        '-accel-check',
+      ]);
+      combinedOutput = `${stdout}\n${stderr}`;
+    } catch (error) {
+      if (error instanceof SubprocessError) {
+        // The check itself ran but exited non-zero - this is how
+        // `-accel-check` reports that acceleration is unavailable, so treat
+        // its output as a normal (non-fatal) result rather than swallowing it.
+        combinedOutput = `${error.stdout}\n${error.stderr}`;
+      } else {
+        // Failed to even run the check (e.g. binary missing). This must never
+        // fail or block emulator startup.
+        emulatorStartupLogger.debug(
+          'Failed to run "emulator -accel-check": %o',
+          error
+        );
+        return;
+      }
+    }
+
+    if (!isAccelerationUsable(combinedOutput)) {
+      logger.warn(
+        'Hardware acceleration (KVM/HVF) appears unavailable for the Android emulator. It will fall back to very slow software emulation.'
+      );
+    }
+  };

package/src/index.ts

@@ -9,5 +9,6 @@ export {
   resolveAvdCachingEnabled,
 } from './avd-config.js';
 export { getHostAndroidSystemImageArch } from './environment.js';
+export { getEmulatorCpuCores } from './emulator-startup.js';
 export { HarnessAppPathError, HarnessEmulatorConfigError } from './errors.js';
 export { getRunTargets } from './targets.js';