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

package/src/crash-supervisor.ts

@@ -0,0 +1,321 @@
+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';
+
+const crashLogger = logger.child('crash');
+
+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) {
+      crashLogger.debug('ignoring crash signal without active test: %s', reason);
+      return;
+    }
+
+    isResolvingCrash = true;
+    crashLogger.debug(
+      'native crash detected during %s (state=%s reason=%s)',
+      activeTestFilePath,
+      state,
+      reason || '(none)'
+    );
+
+    for (const line of details?.rawLines ?? []) {
+      crashLogger.debug('%s', 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);
+      crashLogger.debug('crash details: %o', {
+        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) {
+        void handleCrash(reason, details);
+      }
+    } catch (error) {
+      crashLogger.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/env.d.ts

@@ -1,4 +1,4 @@
-import type { Harness } from '@react-native-harness/cli/external';
+import type { Harness } from './harness.js';
 import type { Config as HarnessConfig } from '@react-native-harness/config';
 
 declare global {

package/src/errors.ts

@@ -1,4 +1,10 @@
 import { HarnessError } from '@react-native-harness/tools';
+import type { AppCrashDetails } from '@react-native-harness/platforms';
+export {
+  StartupStallError,
+  type StartupStallCode,
+  type StartupStallDetails,
+} from '@react-native-harness/bundler-metro';
 
 export class NoRunnerSpecifiedError extends HarnessError {
   constructor() {
@@ -21,22 +27,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;
   }
 }