@react-native-harness/platform-android 1.3.0 → 1.4.0

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

package/src/instance.ts

@@ -1,12 +1,11 @@
 import {
   AppNotInstalledError,
-  CreateAppMonitorOptions,
   DeviceNotFoundError,
   type HarnessPlatformInitOptions,
   HarnessPlatformRunner,
 } from '@react-native-harness/platforms';
 import type { Config as HarnessConfig } from '@react-native-harness/config';
-import { logger } from '@react-native-harness/tools';
+import { instrumented, logger, noopDiagnostics } from '@react-native-harness/tools';
 import {
   AndroidPlatformConfig,
   assertAndroidDeviceEmulator,
@@ -18,33 +17,25 @@ import {
   resolveAvdCachingEnabled,
 } from './avd-config.js';
 import { getAdbId } from './adb-id.js';
-import * as adb from './adb.js';
+import * as adbModule from './adb.js';
 import {
   applyHarnessDebugHttpHost,
   clearHarnessDebugHttpHost,
 } from './shared-prefs.js';
 import { getDeviceName } from './utils.js';
-import { createAndroidAppMonitor } from './app-monitor.js';
 import { HarnessAppPathError, HarnessEmulatorConfigError } from './errors.js';
 import {
   ensureAndroidEmulatorAvailable,
   ensureAndroidEmulatorEnvironment,
   getHostAndroidSystemImageArch,
 } from './environment.js';
+import { warnIfEmulatorAccelerationUnavailable } from './emulator-startup.js';
 import { isInteractive } from '@react-native-harness/tools';
 import fs from 'node:fs';
-import type { AppMonitor } from '@react-native-harness/platforms';
+import { createAndroidAppSession } from './app-session.js';
 
 const androidInstanceLogger = logger.child('android-instance');
 
-const createNoopAppMonitor = (): AppMonitor => ({
-  start: async () => undefined,
-  stop: async () => undefined,
-  dispose: async () => undefined,
-  addListener: () => undefined,
-  removeListener: () => undefined,
-});
-
 const getHarnessAppPath = (): string => {
   const appPath = process.env.HARNESS_APP_PATH;
 
@@ -76,18 +67,18 @@ const getOptionalHarnessAppPath = (): string | undefined => {
 const configureAndroidRuntime = async (
   adbId: string,
   config: AndroidPlatformConfig,
-  harnessConfig: HarnessConfig,
+  harnessConfig: HarnessConfig
 ): Promise<number> => {
   const metroPort = harnessConfig.metroPort;
 
   await Promise.all([
-    adb.reversePort(adbId, metroPort),
-    adb.reversePort(adbId, 8080),
-    adb.setHideErrorDialogs(adbId, true),
+    adbModule.reversePort(adbId, metroPort),
+    adbModule.reversePort(adbId, 8080),
+    adbModule.setHideErrorDialogs(adbId, true),
     applyHarnessDebugHttpHost(adbId, config.bundleId, `localhost:${metroPort}`),
   ]);
 
-  return adb.getAppUid(adbId, config.bundleId);
+  return adbModule.getAppUid(adbId, config.bundleId);
 };
 
 const startAndWaitForBoot = async ({
@@ -97,11 +88,12 @@ const startAndWaitForBoot = async ({
 }: {
   emulatorName: string;
   signal: AbortSignal;
-  mode?: Parameters<typeof adb.startEmulator>[1];
+  mode?: Parameters<typeof adbModule.startEmulator>[1];
 }): Promise<string> => {
   await ensureAndroidEmulatorAvailable();
-  await adb.startEmulator(emulatorName, mode);
-  return adb.waitForBoot(emulatorName, signal);
+  await warnIfEmulatorAccelerationUnavailable();
+  await adbModule.startEmulator(emulatorName, mode);
+  return adbModule.waitForBoot(emulatorName, signal);
 };
 
 const recreateAvd = async ({
@@ -116,7 +108,7 @@ const recreateAvd = async ({
     throw new HarnessEmulatorConfigError(emulatorConfig.name);
   }
 
-  await adb.createAvd({
+  await adbModule.createAvd({
     name: emulatorConfig.name,
     apiLevel: emulatorConfig.avd.apiLevel,
     profile: emulatorConfig.avd.profile,
@@ -137,7 +129,7 @@ const prepareCachedAvd = async ({
 }): Promise<string> => {
   const emulatorName = emulatorConfig.name;
   const hostArch = getHostAndroidSystemImageArch();
-  const hasExistingAvd = await adb.hasAvd(emulatorName);
+  const hasExistingAvd = await adbModule.hasAvd(emulatorName);
   const avdConfig = hasExistingAvd ? await readAvdConfig(emulatorName) : null;
   const compatibility =
     avdConfig == null
@@ -153,16 +145,16 @@ const prepareCachedAvd = async ({
       hasExistingAvd
         ? 'Recreating incompatible Android emulator %s...'
         : 'Creating Android emulator %s...',
-      emulatorName,
+      emulatorName
     );
 
     if (hasExistingAvd && !compatibility.compatible) {
       androidInstanceLogger.debug(
         'Android AVD %s is not reusable: %s',
         emulatorName,
-        compatibility.reason,
+        compatibility.reason
       );
-      await adb.deleteAvd(emulatorName);
+      await adbModule.deleteAvd(emulatorName);
     }
 
     await recreateAvd({ emulatorConfig });
@@ -174,8 +166,8 @@ const prepareCachedAvd = async ({
     });
 
     logger.info('Saving Android emulator snapshot for %s...', emulatorName);
-    await adb.stopEmulator(generationAdbId);
-    await adb.waitForEmulatorDisconnect(generationAdbId, signal);
+    await adbModule.stopEmulator(generationAdbId);
+    await adbModule.waitForEmulatorDisconnect(generationAdbId, signal);
   } else {
     logger.info('Using cached Android emulator %s...', emulatorName);
   }
@@ -190,10 +182,14 @@ const prepareCachedAvd = async ({
 export const getAndroidEmulatorPlatformInstance = async (
   config: AndroidPlatformConfig,
   harnessConfig: HarnessConfig,
-  init: HarnessPlatformInitOptions,
+  init: HarnessPlatformInitOptions
 ): Promise<HarnessPlatformRunner> => {
   assertAndroidDeviceEmulator(config.device);
-  const detectNativeCrashes = harnessConfig.detectNativeCrashes ?? true;
+  const adb = instrumented(
+    adbModule,
+    'platform.android.adb',
+    init.diagnostics ?? noopDiagnostics
+  );
   const permissionsEnabled = harnessConfig.permissions ?? false;
   const emulatorConfig = config.device;
   const emulatorName = emulatorConfig.name;
@@ -209,7 +205,7 @@ export const getAndroidEmulatorPlatformInstance = async (
   androidInstanceLogger.debug(
     'resolved Android emulator %s with adb id %s',
     emulatorConfig.name,
-    adbId ?? 'not-found',
+    adbId ?? 'not-found'
   );
 
   if (!adbId) {
@@ -229,7 +225,7 @@ export const getAndroidEmulatorPlatformInstance = async (
             logger.info('Creating Android emulator %s...', emulatorName);
             androidInstanceLogger.debug(
               'creating Android AVD %s before startup',
-              emulatorConfig.name,
+              emulatorConfig.name
             );
             await recreateAvd({ emulatorConfig });
           } else {
@@ -238,7 +234,7 @@ export const getAndroidEmulatorPlatformInstance = async (
 
           androidInstanceLogger.debug(
             'starting Android emulator %s',
-            emulatorConfig.name,
+            emulatorConfig.name
           );
           return startAndWaitForBoot({
             emulatorName: emulatorConfig.name,
@@ -251,7 +247,7 @@ export const getAndroidEmulatorPlatformInstance = async (
     androidInstanceLogger.debug(
       'Android emulator %s connected as %s',
       emulatorConfig.name,
-      adbId,
+      adbId
     );
   }
 
@@ -261,7 +257,7 @@ export const getAndroidEmulatorPlatformInstance = async (
 
   androidInstanceLogger.debug(
     'waiting for Android emulator %s to finish booting',
-    adbId,
+    adbId
   );
 
   const isInstalled = await adb.isAppInstalled(adbId, config.bundleId);
@@ -282,27 +278,31 @@ export const getAndroidEmulatorPlatformInstance = async (
   }
 
   return {
-    startApp: async (options) => {
-      await adb.startApp(
-        adbId,
-        config.bundleId,
-        config.activityName,
-        (options as typeof config.appLaunchOptions | undefined) ??
-          config.appLaunchOptions,
-      );
-    },
-    restartApp: async (options) => {
+    createAppSession: async (options) => {
       await adb.stopApp(adbId, config.bundleId);
-      await adb.startApp(
-        adbId,
-        config.bundleId,
-        config.activityName,
+      const launchOptions =
         (options as typeof config.appLaunchOptions | undefined) ??
-          config.appLaunchOptions,
-      );
-    },
-    stopApp: async () => {
-      await adb.stopApp(adbId, config.bundleId);
+        config.appLaunchOptions;
+
+      return await createAndroidAppSession({
+        appUid,
+        bundleId: config.bundleId,
+        startApp: () =>
+          adb.startApp(
+            adbId,
+            config.bundleId,
+            config.activityName,
+            launchOptions
+          ),
+        stopApp: () => adb.stopApp(adbId, config.bundleId),
+        getAppPid: () => adb.getAppPid(adbId, config.bundleId),
+        getLogcatTimestamp: () => adb.getLogcatTimestamp(adbId),
+        startLogcat: (args, options) => adb.startLogcat(adbId, args, options),
+        getDropboxOutput: () => adb.getDropboxPrint(adbId),
+        getExitInfo: () => adb.getActivityExitInfo(adbId, config.bundleId),
+        crashArtifactWriter: init.crashArtifactWriter,
+        signal: init.signal,
+      });
     },
     dispose: async () => {
       await adb.stopApp(adbId, config.bundleId);
@@ -314,30 +314,20 @@ export const getAndroidEmulatorPlatformInstance = async (
         await adb.stopEmulator(adbId);
       }
     },
-    isAppRunning: async () => {
-      return await adb.isAppRunning(adbId, config.bundleId);
-    },
-    createAppMonitor: (options?: CreateAppMonitorOptions) => {
-      if (!detectNativeCrashes) {
-        return createNoopAppMonitor();
-      }
-
-      return createAndroidAppMonitor({
-        adbId,
-        bundleId: config.bundleId,
-        appUid,
-        crashArtifactWriter: options?.crashArtifactWriter,
-      });
-    },
   };
 };
 
 export const getAndroidPhysicalDevicePlatformInstance = async (
   config: AndroidPlatformConfig,
   harnessConfig: HarnessConfig,
+  init?: HarnessPlatformInitOptions
 ): Promise<HarnessPlatformRunner> => {
   assertAndroidDevicePhysical(config.device);
-  const detectNativeCrashes = harnessConfig.detectNativeCrashes ?? true;
+  const adb = instrumented(
+    adbModule,
+    'platform.android.adb',
+    init?.diagnostics ?? noopDiagnostics
+  );
   const permissionsEnabled = harnessConfig.permissions ?? false;
 
   const adbId = await getAdbId(config.device);
@@ -351,7 +341,7 @@ export const getAndroidPhysicalDevicePlatformInstance = async (
   if (!isInstalled) {
     throw new AppNotInstalledError(
       config.bundleId,
-      getDeviceName(config.device),
+      getDeviceName(config.device)
     );
   }
 
@@ -362,47 +352,36 @@ export const getAndroidPhysicalDevicePlatformInstance = async (
   }
 
   return {
-    startApp: async (options) => {
-      await adb.startApp(
-        adbId,
-        config.bundleId,
-        config.activityName,
-        (options as typeof config.appLaunchOptions | undefined) ??
-          config.appLaunchOptions,
-      );
-    },
-    restartApp: async (options) => {
+    createAppSession: async (options) => {
       await adb.stopApp(adbId, config.bundleId);
-      await adb.startApp(
-        adbId,
-        config.bundleId,
-        config.activityName,
+      const launchOptions =
         (options as typeof config.appLaunchOptions | undefined) ??
-          config.appLaunchOptions,
-      );
-    },
-    stopApp: async () => {
-      await adb.stopApp(adbId, config.bundleId);
+        config.appLaunchOptions;
+
+      return await createAndroidAppSession({
+        appUid,
+        bundleId: config.bundleId,
+        startApp: () =>
+          adb.startApp(
+            adbId,
+            config.bundleId,
+            config.activityName,
+            launchOptions
+          ),
+        stopApp: () => adb.stopApp(adbId, config.bundleId),
+        getAppPid: () => adb.getAppPid(adbId, config.bundleId),
+        getLogcatTimestamp: () => adb.getLogcatTimestamp(adbId),
+        startLogcat: (args, options) => adb.startLogcat(adbId, args, options),
+        getDropboxOutput: () => adb.getDropboxPrint(adbId),
+        getExitInfo: () => adb.getActivityExitInfo(adbId, config.bundleId),
+        crashArtifactWriter: init?.crashArtifactWriter,
+        signal: init?.signal,
+      });
     },
     dispose: async () => {
       await adb.stopApp(adbId, config.bundleId);
       await clearHarnessDebugHttpHost(adbId, config.bundleId);
       await adb.setHideErrorDialogs(adbId, false);
     },
-    isAppRunning: async () => {
-      return await adb.isAppRunning(adbId, config.bundleId);
-    },
-    createAppMonitor: (options?: CreateAppMonitorOptions) => {
-      if (!detectNativeCrashes) {
-        return createNoopAppMonitor();
-      }
-
-      return createAndroidAppMonitor({
-        adbId,
-        bundleId: config.bundleId,
-        appUid,
-        crashArtifactWriter: options?.crashArtifactWriter,
-      });
-    },
   };
 };

package/src/runner.ts

@@ -1,7 +1,4 @@
-import {
-  HarnessPlatformRunner,
-  type HarnessPlatformInitOptions,
-} from '@react-native-harness/platforms';
+import { type HarnessPlatformRunnerFactory } from '@react-native-harness/platforms';
 import type { Config as HarnessConfig } from '@react-native-harness/config';
 import {
   AndroidPlatformConfigSchema,
@@ -17,11 +14,10 @@ import {
   initializeAndroidProcessEnv,
 } from './environment.js';
 
-const getAndroidRunner = async (
-  config: AndroidPlatformConfig,
-  harnessConfig: HarnessConfig,
-  init: HarnessPlatformInitOptions,
-): Promise<HarnessPlatformRunner> => {
+const getAndroidRunner: HarnessPlatformRunnerFactory<
+  AndroidPlatformConfig,
+  HarnessConfig
+> = async (config, harnessConfig, init) => {
   const parsedConfig = AndroidPlatformConfigSchema.parse(config);
 
   initializeAndroidProcessEnv();
@@ -32,11 +28,15 @@ const getAndroidRunner = async (
     return getAndroidEmulatorPlatformInstance(
       parsedConfig,
       harnessConfig,
-      init,
+      init
     );
   }
 
-  return getAndroidPhysicalDevicePlatformInstance(parsedConfig, harnessConfig);
+  return getAndroidPhysicalDevicePlatformInstance(
+    parsedConfig,
+    harnessConfig,
+    init
+  );
 };
 
 export default getAndroidRunner;

package/test/setup.ts

@@ -57,6 +57,7 @@ vi.mock('../src/adb.js', async (importOriginal) => {
     waitForEmulatorDisconnect: vi.fn().mockResolvedValue(undefined),
     waitForBoot: vi.fn().mockResolvedValue('emulator-5554'),
     isAppRunning: vi.fn().mockResolvedValue(false),
+    getAppPid: vi.fn().mockResolvedValue(null),
     getAppUid: vi.fn().mockResolvedValue(0),
     setHideErrorDialogs: vi.fn().mockResolvedValue(undefined),
     getLogcatTimestamp: vi.fn().mockResolvedValue('01-01 00:00:00.000'),