@react-native-harness/platform-android 1.1.0-rc.1 → 1.1.0-rc.3

package/src/instance.ts

@@ -0,0 +1,380 @@
+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 {
+  AndroidPlatformConfig,
+  assertAndroidDeviceEmulator,
+  assertAndroidDevicePhysical,
+} from './config.js';
+import {
+  isAvdCompatible,
+  readAvdConfig,
+  resolveAvdCachingEnabled,
+} from './avd-config.js';
+import { getAdbId } from './adb-id.js';
+import * as adb 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 {
+  ensureAndroidEmulatorEnvironment,
+  getHostAndroidSystemImageArch,
+} from './environment.js';
+import { isInteractive } from '@react-native-harness/tools';
+import fs from 'node:fs';
+import type { AppMonitor } from '@react-native-harness/platforms';
+
+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;
+
+  if (!appPath) {
+    throw new HarnessAppPathError('missing');
+  }
+
+  if (!fs.existsSync(appPath)) {
+    throw new HarnessAppPathError('invalid', appPath);
+  }
+
+  return appPath;
+};
+
+const configureAndroidRuntime = async (
+  adbId: string,
+  config: AndroidPlatformConfig,
+  harnessConfig: HarnessConfig
+): Promise<number> => {
+  const metroPort = harnessConfig.metroPort;
+
+  await Promise.all([
+    adb.reversePort(adbId, metroPort),
+    adb.reversePort(adbId, 8080),
+    adb.setHideErrorDialogs(adbId, true),
+    applyHarnessDebugHttpHost(adbId, config.bundleId, `localhost:${metroPort}`),
+  ]);
+
+  return adb.getAppUid(adbId, config.bundleId);
+};
+
+const startAndWaitForBoot = async ({
+  emulatorName,
+  signal,
+  mode,
+}: {
+  emulatorName: string;
+  signal: AbortSignal;
+  mode?: Parameters<typeof adb.startEmulator>[1];
+}): Promise<string> => {
+  await adb.startEmulator(emulatorName, mode);
+  return adb.waitForBoot(emulatorName, signal);
+};
+
+const recreateAvd = async ({
+  emulatorConfig,
+}: {
+  emulatorConfig: Extract<
+    AndroidPlatformConfig['device'],
+    { type: 'emulator' }
+  >;
+}): Promise<void> => {
+  if (!emulatorConfig.avd) {
+    throw new HarnessEmulatorConfigError(emulatorConfig.name);
+  }
+
+  await adb.createAvd({
+    name: emulatorConfig.name,
+    apiLevel: emulatorConfig.avd.apiLevel,
+    profile: emulatorConfig.avd.profile,
+    diskSize: emulatorConfig.avd.diskSize,
+    heapSize: emulatorConfig.avd.heapSize,
+  });
+};
+
+const prepareCachedAvd = async ({
+  emulatorConfig,
+  signal,
+}: {
+  emulatorConfig: Extract<
+    AndroidPlatformConfig['device'],
+    { type: 'emulator' }
+  >;
+  signal: AbortSignal;
+}): Promise<string> => {
+  const emulatorName = emulatorConfig.name;
+  const hostArch = getHostAndroidSystemImageArch();
+  const hasExistingAvd = await adb.hasAvd(emulatorName);
+  const avdConfig = hasExistingAvd ? await readAvdConfig(emulatorName) : null;
+  const compatibility =
+    avdConfig == null
+      ? { compatible: false as const, reason: 'Missing AVD config.ini.' }
+      : isAvdCompatible({
+          emulator: emulatorConfig,
+          avdConfig,
+          hostArch,
+        });
+
+  if (!hasExistingAvd || !compatibility.compatible) {
+    logger.info(
+      hasExistingAvd
+        ? 'Recreating incompatible Android emulator %s...'
+        : 'Creating Android emulator %s...',
+      emulatorName
+    );
+
+    if (hasExistingAvd && !compatibility.compatible) {
+      androidInstanceLogger.debug(
+        'Android AVD %s is not reusable: %s',
+        emulatorName,
+        compatibility.reason
+      );
+      await adb.deleteAvd(emulatorName);
+    }
+
+    await recreateAvd({ emulatorConfig });
+
+    const generationAdbId = await startAndWaitForBoot({
+      emulatorName,
+      signal,
+      mode: 'clean-snapshot-generation',
+    });
+
+    logger.info('Saving Android emulator snapshot for %s...', emulatorName);
+    await adb.stopEmulator(generationAdbId);
+    await adb.waitForEmulatorDisconnect(generationAdbId, signal);
+  } else {
+    logger.info('Using cached Android emulator %s...', emulatorName);
+  }
+
+  return startAndWaitForBoot({
+    emulatorName,
+    signal,
+    mode: 'snapshot-reuse',
+  });
+};
+
+export const getAndroidEmulatorPlatformInstance = async (
+  config: AndroidPlatformConfig,
+  harnessConfig: HarnessConfig,
+  init: HarnessPlatformInitOptions
+): Promise<HarnessPlatformRunner> => {
+  assertAndroidDeviceEmulator(config.device);
+  const detectNativeCrashes = harnessConfig.detectNativeCrashes ?? true;
+  const emulatorConfig = config.device;
+  const emulatorName = emulatorConfig.name;
+  const avdConfig = emulatorConfig.avd;
+  const avdCachingEnabled = resolveAvdCachingEnabled({
+    avd: avdConfig,
+    isInteractive: isInteractive(),
+  });
+
+  let adbId = await getAdbId(emulatorConfig);
+  let startedByHarness = false;
+
+  androidInstanceLogger.debug(
+    'resolved Android emulator %s with adb id %s',
+    emulatorConfig.name,
+    adbId ?? 'not-found'
+  );
+
+  if (!adbId) {
+    if (!avdConfig) {
+      throw new HarnessEmulatorConfigError(emulatorConfig.name);
+    }
+
+    await ensureAndroidEmulatorEnvironment(avdConfig.apiLevel);
+
+    adbId = avdCachingEnabled
+      ? await prepareCachedAvd({
+          emulatorConfig,
+          signal: init.signal,
+        })
+      : await (async () => {
+          if (!(await adb.hasAvd(emulatorConfig.name))) {
+            logger.info('Creating Android emulator %s...', emulatorName);
+            androidInstanceLogger.debug(
+              'creating Android AVD %s before startup',
+              emulatorConfig.name
+            );
+            await recreateAvd({ emulatorConfig });
+          } else {
+            logger.info('Using existing Android emulator %s...', emulatorName);
+          }
+
+          androidInstanceLogger.debug(
+            'starting Android emulator %s',
+            emulatorConfig.name
+          );
+          return startAndWaitForBoot({
+            emulatorName: emulatorConfig.name,
+            signal: init.signal,
+          });
+        })();
+
+    startedByHarness = true;
+
+    androidInstanceLogger.debug(
+      'Android emulator %s connected as %s',
+      emulatorConfig.name,
+      adbId
+    );
+  } else if (emulatorConfig.avd) {
+    await ensureAndroidEmulatorEnvironment(emulatorConfig.avd.apiLevel);
+  }
+
+  if (!adbId) {
+    throw new DeviceNotFoundError(getDeviceName(emulatorConfig));
+  }
+
+  androidInstanceLogger.debug(
+    'waiting for Android emulator %s to finish booting',
+    adbId
+  );
+
+  const isInstalled = await adb.isAppInstalled(adbId, config.bundleId);
+
+  if (!isInstalled) {
+    const appPath = getHarnessAppPath();
+    await adb.installApp(adbId, appPath);
+  }
+
+  const appUid = await configureAndroidRuntime(adbId, config, harnessConfig);
+
+  return {
+    startApp: async (options) => {
+      await adb.startApp(
+        adbId,
+        config.bundleId,
+        config.activityName,
+        (options as typeof config.appLaunchOptions | undefined) ??
+          config.appLaunchOptions
+      );
+    },
+    restartApp: async (options) => {
+      await adb.stopApp(adbId, config.bundleId);
+      await adb.startApp(
+        adbId,
+        config.bundleId,
+        config.activityName,
+        (options as typeof config.appLaunchOptions | undefined) ??
+          config.appLaunchOptions
+      );
+    },
+    stopApp: async () => {
+      await adb.stopApp(adbId, config.bundleId);
+    },
+    dispose: async () => {
+      await adb.stopApp(adbId, config.bundleId);
+      await clearHarnessDebugHttpHost(adbId, config.bundleId);
+      await adb.setHideErrorDialogs(adbId, false);
+
+      if (startedByHarness) {
+        logger.info('Shutting down Android emulator %s...', emulatorName);
+        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
+): Promise<HarnessPlatformRunner> => {
+  assertAndroidDevicePhysical(config.device);
+  const detectNativeCrashes = harnessConfig.detectNativeCrashes ?? true;
+
+  const adbId = await getAdbId(config.device);
+
+  if (!adbId) {
+    throw new DeviceNotFoundError(getDeviceName(config.device));
+  }
+
+  const isInstalled = await adb.isAppInstalled(adbId, config.bundleId);
+
+  if (!isInstalled) {
+    throw new AppNotInstalledError(
+      config.bundleId,
+      getDeviceName(config.device)
+    );
+  }
+
+  const appUid = await configureAndroidRuntime(adbId, config, harnessConfig);
+
+  return {
+    startApp: async (options) => {
+      await adb.startApp(
+        adbId,
+        config.bundleId,
+        config.activityName,
+        (options as typeof config.appLaunchOptions | undefined) ??
+          config.appLaunchOptions
+      );
+    },
+    restartApp: async (options) => {
+      await adb.stopApp(adbId, config.bundleId);
+      await adb.startApp(
+        adbId,
+        config.bundleId,
+        config.activityName,
+        (options as typeof config.appLaunchOptions | undefined) ??
+          config.appLaunchOptions
+      );
+    },
+    stopApp: async () => {
+      await adb.stopApp(adbId, config.bundleId);
+    },
+    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,85 +1,47 @@
 import {
-  DeviceNotFoundError,
-  AppNotInstalledError,
-  CreateAppMonitorOptions,
   HarnessPlatformRunner,
+  type HarnessPlatformInitOptions,
 } from '@react-native-harness/platforms';
-import { Config } from '@react-native-harness/config';
+import type { Config as HarnessConfig } from '@react-native-harness/config';
 import {
   AndroidPlatformConfigSchema,
   type AndroidPlatformConfig,
+  isAndroidDeviceEmulator,
 } from './config.js';
-import { getAdbId } from './adb-id.js';
-import * as adb from './adb.js';
-import { getDeviceName } from './utils.js';
-import { createAndroidAppMonitor } from './app-monitor.js';
+import {
+  getAndroidEmulatorPlatformInstance,
+  getAndroidPhysicalDevicePlatformInstance,
+} from './instance.js';
+import {
+  ensureAndroidEmulatorEnvironment,
+  ensureAndroidPhysicalDeviceEnvironment,
+  initializeAndroidProcessEnv,
+} from './environment.js';
 
 const getAndroidRunner = async (
   config: AndroidPlatformConfig,
-  harnessConfig: Config
+  harnessConfig: HarnessConfig,
+  init: HarnessPlatformInitOptions
 ): Promise<HarnessPlatformRunner> => {
   const parsedConfig = AndroidPlatformConfigSchema.parse(config);
-  const adbId = await getAdbId(parsedConfig.device);
 
-  if (!adbId) {
-    throw new DeviceNotFoundError(getDeviceName(parsedConfig.device));
-  }
+  initializeAndroidProcessEnv();
 
-  const isInstalled = await adb.isAppInstalled(adbId, parsedConfig.bundleId);
+  if (isAndroidDeviceEmulator(parsedConfig.device)) {
+    if (parsedConfig.device.avd) {
+      await ensureAndroidEmulatorEnvironment(parsedConfig.device.avd.apiLevel);
+    }
 
-  if (!isInstalled) {
-    throw new AppNotInstalledError(
-      parsedConfig.bundleId,
-      getDeviceName(parsedConfig.device)
+    return getAndroidEmulatorPlatformInstance(
+      parsedConfig,
+      harnessConfig,
+      init
     );
   }
 
-  await Promise.all([
-    adb.reversePort(adbId, 8081),
-    adb.reversePort(adbId, 8080),
-    adb.reversePort(adbId, harnessConfig.webSocketPort),
-    adb.setHideErrorDialogs(adbId, true),
-  ]);
-  const appUid = await adb.getAppUid(adbId, parsedConfig.bundleId);
+  await ensureAndroidPhysicalDeviceEnvironment();
 
-  return {
-    startApp: async (options) => {
-      await adb.startApp(
-        adbId,
-        parsedConfig.bundleId,
-        parsedConfig.activityName,
-        (options as typeof parsedConfig.appLaunchOptions | undefined) ??
-          parsedConfig.appLaunchOptions
-      );
-    },
-    restartApp: async (options) => {
-      await adb.stopApp(adbId, parsedConfig.bundleId);
-      await adb.startApp(
-        adbId,
-        parsedConfig.bundleId,
-        parsedConfig.activityName,
-        (options as typeof parsedConfig.appLaunchOptions | undefined) ??
-          parsedConfig.appLaunchOptions
-      );
-    },
-    stopApp: async () => {
-      await adb.stopApp(adbId, parsedConfig.bundleId);
-    },
-    dispose: async () => {
-      await adb.stopApp(adbId, parsedConfig.bundleId);
-      await adb.setHideErrorDialogs(adbId, false);
-    },
-    isAppRunning: async () => {
-      return await adb.isAppRunning(adbId, parsedConfig.bundleId);
-    },
-    createAppMonitor: (options?: CreateAppMonitorOptions) =>
-      createAndroidAppMonitor({
-        adbId,
-        bundleId: parsedConfig.bundleId,
-        appUid,
-        crashArtifactWriter: options?.crashArtifactWriter,
-      }),
-  };
+  return getAndroidPhysicalDevicePlatformInstance(parsedConfig, harnessConfig);
 };
 
 export default getAndroidRunner;

package/src/shared-prefs.ts

@@ -0,0 +1,205 @@
+import { spawn, SubprocessError } from '@react-native-harness/tools';
+
+const DEBUG_HTTP_HOST_BLOCK_START =
+  '<!-- react-native-harness:debug_http_host:start -->';
+const DEBUG_HTTP_HOST_BLOCK_END =
+  '<!-- react-native-harness:debug_http_host:end -->';
+const DEBUG_HTTP_HOST_BACKUP_KEY = 'harness_debug_http_host_backup';
+
+const getSharedPrefsPath = (bundleId: string) =>
+  `shared_prefs/${bundleId}_preferences.xml`;
+
+const escapeRegExp = (value: string): string =>
+  value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+const escapeXml = (value: string): string =>
+  value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+
+const unescapeXml = (value: string): string =>
+  value
+    .replaceAll('&apos;', "'")
+    .replaceAll('&quot;', '"')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&lt;', '<')
+    .replaceAll('&amp;', '&');
+
+const getStringPreferenceRegex = (key: string) =>
+  new RegExp(
+    `<string\\s+name="${escapeRegExp(key)}">([\\s\\S]*?)<\\/string>`,
+    'g'
+  );
+
+const getStringPreferenceValue = (
+  content: string,
+  key: string
+): string | null => {
+  const matches = [...content.matchAll(getStringPreferenceRegex(key))];
+  const value = matches.at(-1)?.[1];
+
+  return value == null ? null : unescapeXml(value);
+};
+
+const renameStringPreference = (
+  content: string,
+  fromKey: string,
+  toKey: string
+): string =>
+  content.replace(
+    new RegExp(
+      `(<string\\s+name=")${escapeRegExp(fromKey)}(">[\\s\\S]*?<\\/string>)`,
+      'g'
+    ),
+    `$1${toKey}$2`
+  );
+
+const stripStringPreference = (content: string, key: string): string =>
+  content.replace(
+    new RegExp(
+      `\\s*<string\\s+name="${escapeRegExp(key)}">[\\s\\S]*?<\\/string>\\s*`,
+      'g'
+    ),
+    '\n'
+  );
+
+const normalizeEmptyMap = (content: string): string =>
+  content.replace(/<map\s*\/>/g, '<map>\n</map>');
+
+const getHarnessDebugHttpHostBlock = (host: string) =>
+  [
+    DEBUG_HTTP_HOST_BLOCK_START,
+    `<string name="debug_http_host">${escapeXml(host)}</string>`,
+    DEBUG_HTTP_HOST_BLOCK_END,
+  ].join('\n');
+
+const stripHarnessDebugHttpHostBlock = (content: string): string =>
+  content.replace(
+    new RegExp(
+      `\\s*${escapeRegExp(
+        DEBUG_HTTP_HOST_BLOCK_START
+      )}\\s*\\n[\\s\\S]*?\\n\\s*${escapeRegExp(DEBUG_HTTP_HOST_BLOCK_END)}\\s*`,
+      'g'
+    ),
+    '\n'
+  );
+
+const normalizeSharedPrefsContent = (content: string | null): string => {
+  if (!content?.trim()) {
+    return ['<?xml version="1.0" encoding="utf-8"?>', '<map>', '</map>'].join(
+      '\n'
+    );
+  }
+
+  return normalizeEmptyMap(stripHarnessDebugHttpHostBlock(content)).trim();
+};
+
+const insertBeforeClosingMap = (content: string, block: string): string => {
+  if (!content.includes('</map>')) {
+    throw new Error('Android shared preferences file is missing </map>.');
+  }
+
+  return content.replace(
+    /<\/map>\s*$/,
+    `  ${block.replace(/\n/g, '\n  ')}\n</map>`
+  );
+};
+
+const readSharedPrefsFile = async (
+  adbId: string,
+  bundleId: string
+): Promise<string | null> => {
+  try {
+    const { stdout } = await spawn('adb', [
+      '-s',
+      adbId,
+      'shell',
+      `run-as ${bundleId} cat ${getSharedPrefsPath(bundleId)}`,
+    ]);
+    return stdout;
+  } catch (error) {
+    if (error instanceof SubprocessError && error.exitCode === 1) {
+      return null;
+    }
+
+    throw error;
+  }
+};
+
+const writeSharedPrefsFile = async (
+  adbId: string,
+  bundleId: string,
+  content: string
+): Promise<void> => {
+  await spawn(
+    'adb',
+    [
+      '-s',
+      adbId,
+      'shell',
+      `run-as ${bundleId} sh -c 'mkdir -p shared_prefs && cat > ${getSharedPrefsPath(
+        bundleId
+      )}'`,
+    ],
+    { stdin: { string: `${content.trim()}\n` } }
+  );
+};
+
+export const applyHarnessDebugHttpHost = async (
+  adbId: string,
+  bundleId: string,
+  host: string
+): Promise<void> => {
+  const existingContent = await readSharedPrefsFile(adbId, bundleId);
+  const normalizedContent = normalizeSharedPrefsContent(existingContent);
+  const existingHost = getStringPreferenceValue(
+    normalizedContent,
+    'debug_http_host'
+  );
+  const contentWithBackup =
+    existingHost == null
+      ? normalizedContent
+      : renameStringPreference(
+          stripStringPreference(normalizedContent, DEBUG_HTTP_HOST_BACKUP_KEY),
+          'debug_http_host',
+          DEBUG_HTTP_HOST_BACKUP_KEY
+        );
+  const nextContent = insertBeforeClosingMap(
+    contentWithBackup,
+    getHarnessDebugHttpHostBlock(host)
+  );
+  await writeSharedPrefsFile(adbId, bundleId, nextContent);
+};
+
+export const clearHarnessDebugHttpHost = async (
+  adbId: string,
+  bundleId: string
+): Promise<void> => {
+  const existingContent = await readSharedPrefsFile(adbId, bundleId);
+
+  if (!existingContent) {
+    return;
+  }
+
+  const nextContentWithoutHarnessBlock =
+    stripHarnessDebugHttpHostBlock(existingContent).trim();
+
+  if (nextContentWithoutHarnessBlock === existingContent.trim()) {
+    return;
+  }
+
+  const restoredContent = renameStringPreference(
+    nextContentWithoutHarnessBlock,
+    DEBUG_HTTP_HOST_BACKUP_KEY,
+    'debug_http_host'
+  );
+
+  await writeSharedPrefsFile(
+    adbId,
+    bundleId,
+    normalizeEmptyMap(restoredContent).trim()
+  );
+};