@react-native-harness/jest 1.0.0 → 1.1.0-rc.1

package/src/crash-supervisor.ts

@@ -0,0 +1,314 @@
+import {
+  type AppMonitor,
+  type AppCrashDetails,
+  type AppMonitorEvent,
+  type AppMonitorListener,
+  type HarnessPlatformRunner,
+} from '@react-native-harness/platforms';
+import {
+  NativeCrashError,
+  type NativeCrashDetails,
+  type NativeCrashPhase,
+} from './errors.js';
+import { logger } from '@react-native-harness/tools';
+
+export type CrashSupervisorState =
+  | 'idle'
+  | 'launching'
+  | 'ready'
+  | 'running'
+  | 'disposing';
+
+export type CrashSupervisor = {
+  setActiveTestFile: (testFilePath: string | null) => void;
+  beginLaunch: (testFilePath: string) => void;
+  markReady: () => void;
+  beginTestRun: (testFilePath: string) => void;
+  stop: () => Promise<void>;
+  start: () => Promise<void>;
+  waitForCrash: (testFilePath: string) => Promise<never>;
+  isReady: () => boolean;
+  cancelCrashWaiters: () => void;
+  reset: () => void;
+  dispose: () => Promise<void>;
+};
+
+export type CrashSupervisorOptions = {
+  appMonitor: AppMonitor;
+  platformRunner: HarnessPlatformRunner;
+};
+
+type CrashDetailsProvider = {
+  getCrashDetails?: (
+    options: {
+      processName?: string;
+      pid?: number;
+      occurredAt: number;
+    }
+  ) => Promise<AppCrashDetails | null>;
+};
+
+const getCrashPhase = (state: CrashSupervisorState): NativeCrashPhase =>
+  state === 'running' ? 'execution' : 'startup';
+
+const mergeCrashDetails = (
+  phase: NativeCrashPhase,
+  initialDetails?: AppCrashDetails,
+  enrichedDetails?: AppCrashDetails | null,
+  fallbackSummary?: string
+): NativeCrashDetails => ({
+  phase,
+  source: enrichedDetails?.source ?? initialDetails?.source,
+  summary:
+    enrichedDetails?.summary ?? initialDetails?.summary ?? fallbackSummary,
+  signal: enrichedDetails?.signal ?? initialDetails?.signal,
+  exceptionType: enrichedDetails?.exceptionType ?? initialDetails?.exceptionType,
+  processName: enrichedDetails?.processName ?? initialDetails?.processName,
+  pid: enrichedDetails?.pid ?? initialDetails?.pid,
+  stackTrace: enrichedDetails?.stackTrace ?? initialDetails?.stackTrace,
+  rawLines: enrichedDetails?.rawLines ?? initialDetails?.rawLines,
+  artifactType: enrichedDetails?.artifactType ?? initialDetails?.artifactType,
+  artifactPath: enrichedDetails?.artifactPath ?? initialDetails?.artifactPath,
+});
+
+export const createCrashSupervisor = ({
+  appMonitor,
+  platformRunner,
+}: CrashSupervisorOptions): CrashSupervisor => {
+  let state: CrashSupervisorState = 'idle';
+  let activeTestFilePath: string | null = null;
+  let crashRejectors = new Set<(error: NativeCrashError) => void>();
+  let disposed = false;
+  let monitoring = true;
+  let isResolvingCrash = false;
+
+  const getCrashDetailsProvider = (): CrashDetailsProvider | null => {
+    if ('getCrashDetails' in appMonitor) {
+      return appMonitor as AppMonitor & CrashDetailsProvider;
+    }
+
+    if (platformRunner.getCrashDetails) {
+      return platformRunner;
+    }
+
+    return null;
+  };
+
+  const rejectCrashWaiters = (testFilePath: string, details: NativeCrashDetails) => {
+    const error = new NativeCrashError(testFilePath, details);
+
+    for (const reject of crashRejectors) {
+      reject(error);
+    }
+
+    crashRejectors = new Set();
+  };
+
+  const handleCrash = async (reason: string, details?: AppCrashDetails) => {
+    if (
+      isResolvingCrash ||
+      (state !== 'launching' && state !== 'running' && state !== 'ready')
+    ) {
+      return;
+    }
+
+    if (!activeTestFilePath) {
+      logger.debug(`Ignoring crash signal without active test: ${reason}`);
+      return;
+    }
+
+    isResolvingCrash = true;
+    logger.debug(`Native crash detected during ${activeTestFilePath} (state: ${state}, reason: ${reason || '(none)'})`);
+
+    for (const line of details?.rawLines ?? []) {
+      logger.debug(line);
+    }
+
+    const phase = getCrashPhase(state);
+    const testFilePath = activeTestFilePath;
+    state = 'idle';
+
+    try {
+      const enrichedDetails = await getCrashDetailsProvider()?.getCrashDetails?.({
+        processName: details?.processName,
+        pid: details?.pid,
+        occurredAt: Date.now(),
+      });
+
+      const mergedDetails = mergeCrashDetails(phase, details, enrichedDetails, reason);
+      logger.debug('Crash details:', {
+        phase: mergedDetails.phase,
+        source: mergedDetails.source,
+        summary: mergedDetails.summary,
+        signal: mergedDetails.signal,
+        exceptionType: mergedDetails.exceptionType,
+        processName: mergedDetails.processName,
+        pid: mergedDetails.pid,
+      });
+      rejectCrashWaiters(testFilePath, mergedDetails);
+    } finally {
+      isResolvingCrash = false;
+    }
+  };
+
+  const confirmCrash = async (reason: string, details?: AppCrashDetails) => {
+    if (disposed || !monitoring || state === 'disposing') {
+      return;
+    }
+
+    try {
+      const isRunning = await platformRunner.isAppRunning();
+
+      if (!isRunning) {
+        handleCrash(reason, details);
+      }
+    } catch (error) {
+      logger.debug('Crash confirmation failed', error);
+    }
+  };
+
+  const appMonitorListener: AppMonitorListener = (event: AppMonitorEvent) => {
+    if (disposed || !monitoring) {
+      return;
+    }
+
+    if (event.type === 'app_started') {
+      return;
+    }
+
+    if (event.type === 'app_exited') {
+      const details = {
+        source: event.crashDetails?.source ?? event.source,
+        summary: event.crashDetails?.summary,
+        signal: event.crashDetails?.signal,
+        exceptionType: event.crashDetails?.exceptionType,
+        processName: event.crashDetails?.processName,
+        pid: event.crashDetails?.pid ?? event.pid,
+        stackTrace: event.crashDetails?.stackTrace,
+        rawLines:
+          event.crashDetails?.rawLines ??
+          (event.line ? [event.line] : undefined),
+      };
+
+      if (event.isConfirmed ?? event.source === 'polling') {
+        void handleCrash('', details);
+      } else {
+        void confirmCrash('', details);
+      }
+      return;
+    }
+
+    if (event.type === 'possible_crash') {
+      const details = {
+        source: event.crashDetails?.source ?? event.source,
+        summary: event.crashDetails?.summary,
+        signal: event.crashDetails?.signal,
+        exceptionType: event.crashDetails?.exceptionType,
+        processName: event.crashDetails?.processName,
+        pid: event.crashDetails?.pid ?? event.pid,
+        stackTrace: event.crashDetails?.stackTrace,
+        rawLines:
+          event.crashDetails?.rawLines ??
+          (event.line ? [event.line] : undefined),
+      };
+
+      if (event.isConfirmed) {
+        void handleCrash(
+          `possible crash signal (${event.source ?? 'unknown'})`,
+          details
+        );
+      } else {
+        void confirmCrash(
+          `possible crash signal (${event.source ?? 'unknown'})`,
+          details
+        );
+      }
+    }
+  };
+
+  appMonitor.addListener(appMonitorListener);
+
+  const setActiveTestFile = (testFilePath: string | null) => {
+    activeTestFilePath = testFilePath;
+  };
+
+  const beginLaunch = (testFilePath: string) => {
+    activeTestFilePath = testFilePath;
+    state = 'launching';
+  };
+
+  const markReady = () => {
+    if (state !== 'disposing') {
+      state = 'ready';
+    }
+  };
+
+  const beginTestRun = (testFilePath: string) => {
+    activeTestFilePath = testFilePath;
+    state = 'running';
+  };
+
+  const stop = async () => {
+    monitoring = false;
+    await appMonitor.stop();
+  };
+
+  const start = async () => {
+    monitoring = true;
+    await appMonitor.start();
+  };
+
+  const waitForCrash = (testFilePath: string): Promise<never> =>
+    new Promise<never>((_, reject) => {
+      if (disposed) {
+        reject(
+          new NativeCrashError(testFilePath, {
+            phase: 'startup',
+            source: 'polling',
+            summary: 'Crash supervisor disposed while waiting for app startup.',
+          })
+        );
+        return;
+      }
+
+      crashRejectors.add(reject);
+    });
+
+  const isReady = () => state === 'ready' || state === 'running';
+
+  const cancelCrashWaiters = () => {
+    crashRejectors = new Set();
+  };
+
+  const reset = () => {
+    cancelCrashWaiters();
+    isResolvingCrash = false;
+    if (state !== 'disposing') {
+      state = 'idle';
+    }
+  };
+
+  const dispose = async () => {
+    disposed = true;
+    monitoring = false;
+    state = 'disposing';
+    crashRejectors = new Set();
+    isResolvingCrash = false;
+    appMonitor.removeListener(appMonitorListener);
+    await appMonitor.dispose();
+  };
+
+  return {
+    setActiveTestFile,
+    beginLaunch,
+    markReady,
+    beginTestRun,
+    stop,
+    start,
+    waitForCrash,
+    isReady,
+    cancelCrashWaiters,
+    reset,
+    dispose,
+  };
+};

package/src/errors.ts

@@ -1,4 +1,5 @@
 import { HarnessError } from '@react-native-harness/tools';
+import type { AppCrashDetails } from '@react-native-harness/platforms';
 
 export class NoRunnerSpecifiedError extends HarnessError {
   constructor() {
@@ -21,22 +22,76 @@ export class InitializationTimeoutError extends HarnessError {
   }
 }
 
-export class MaxAppRestartsError extends HarnessError {
-  constructor(attempts: number) {
-    super(
-      `App failed to start after ${attempts} attempts. ` +
-        `No bundling activity detected within timeout period.`
+export type NativeCrashPhase = 'startup' | 'execution';
+
+export type NativeCrashDetails = AppCrashDetails & {
+  phase: NativeCrashPhase;
+};
+
+const buildNativeCrashMessage = ({
+  phase,
+  summary,
+  signal,
+  exceptionType,
+  processName,
+  pid,
+  stackTrace,
+  artifactType,
+}: NativeCrashDetails) => {
+  const lines = [
+    phase === 'startup'
+      ? 'The native app crashed while preparing to run this test file.'
+      : 'The native app crashed during test execution.',
+  ];
+  const hasCrashBlock = summary?.includes('\n') ?? false;
+  const shouldRenderSummary =
+    Boolean(summary) &&
+    !(
+      !hasCrashBlock &&
+      artifactType === 'ios-crash-report'
     );
-    this.name = 'MaxAppRestartsError';
+
+  if (shouldRenderSummary && summary) {
+    lines.push('');
+    lines.push(summary);
+  }
+
+  if (!hasCrashBlock && signal) {
+    lines.push(`Signal: ${signal}`);
+  }
+
+  if (!hasCrashBlock && exceptionType) {
+    lines.push(`Exception: ${exceptionType}`);
   }
-}
+
+  if (!hasCrashBlock && processName && pid !== undefined) {
+    lines.push(`Process: ${processName} (pid ${pid})`);
+  } else if (!hasCrashBlock && processName) {
+    lines.push(`Process: ${processName}`);
+  } else if (!hasCrashBlock && pid !== undefined) {
+    lines.push(`PID: ${pid}`);
+  }
+
+  if (!hasCrashBlock && stackTrace && stackTrace.length > 0) {
+    lines.push('');
+    lines.push(...stackTrace.map((line) => `  ${line}`));
+  }
+
+  return lines.join('\n');
+};
 
 export class NativeCrashError extends HarnessError {
   constructor(
     public readonly testFilePath: string,
+    public readonly details: NativeCrashDetails,
     public readonly lastKnownTest?: string
   ) {
-    super('The native app crashed during test execution.');
+    super(buildNativeCrashMessage(details));
     this.name = 'NativeCrashError';
+    this.stack = `${this.name}: ${this.message.split('\n')[0]}`;
+  }
+
+  get phase() {
+    return this.details.phase;
   }
 }

package/src/harness.ts

@@ -8,18 +8,21 @@ import {
   TestSuiteResult,
 } from '@react-native-harness/bridge';
 import {
+  type AppLaunchOptions,
   HarnessPlatform,
   HarnessPlatformRunner,
 } from '@react-native-harness/platforms';
 import {
   getMetroInstance,
   prewarmMetroBundle,
-  Reporter,
-  ReportableEvent,
 } from '@react-native-harness/bundler-metro';
-import { InitializationTimeoutError, MaxAppRestartsError } from './errors.js';
+import { createCrashArtifactWriter } from '@react-native-harness/tools';
+import { InitializationTimeoutError } from './errors.js';
 import { Config as HarnessConfig } from '@react-native-harness/config';
-import { createCrashMonitor, CrashMonitor } from './crash-monitor.js';
+import {
+  createCrashSupervisor,
+  type CrashSupervisor,
+} from './crash-supervisor.js';
 import { createClientLogListener } from './client-log-handler.js';
 import { logMetroPrewarmCompleted } from './logs.js';
 
@@ -31,97 +34,65 @@ export type Harness = {
     path: string,
     options: HarnessRunTestsOptions
   ) => Promise<TestSuiteResult>;
-  restart: () => Promise<void>;
+  ensureAppReady: (testFilePath: string) => Promise<void>;
+  restart: (testFilePath?: string) => Promise<void>;
   dispose: () => Promise<void>;
-  crashMonitor: CrashMonitor;
+  crashSupervisor: CrashSupervisor;
 };
 
 export const waitForAppReady = async (options: {
-  metroEvents: Reporter;
   serverBridge: BridgeServer;
   platformInstance: HarnessPlatformRunner;
-  bundleStartTimeout: number;
-  maxRestarts: number;
-  signal: AbortSignal;
+  bridgeTimeout: number;
+  testFilePath: string;
+  crashSupervisor: CrashSupervisor;
+  appLaunchOptions?: AppLaunchOptions;
 }): Promise<void> => {
   const {
-    metroEvents,
     serverBridge,
     platformInstance,
-    bundleStartTimeout,
-    maxRestarts,
-    signal,
+    bridgeTimeout,
+    testFilePath,
+    crashSupervisor,
+    appLaunchOptions,
   } = options;
 
-  let restartCount = 0;
-  let isBundling = false;
-  let bundleTimeoutId: NodeJS.Timeout | null = null;
-
-  const clearBundleTimeout = () => {
-    if (bundleTimeoutId) {
-      clearTimeout(bundleTimeoutId);
-      bundleTimeoutId = null;
-    }
-  };
+  const signal = AbortSignal.timeout(bridgeTimeout);
 
   return new Promise<void>((resolve, reject) => {
-    // Handle abort signal
-    signal.addEventListener('abort', () => {
-      clearBundleTimeout();
-      reject(new DOMException('The operation was aborted', 'AbortError'));
-    });
-
-    // Start/restart the bundle timeout
-    const startBundleTimeout = () => {
-      clearBundleTimeout();
-      bundleTimeoutId = setTimeout(() => {
-        if (isBundling) return; // Don't restart while bundling
-
-        if (restartCount >= maxRestarts) {
-          cleanup();
-          reject(new MaxAppRestartsError(restartCount + 1));
-          return;
-        }
-
-        restartCount++;
-        platformInstance.restartApp().catch(reject);
-        startBundleTimeout(); // Reset timer for next attempt
-      }, bundleStartTimeout);
-    };
-
-    // Metro event listener
-    const onMetroEvent = (event: ReportableEvent) => {
-      if (event.type === 'bundle_build_started') {
-        isBundling = true;
-        clearBundleTimeout(); // Cancel restart timer while bundling
-      } else if (
-        event.type === 'bundle_build_done' ||
-        event.type === 'bundle_build_failed'
-      ) {
-        isBundling = false;
-        startBundleTimeout(); // Reset timer after bundle completes
-      }
+    const launchApp = async () => {
+      crashSupervisor.beginLaunch(testFilePath);
+      await platformInstance.restartApp(appLaunchOptions);
     };
 
-    // Bridge ready listener
     const onReady = () => {
+      crashSupervisor.markReady();
       cleanup();
       resolve();
     };
 
+    const onAbort = () => {
+      cleanup();
+      reject(new DOMException('The operation was aborted', 'AbortError'));
+    };
+
     const cleanup = () => {
-      clearBundleTimeout();
-      metroEvents.removeListener(onMetroEvent);
       serverBridge.off('ready', onReady);
+      signal.removeEventListener('abort', onAbort);
+      crashSupervisor.cancelCrashWaiters();
     };
 
-    // Setup listeners
-    metroEvents.addListener(onMetroEvent);
+    signal.addEventListener('abort', onAbort);
     serverBridge.once('ready', onReady);
+    void crashSupervisor.waitForCrash(testFilePath).catch((error) => {
+      cleanup();
+      reject(error);
+    });
 
-    // Start the app and timeout
-    platformInstance.restartApp().catch(reject);
-    startBundleTimeout();
+    void launchApp().catch((error) => {
+      cleanup();
+      reject(error);
+    });
   });
 };
 
@@ -146,9 +117,24 @@ const getHarnessInternal = async (
       context,
     }),
   ]);
+  const crashArtifactWriter = createCrashArtifactWriter({
+    runnerName: platform.name,
+    platformId: platform.platformId,
+  });
+  const appMonitor = platformInstance.createAppMonitor({
+    crashArtifactWriter,
+  });
+  const appLaunchOptions = (
+    platform.config as { appLaunchOptions?: AppLaunchOptions }
+  ).appLaunchOptions;
 
-  // Forward client logs to console if enabled
   const clientLogListener = createClientLogListener();
+  const crashSupervisor = createCrashSupervisor({
+    appMonitor,
+    platformRunner: platformInstance,
+  });
+
+  serverBridge.on('ready', crashSupervisor.markReady);
 
   if (config.forwardClientLogs) {
     metroInstance.events.addListener(clientLogListener);
@@ -158,19 +144,15 @@ const getHarnessInternal = async (
     if (config.forwardClientLogs) {
       metroInstance.events.removeListener(clientLogListener);
     }
+    serverBridge.off('ready', crashSupervisor.markReady);
     await Promise.all([
+      crashSupervisor.dispose(),
       serverBridge.dispose(),
       platformInstance.dispose(),
       metroInstance.dispose(),
     ]);
   };
 
-  const crashMonitor = createCrashMonitor({
-    interval: config.crashDetectionInterval,
-    platformRunner: platformInstance,
-    bridgeServer: serverBridge,
-  });
-
   if (signal.aborted) {
     await dispose();
 
@@ -187,29 +169,46 @@ const getHarnessInternal = async (
       signal,
     });
     logMetroPrewarmCompleted(platform);
-
-    await waitForAppReady({
-      metroEvents: metroInstance.events,
-      serverBridge,
-      platformInstance: platformInstance as HarnessPlatformRunner,
-      bundleStartTimeout: config.bundleStartTimeout,
-      maxRestarts: config.maxAppRestarts,
-      signal,
-    });
+    await appMonitor.start();
   } catch (error) {
     await dispose();
     throw error;
   }
 
-  const restart = () =>
-    new Promise<void>((resolve, reject) => {
-      crashMonitor.markIntentionalRestart();
-      serverBridge.once('ready', () => {
-        crashMonitor.clearIntentionalRestart();
-        resolve();
-      });
-      platformInstance.restartApp().catch(reject);
+  const ensureAppReady = async (testFilePath: string) => {
+    crashSupervisor.setActiveTestFile(testFilePath);
+
+    if (crashSupervisor.isReady() && (await platformInstance.isAppRunning())) {
+      return;
+    }
+
+    crashSupervisor.reset();
+    await waitForAppReady({
+      serverBridge,
+      platformInstance: platformInstance as HarnessPlatformRunner,
+      bridgeTimeout: config.bridgeTimeout,
+      testFilePath,
+      crashSupervisor,
+      appLaunchOptions,
     });
+  };
+
+  const restart = async (testFilePath?: string) => {
+    await crashSupervisor.stop();
+
+    if (testFilePath) {
+      await platformInstance.stopApp();
+    } else {
+      await platformInstance.restartApp(appLaunchOptions);
+    }
+
+    crashSupervisor.reset();
+    await crashSupervisor.start();
+
+    if (testFilePath) {
+      await ensureAppReady(testFilePath);
+    }
+  };
 
   return {
     context,
@@ -225,9 +224,10 @@ const getHarnessInternal = async (
         runner: platform.runner,
       });
     },
+    ensureAppReady,
     restart,
     dispose,
-    crashMonitor,
+    crashSupervisor,
   };
 };