@react-native-harness/cli 1.0.0-alpha.9 → 1.0.0-canary.1761046904277

package/src/errors/errorHandler.ts

@@ -13,6 +13,7 @@ import {
   AppNotInstalledError,
   BridgeTimeoutError,
   BundlingFailedError,
+  MetroPortUnavailableError,
 } from './errors.js';
 
 export const handleError = (error: unknown): void => {
@@ -128,10 +129,14 @@ export const handleError = (error: unknown): void => {
     console.error(`\nPlease check your bridge connection and try again.`);
   } else if (error instanceof AppNotInstalledError) {
     console.error(`\n❌ App Not Installed`);
+    const deviceType =
+      error.platform === 'ios'
+        ? 'simulator'
+        : error.platform === 'android'
+        ? 'emulator'
+        : 'virtual device';
     console.error(
-      `\nThe app "${error.bundleId}" is not installed on ${
-        error.platform === 'ios' ? 'simulator' : 'emulator'
-      } "${error.deviceName}".`
+      `\nThe app "${error.bundleId}" is not installed on ${deviceType} "${error.deviceName}".`
     );
     console.error(`\nTo resolve this issue:`);
     if (error.platform === 'ios') {
@@ -141,13 +146,21 @@ export const handleError = (error: unknown): void => {
       console.error(
         `  • Or install from Xcode: Open ios/*.xcworkspace and run the project`
       );
-    } else {
+    } else if (error.platform === 'android') {
       console.error(
         `  • Build and install the app: npx react-native run-android`
       );
       console.error(
         `  • Or build manually: ./gradlew assembleDebug && adb install android/app/build/outputs/apk/debug/app-debug.apk`
       );
+    } else if (error.platform === 'vega') {
+      console.error(`  • Build the Vega app: npm run build:app`);
+      console.error(
+        `  • Install the app: kepler device install-app -p <path-to-vpkg> --device "${error.deviceName}"`
+      );
+      console.error(
+        `  • Or use the combined command: kepler run-kepler <path-to-vpkg> "${error.bundleId}" -d "${error.deviceName}"`
+      );
     }
     console.error(`\nPlease install the app and try running the tests again.`);
   } else if (error instanceof BundlingFailedError) {
@@ -189,6 +202,23 @@ export const handleError = (error: unknown): void => {
     console.error(
       `\nIf the app needs more time to start, consider increasing the timeout in the configuration.`
     );
+  } else if (error instanceof MetroPortUnavailableError) {
+    console.error(`\n❌ Metro Port Unavailable`);
+    console.error(`\nPort ${error.port} is already in use or unavailable.`);
+    console.error(`\nThis usually indicates that:`);
+    console.error(`  • Another Metro bundler instance is already running`);
+    console.error(`  • Another application is using port ${error.port}`);
+    console.error(`  • The port is blocked by a firewall or security software`);
+    console.error(`\nTo resolve this issue:`);
+    console.error(`  • Stop any running Metro bundler instances`);
+    console.error(
+      `  • Check for other applications using port ${error.port}: lsof -i :${error.port}`
+    );
+    console.error(`  • Kill the process using the port: kill -9 <PID>`);
+    console.error(
+      `  • Or use a different port by updating your Metro configuration`
+    );
+    console.error(`\nPlease free up the port and try again.`);
   } else {
     console.error(`\n❌ Unexpected Error`);
     console.error(error);

package/src/errors/errors.ts

@@ -97,12 +97,17 @@ export class AppNotInstalledError extends Error {
   constructor(
     public readonly deviceName: string,
     public readonly bundleId: string,
-    public readonly platform: 'ios' | 'android'
+    public readonly platform: 'ios' | 'android' | 'vega'
   ) {
+    const deviceType =
+      platform === 'ios'
+        ? 'simulator'
+        : platform === 'android'
+        ? 'emulator'
+        : 'virtual device';
+
     super(
-      `App "${bundleId}" is not installed on ${
-        platform === 'ios' ? 'simulator' : 'emulator'
-      } "${deviceName}"`
+      `App "${bundleId}" is not installed on ${deviceType} "${deviceName}"`
     );
     this.name = 'AppNotInstalledError';
   }
@@ -117,3 +122,10 @@ export class BundlingFailedError extends Error {
     this.name = 'BundlingFailedError';
   }
 }
+
+export class MetroPortUnavailableError extends Error {
+  constructor(public readonly port: number) {
+    super(`Metro port ${port} is not available`);
+    this.name = 'MetroPortUnavailableError';
+  }
+}

package/src/external.ts

@@ -0,0 +1,44 @@
+import { TestRunnerConfig } from '@react-native-harness/config';
+import { Environment } from './platforms/platform-adapter.js';
+import {
+  BridgeServer,
+  getBridgeServer,
+} from '@react-native-harness/bridge/server';
+import { BridgeTimeoutError } from './errors/errors.js';
+import { getPlatformAdapter } from './platforms/platform-registry.js';
+
+export type Harness = {
+  environment: Environment;
+  bridge: BridgeServer;
+};
+
+export const getHarness = async (
+  runner: TestRunnerConfig
+): Promise<Harness> => {
+  const bridgeTimeout = 60000;
+  const platformAdapter = await getPlatformAdapter(runner.platform);
+  const serverBridge = await getBridgeServer({
+    port: 3001,
+  });
+
+  const readyPromise = new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      reject(
+        new BridgeTimeoutError(bridgeTimeout, runner.name, runner.platform)
+      );
+    }, bridgeTimeout);
+
+    serverBridge.once('ready', () => {
+      clearTimeout(timeout);
+      resolve();
+    });
+  });
+
+  const environment = await platformAdapter.getEnvironment(runner);
+  await readyPromise;
+
+  return {
+    environment,
+    bridge: serverBridge,
+  };
+};

package/src/index.ts

@@ -13,14 +13,20 @@ const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
 
 const program = new Command();
 
-logger.setVerbose(true);
-
 program
   .name('react-native-harness')
   .description(
     'React Native Test Harness - A comprehensive testing framework for React Native applications'
   )
-  .version(packageJson.version);
+  .version(packageJson.version)
+  .option('-v, --verbose', 'Enable verbose logging')
+  .hook('preAction', (thisCommand) => {
+    // Handle global verbose option
+    const opts = thisCommand.optsWithGlobals();
+    if (opts.verbose) {
+      logger.setVerbose(true);
+    }
+  });
 
 program
   .command('test')
@@ -33,9 +39,31 @@ program
     '[pattern]',
     'glob pattern to match test files (uses config.include if not specified)'
   )
-  .action(async (runner, pattern) => {
+  .option(
+    '-t, --testNamePattern <pattern>',
+    'Run only tests with names matching regex pattern'
+  )
+  .option(
+    '--testPathPattern <pattern>',
+    'Run only test files with paths matching regex pattern'
+  )
+  .option(
+    '--testPathIgnorePatterns <patterns...>',
+    'Ignore test files matching these patterns'
+  )
+  .option(
+    '--testMatch <patterns...>',
+    'Override config.include with these glob patterns'
+  )
+  .action(async (runner, pattern, options) => {
     try {
-      await testCommand(runner, pattern);
+      // Convert CLI pattern argument to testMatch option
+      const mergedOptions = {
+        ...options,
+        testMatch: pattern ? [pattern] : options.testMatch,
+      };
+
+      await testCommand(runner, mergedOptions);
     } catch (error) {
       handleError(error);
       process.exit(1);

package/src/platforms/android/emulator.ts

@@ -7,7 +7,13 @@ export const getEmulatorNameFromId = async (
   emulatorId: string
 ): Promise<string | null> => {
   try {
-    const { stdout } = await spawn('adb', ['-s', emulatorId, 'emu', 'avd', 'name']);
+    const { stdout } = await spawn('adb', [
+      '-s',
+      emulatorId,
+      'emu',
+      'avd',
+      'name',
+    ]);
     const avdName = stdout.split('\n')[0].trim();
     return avdName || null;
   } catch {
@@ -48,7 +54,13 @@ export const getEmulatorStatus = async (
 
   try {
     // Check if device is fully booted by checking boot completion
-    const { stdout } = await spawn('adb', ['-s', emulatorId, 'shell', 'getprop', 'sys.boot_completed']);
+    const { stdout } = await spawn('adb', [
+      '-s',
+      emulatorId,
+      'shell',
+      'getprop',
+      'sys.boot_completed',
+    ]);
     const bootCompleted = stdout.trim() === '1';
     return bootCompleted ? 'running' : 'loading';
   } catch {
@@ -69,17 +81,17 @@ export const runEmulator = async (name: string): Promise<ChildProcess> => {
       return;
     } else if (status === 'loading') {
       // Check again in 2 seconds
-      await new Promise(resolve => setTimeout(resolve, 2000));
+      await new Promise((resolve) => setTimeout(resolve, 2000));
       await checkStatus();
     } else {
       // Still stopped, check again in 1 second
-      await new Promise(resolve => setTimeout(resolve, 1000));
+      await new Promise((resolve) => setTimeout(resolve, 1000));
       await checkStatus();
     }
   };
 
   // Start checking status after a brief delay to allow emulator to start
-  await new Promise(resolve => setTimeout(resolve, 3000));
+  await new Promise((resolve) => setTimeout(resolve, 3000));
   await checkStatus();
 
   return nodeChildProcess;
@@ -105,7 +117,15 @@ export const isAppInstalled = async (
   bundleId: string
 ): Promise<boolean> => {
   try {
-    const { stdout } = await spawn('adb', ['-s', emulatorId, 'shell', 'pm', 'list', 'packages', bundleId]);
+    const { stdout } = await spawn('adb', [
+      '-s',
+      emulatorId,
+      'shell',
+      'pm',
+      'list',
+      'packages',
+      bundleId,
+    ]);
     return stdout.trim() !== '';
   } catch {
     return false;
@@ -115,25 +135,3 @@ export const isAppInstalled = async (
 export const reversePort = async (port: number): Promise<void> => {
   await spawn('adb', ['reverse', `tcp:${port}`, `tcp:${port}`]);
 };
-
-export const getEmulatorScreenshot = async (
-  emulatorId: string,
-  name: string = `${emulatorId}-${new Date()
-    .toISOString()
-    .replace(/:/g, '-')
-    .replace(/\//g, '-')}.png`
-): Promise<string> => {
-  // Use screencap to save directly to device, then pull the file
-  const devicePath = '/sdcard/screenshot.png';
-
-  // Take screenshot and save to device
-  await spawn('adb', ['-s', emulatorId, 'shell', 'screencap', '-p', devicePath]);
-
-  // Pull the file from device to local
-  await spawn('adb', ['-s', emulatorId, 'pull', devicePath, name]);
-
-  // Clean up the file on device
-  await spawn('adb', ['-s', emulatorId, 'shell', 'rm', devicePath]);
-
-  return name;
-};

package/src/platforms/android/index.ts

@@ -69,7 +69,7 @@ const androidPlatformAdapter: PlatformAdapter = {
 
     return {
       restart: async () => {
-        await runApp(runner.deviceId, runner.bundleId, runner.activityName);
+        await runApp(deviceId, runner.bundleId, runner.activityName);
       },
       dispose: async () => {
         await killApp(deviceId, runner.bundleId);

package/src/platforms/ios/build.ts

@@ -1,5 +1,6 @@
 import { spawn, spawnAndForget } from '@react-native-harness/tools';
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const listDevices = async (): Promise<any> => {
   const { stdout } = await spawn('xcrun', [
     'simctl',
@@ -13,6 +14,7 @@ export const listDevices = async (): Promise<any> => {
 export const getDeviceByName = async (
   simulatorName: string,
   systemVersion: string
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
 ): Promise<any | null> => {
   const devices = await listDevices();
   const expectedRuntimeId = `com.apple.CoreSimulator.SimRuntime.iOS-${systemVersion.replace(
@@ -27,6 +29,7 @@ export const getDeviceByName = async (
   }
 
   const runtimeDevices = devices.devices[runtime];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const device = runtimeDevices.find((d: any) => d.name === simulatorName);
 
   if (device) {

package/src/platforms/ios/device.ts

@@ -1,6 +1,9 @@
 import { spawn, spawnAndForget } from '@react-native-harness/tools';
 
-export const listDevices = async (): Promise<any> => {
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Device = any;
+
+export const listDevices = async (): Promise<{ devices: Device[] }> => {
   const { stdout } = await spawn('xcrun', [
     'simctl',
     'list',
@@ -12,7 +15,7 @@ export const listDevices = async (): Promise<any> => {
 
 export const getDeviceByName = async (
   simulatorName: string
-): Promise<any | null> => {
+): Promise<Device | null> => {
   const devices = await listDevices();
 
   for (const runtime in devices.devices) {

package/src/platforms/ios/simulator.ts

@@ -1,4 +1,4 @@
-import { spawn } from '@react-native-harness/tools';
+import { spawn, SubprocessError } from '@react-native-harness/tools';
 
 export type IOSSimulatorStatus = 'stopped' | 'loading' | 'running';
 
@@ -25,6 +25,7 @@ export const getSimulatorDeviceId = async (
       return null;
     }
 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const device = runtime.find((d: any) => d.name === simulatorName);
 
     if (device) {
@@ -57,6 +58,7 @@ export const getAvailableSimulators = async (): Promise<
     for (const runtime in devices.devices) {
       if (runtime.includes('iOS')) {
         const runtimeDevices = devices.devices[runtime];
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         runtimeDevices.forEach((device: any) => {
           if (device.isAvailable) {
             simulators.push({
@@ -90,6 +92,7 @@ export const getSimulatorStatus = async (
     for (const runtime in devices.devices) {
       if (runtime.includes('iOS')) {
         const runtimeDevices = devices.devices[runtime];
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const device = runtimeDevices.find((d: any) => d.udid === udid);
 
         if (device) {
@@ -114,9 +117,10 @@ export const getSimulatorStatus = async (
 export const runSimulator = async (udid: string): Promise<void> => {
   try {
     await spawn('xcrun', ['simctl', 'boot', udid]);
-  } catch (bootError: any) {
+  } catch (bootError) {
     // Ignore if simulator is already booted
     if (
+      bootError instanceof SubprocessError &&
       !bootError.stderr?.includes(
         'Unable to boot device in current state: Booted'
       )
@@ -153,9 +157,10 @@ export const stopSimulator = async (udid: string): Promise<void> => {
 const stopSimulatorById = async (udid: string): Promise<void> => {
   try {
     await spawn('xcrun', ['simctl', 'shutdown', udid]);
-  } catch (shutdownError: any) {
+  } catch (shutdownError) {
     // Ignore if simulator is already shut down
     if (
+      shutdownError instanceof SubprocessError &&
       !shutdownError.stderr?.includes(
         'Unable to shutdown device in current state: Shutdown'
       )

package/src/platforms/platform-registry.ts

@@ -2,11 +2,13 @@ import { PlatformAdapter } from './platform-adapter.js';
 import androidPlatformAdapter from './android/index.js';
 import iosPlatformAdapter from './ios/index.js';
 import webPlatformAdapter from './web/index.js';
+import vegaPlatformAdapter from './vega/index.js';
 
 const platformAdapters = {
   android: androidPlatformAdapter,
   ios: iosPlatformAdapter,
   web: webPlatformAdapter,
+  vega: vegaPlatformAdapter,
 };
 
 export const getPlatformAdapter = async (
@@ -18,7 +20,7 @@ export const getPlatformAdapter = async (
 
   try {
     return platformAdapters[platformName as keyof typeof platformAdapters];
-  } catch (error) {
+  } catch {
     throw new Error(`Platform adapter for ${platformName} not found`);
   }
 };

package/src/platforms/vega/build.ts

@@ -0,0 +1,85 @@
+import path from 'node:path';
+import { spawn } from '@react-native-harness/tools';
+
+export type VegaBuildTarget = 'sim_tv_x86_64' | 'sim_tv_aarch64';
+export type VegaBuildType = 'Debug' | 'Release';
+
+/**
+ * Build Vega app and produce .vpkg file
+ */
+export const buildVegaApp = async (
+  buildType: VegaBuildType = 'Release',
+  target?: VegaBuildTarget
+): Promise<void> => {
+  const args = ['run', 'build:app'];
+
+  if (buildType) {
+    args.push('-b', buildType);
+  }
+
+  if (target) {
+    args.push('-t', target);
+  }
+
+  await spawn('npm', args);
+};
+
+/**
+ * Clean build artifacts
+ */
+export const cleanBuild = async (): Promise<void> => {
+  await spawn('kepler', ['clean']);
+};
+
+/**
+ * Get the expected .vpkg file path based on build configuration
+ */
+export const getVpkgPath = (
+  appName: string,
+  buildType: VegaBuildType = 'Release',
+  target: VegaBuildTarget = 'sim_tv_x86_64'
+): string => {
+  const buildTypeStr = buildType.toLowerCase();
+  const vpkgFileName = `${appName}_${target}.vpkg`;
+
+  return path.join(
+    process.cwd(),
+    'build',
+    `${target}-${buildTypeStr}`,
+    vpkgFileName
+  );
+};
+
+/**
+ * Launch an already installed app on specified Vega virtual device
+ */
+export const runApp = async (
+  deviceId: string,
+  bundleId: string
+): Promise<void> => {
+  await spawn('kepler', [
+    'device',
+    'launch-app',
+    '--device',
+    deviceId,
+    '--appName',
+    bundleId,
+  ]);
+};
+
+/**
+ * Kill/terminate app on specified Vega virtual device
+ */
+export const killApp = async (
+  deviceId: string,
+  bundleId: string
+): Promise<void> => {
+  await spawn('kepler', [
+    'device',
+    'terminate-app',
+    '--device',
+    deviceId,
+    '--appName',
+    bundleId,
+  ]);
+};