@react-native-harness/jest 1.4.0-rc.1 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-native-harness/jest",
-  "version": "1.4.0-rc.1",
+  "version": "1.4.1",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -39,12 +39,13 @@
     "jest-util": "^30.2.0",
     "tslib": "^2.3.0",
     "yargs": "^17.7.2",
-    "@react-native-harness/plugins": "1.4.0-rc.1",
-    "@react-native-harness/platforms": "1.4.0-rc.1",
-    "@react-native-harness/bridge": "1.4.0-rc.1",
-    "@react-native-harness/config": "1.4.0-rc.1",
-    "@react-native-harness/tools": "1.4.0-rc.1",
-    "@react-native-harness/bundler-metro": "1.4.0-rc.1"
+    "@react-native-harness/bridge": "1.4.1",
+    "@react-native-harness/cache": "1.4.1",
+    "@react-native-harness/config": "1.4.1",
+    "@react-native-harness/bundler-metro": "1.4.1",
+    "@react-native-harness/plugins": "1.4.1",
+    "@react-native-harness/tools": "1.4.1",
+    "@react-native-harness/platforms": "1.4.1"
   },
   "devDependencies": {
     "@types/yargs": "^17.0.32",

package/src/crash-monitor.ts

@@ -40,6 +40,13 @@ export type CrashMonitor = {
   reset: () => void;
   setAppSession: (session: AppSession | null) => void;
   handleBridgeDisconnect: () => void;
+  /**
+   * Opens a window during which handleBridgeDisconnect() is suppressed,
+   * for use around operations (like a runtime reset) that intentionally
+   * disconnect the bridge without the app process dying. Returns a closer
+   * that ends the window; safe to call multiple times or nest.
+   */
+  expectDisconnect: () => () => void;
   dispose: () => Promise<void>;
 };
 
@@ -131,6 +138,7 @@ export const createCrashMonitor = ({
 
   let currentTestFilePath = '';
   let currentPhase: NativeCrashPhase = 'startup';
+  let expectedDisconnectDepth = 0;
   const watchers = new Set<(err: HarnessRuntimeFailure) => void>();
 
   const notifyFailure = (err: HarnessRuntimeFailure) => {
@@ -273,6 +281,19 @@ export const createCrashMonitor = ({
     return { promise, cancel };
   };
 
+  const expectDisconnect = (): (() => void) => {
+    expectedDisconnectDepth += 1;
+    let closed = false;
+
+    return () => {
+      if (closed) {
+        return;
+      }
+      closed = true;
+      expectedDisconnectDepth = Math.max(0, expectedDisconnectDepth - 1);
+    };
+  };
+
   return {
     watch,
     isAlive: () => alive,
@@ -289,15 +310,22 @@ export const createCrashMonitor = ({
       watchers.clear();
       isResolvingCrash = false;
       currentTestFilePath = '';
+      expectedDisconnectDepth = 0;
       clearPendingTimer();
     },
     setAppSession,
     handleBridgeDisconnect: () => {
+      if (expectedDisconnectDepth > 0) {
+        crashLogger.debug('ignoring expected bridge disconnect');
+        return;
+      }
       startCrashResolution('bridge-disconnect');
     },
+    expectDisconnect,
     dispose: async () => {
       disposed = true;
       monitoring = false;
+      expectedDisconnectDepth = 0;
       watchers.clear();
       isResolvingCrash = false;
       clearPendingTimer();

package/src/diagnostics/derivers.ts

@@ -0,0 +1,170 @@
+import type { Diagnostics, DiagnosticSpan } from '@react-native-harness/tools';
+import type { HarnessBridge } from '@react-native-harness/bridge/server';
+import type { BridgeEvents } from '@react-native-harness/bridge';
+import type { MetroInstance, ReportableEvent } from '@react-native-harness/bundler-metro';
+
+/**
+ * Span/mark derivers translate existing domain event streams (Metro build
+ * events, bridge/device events) into diagnostics entries. This is the only
+ * place in the jest package that maps event shapes to diagnostic labels -
+ * business logic elsewhere stays free of diagnostics calls.
+ */
+
+const noopDispose = (): void => undefined;
+
+/**
+ * Observes Metro's reporter event stream and derives:
+ * - `metro.bundle.build` spans, correlated by `buildID` across
+ *   bundle_build_started -> bundle_build_done|bundle_build_failed.
+ * - `metro.bundle.request` marks from bundle_request_observed events.
+ */
+export const observeMetroEvents = (
+  events: MetroInstance['events'],
+  diagnostics: Diagnostics
+): (() => void) => {
+  if (!diagnostics.enabled) {
+    return noopDispose;
+  }
+
+  const inflightBuilds = new Map<string, DiagnosticSpan>();
+
+  const listener = (event: ReportableEvent): void => {
+    switch (event.type) {
+      case 'bundle_build_started': {
+        const span = diagnostics.start('metro.bundle.build', {
+          buildID: event.buildID,
+          platform: event.bundleDetails.platform,
+          entryFile: event.bundleDetails.entryFile,
+          dev: event.bundleDetails.dev,
+        });
+        inflightBuilds.set(event.buildID, span);
+        return;
+      }
+      case 'bundle_build_done': {
+        const span = inflightBuilds.get(event.buildID);
+        inflightBuilds.delete(event.buildID);
+        span?.end();
+        return;
+      }
+      case 'bundle_build_failed': {
+        const span = inflightBuilds.get(event.buildID);
+        inflightBuilds.delete(event.buildID);
+        span?.fail(new Error(`Metro bundle build ${event.buildID} failed`));
+        return;
+      }
+      case 'bundle_request_observed': {
+        diagnostics.mark('metro.bundle.request', {
+          requestKind: event.requestKind,
+          platform: event.platform,
+        });
+        return;
+      }
+      default:
+        return;
+    }
+  };
+
+  events.addListener(listener);
+  return () => {
+    events.removeListener(listener);
+  };
+};
+
+type MinimalBridge = Pick<HarnessBridge, 'on' | 'off'>;
+
+/**
+ * Observes bridge connection lifecycle and device-reported bridge events and
+ * derives:
+ * - `bridge.connected` / `bridge.disconnected` marks.
+ * - `client.bundle.module`, `client.setup-file`, `client.collect`,
+ *   `client.suite`, `client.test` completed spans, recorded via
+ *   diagnostics.record() since these events arrive with a `duration` already
+ *   measured on the (unsynced) device clock; we anchor them at host receipt
+ *   time instead of trusting the device's absolute clock.
+ */
+export const observeBridgeEvents = (
+  bridge: MinimalBridge,
+  diagnostics: Diagnostics
+): (() => void) => {
+  if (!diagnostics.enabled) {
+    return noopDispose;
+  }
+
+  const onConnected = (): void => {
+    diagnostics.mark('bridge.connected');
+  };
+
+  const onDisconnected = (): void => {
+    diagnostics.mark('bridge.disconnected');
+  };
+
+  const onEvent = (event: BridgeEvents): void => {
+    switch (event.type) {
+      case 'module-bundling-finished':
+        diagnostics.record({
+          label: 'client.bundle.module',
+          duration: event.duration,
+          attrs: { file: event.file },
+        });
+        return;
+      case 'module-bundling-failed':
+        diagnostics.record({
+          label: 'client.bundle.module',
+          duration: event.duration,
+          attrs: { file: event.file },
+          status: 'error',
+        });
+        return;
+      case 'setup-file-bundling-finished':
+        diagnostics.record({
+          label: 'client.setup-file',
+          duration: event.duration,
+          attrs: { file: event.file, setupType: event.setupType },
+        });
+        return;
+      case 'setup-file-bundling-failed':
+        diagnostics.record({
+          label: 'client.setup-file',
+          duration: event.duration,
+          attrs: { file: event.file, setupType: event.setupType },
+          status: 'error',
+        });
+        return;
+      case 'collection-finished':
+        diagnostics.record({
+          label: 'client.collect',
+          duration: event.duration,
+          attrs: { file: event.file, totalTests: event.totalTests },
+        });
+        return;
+      case 'suite-finished':
+        diagnostics.record({
+          label: 'client.suite',
+          duration: event.duration,
+          attrs: { file: event.file, name: event.name, status: event.status },
+          status: event.status === 'failed' ? 'error' : 'ok',
+        });
+        return;
+      case 'test-finished':
+        diagnostics.record({
+          label: 'client.test',
+          duration: event.duration,
+          attrs: { file: event.file, name: event.name, status: event.status },
+          status: event.status === 'failed' ? 'error' : 'ok',
+        });
+        return;
+      default:
+        return;
+    }
+  };
+
+  bridge.on('connected', onConnected);
+  bridge.on('disconnected', onDisconnected);
+  bridge.on('event', onEvent);
+
+  return () => {
+    bridge.off('connected', onConnected);
+    bridge.off('disconnected', onDisconnected);
+    bridge.off('event', onEvent);
+  };
+};

package/src/diagnostics/index.ts

@@ -0,0 +1,2 @@
+export { observeMetroEvents, observeBridgeEvents } from './derivers.js';
+export { writeTraceFile, printSummary } from './report.js';

package/src/diagnostics/report.ts

@@ -0,0 +1,124 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { DiagnosticEntry } from '@react-native-harness/tools';
+import { getHarnessRootPath } from '@react-native-harness/tools';
+
+type TraceEvent = {
+  name: string;
+  ph: 'X' | 'i';
+  ts: number;
+  dur?: number;
+  s?: 'g';
+  pid: number;
+  tid: number;
+  args?: Record<string, unknown>;
+};
+
+const TRACE_PID = 1;
+const TRACE_TID = 1;
+
+const toTraceEvent = (entry: DiagnosticEntry): TraceEvent => {
+  if (entry.kind === 'mark') {
+    return {
+      name: entry.label,
+      ph: 'i',
+      s: 'g',
+      ts: entry.startTime * 1000,
+      pid: TRACE_PID,
+      tid: TRACE_TID,
+      args: entry.attrs,
+    };
+  }
+
+  return {
+    name: entry.label,
+    ph: 'X',
+    ts: entry.startTime * 1000,
+    dur: entry.duration * 1000,
+    pid: TRACE_PID,
+    tid: TRACE_TID,
+    args: entry.attrs,
+  };
+};
+
+export const writeTraceFile = async (
+  entries: DiagnosticEntry[],
+  options: { projectRoot: string; runId: string }
+): Promise<string> => {
+  const dir = path.join(getHarnessRootPath(options.projectRoot), 'diagnostics');
+  await fs.mkdir(dir, { recursive: true });
+
+  const filePath = path.join(dir, `${options.runId}.json`);
+  const trace = { traceEvents: entries.map(toTraceEvent) };
+
+  await fs.writeFile(filePath, JSON.stringify(trace), 'utf-8');
+
+  return filePath;
+};
+
+const formatDuration = (ms: number): string => {
+  if (ms >= 1000) {
+    return `${(ms / 1000).toFixed(1)}s`;
+  }
+  return `${Math.round(ms)}ms`;
+};
+
+const getNamespace = (label: string): string => label.split('.')[0] ?? label;
+
+type LabelStats = {
+  label: string;
+  count: number;
+  totalMs: number;
+  maxMs: number;
+};
+
+export const printSummary = (
+  entries: DiagnosticEntry[],
+  log: (line: string) => void
+): void => {
+  if (entries.length === 0) {
+    return;
+  }
+
+  const statsByLabel = new Map<string, LabelStats>();
+  for (const entry of entries) {
+    const existing = statsByLabel.get(entry.label);
+    if (existing) {
+      existing.count += 1;
+      existing.totalMs += entry.duration;
+      existing.maxMs = Math.max(existing.maxMs, entry.duration);
+    } else {
+      statsByLabel.set(entry.label, {
+        label: entry.label,
+        count: 1,
+        totalMs: entry.duration,
+        maxMs: entry.duration,
+      });
+    }
+  }
+
+  const byNamespace = new Map<string, LabelStats[]>();
+  for (const stats of statsByLabel.values()) {
+    const namespace = getNamespace(stats.label);
+    const group = byNamespace.get(namespace);
+    if (group) {
+      group.push(stats);
+    } else {
+      byNamespace.set(namespace, [stats]);
+    }
+  }
+
+  log('Diagnostics summary:');
+  const sortedNamespaces = [...byNamespace.entries()].sort(([a], [b]) =>
+    a.localeCompare(b)
+  );
+  for (const [namespace, group] of sortedNamespaces) {
+    log(`  ${namespace}`);
+    group.sort((a, b) => b.totalMs - a.totalMs);
+    for (const stats of group) {
+      log(
+        `    ${stats.label}: count=${stats.count} total=${formatDuration(stats.totalMs)} max=${formatDuration(stats.maxMs)}`
+      );
+    }
+  }
+};

package/src/environment-reset.ts

@@ -0,0 +1,138 @@
+import { getTimeoutSignal } from '@react-native-harness/tools';
+import type { Config as HarnessConfig } from '@react-native-harness/config';
+
+const ignorePromiseRejection = () => undefined;
+
+export type ResetStrategyKind = 'process' | 'runtime';
+
+export type EnvironmentResetStrategy = {
+  readonly kind: ResetStrategyKind;
+  // Post-condition: bridge connected, runtime ready, crash-monitor state consistent.
+  reset(ctx: { testFilePath: string }): Promise<void>;
+};
+
+/**
+ * Normalizes the `resetEnvironmentBetweenTestFiles` config value into a
+ * strategy kind, or `null` when no reset should happen between test files
+ * (i.e. the value is `false`).
+ */
+export const resolveResetStrategyKind = (
+  value: HarnessConfig['resetEnvironmentBetweenTestFiles']
+): ResetStrategyKind | null => {
+  if (value === false) {
+    return null;
+  }
+  if (value === true) {
+    return 'process';
+  }
+  return value;
+};
+
+export type ProcessResetStrategyDeps = {
+  // Shared with restartApp; killing and relaunching the app process.
+  restart: (testFilePath: string) => Promise<void>;
+};
+
+/**
+ * The 'process' strategy: kill and cold-restart the app process. This is
+ * the same implementation `restartApp` uses for crash/timeout recovery.
+ */
+export const createProcessResetStrategy = (
+  deps: ProcessResetStrategyDeps
+): EnvironmentResetStrategy => ({
+  kind: 'process',
+  reset: ({ testFilePath }) => deps.restart(testFilePath),
+});
+
+export type RuntimeResetConnection = {
+  resetEnvironment: () => Promise<void>;
+};
+
+export type RuntimeResetStrategyDeps = {
+  // Returns the active app connection, or null if there isn't one.
+  getConnection: () => RuntimeResetConnection | null;
+  // Opens a window that suppresses crash-monitor disconnect handling;
+  // returns a closer to end the window.
+  expectDisconnect: () => () => void;
+  // Resolves the next time the bridge reports a 'connected' event, or
+  // rejects when `signal` aborts.
+  waitForReconnect: (signal: AbortSignal) => Promise<void>;
+  // Identifies RPC rejections caused by the bridge disconnecting. Inside the
+  // expected-disconnect window these mean the reload tore the runtime down
+  // before the RPC ack flushed — the reload is in flight, not failed.
+  isDisconnectError: (error: unknown) => boolean;
+  // Reconnect timeout in ms (the configured bundleStartTimeout).
+  timeoutMs: number;
+};
+
+/**
+ * The 'runtime' strategy: reload the JS runtime in place (DevSettings.reload()
+ * on native, window.location.reload() on web) via the resetEnvironment RPC,
+ * and wait for the bridge to reconnect. The app process stays alive
+ * throughout, so the crash monitor's expected-disconnect window is used to
+ * avoid misclassifying the intentional disconnect as a runtime failure.
+ */
+export const createRuntimeResetStrategy = (
+  deps: RuntimeResetStrategyDeps
+): EnvironmentResetStrategy => ({
+  kind: 'runtime',
+  reset: async () => {
+    const connection = deps.getConnection();
+    if (!connection) {
+      throw new Error('No active app connection to reset the runtime on');
+    }
+
+    const closeWindow = deps.expectDisconnect();
+    try {
+      // Start listening for the reconnect before firing the RPC, so a fast
+      // reload can't reconnect before we're watching for it.
+      const reconnected = deps.waitForReconnect(getTimeoutSignal(deps.timeoutMs));
+      // Observe the rejection even when the RPC throws first, so the timeout
+      // abort firing later can't become an unhandled rejection. (.catch()
+      // returns a new promise; the original is what gets awaited below.)
+      reconnected.catch(ignorePromiseRejection);
+
+      try {
+        await connection.resetEnvironment();
+      } catch (error) {
+        // The reload can tear the runtime down before the RPC ack flushes.
+        // A disconnect-flavored rejection means the reload is in flight, so
+        // keep waiting for the reconnect; anything else is a real failure.
+        if (!deps.isDisconnectError(error)) {
+          throw error;
+        }
+      }
+
+      await reconnected;
+    } finally {
+      closeWindow();
+    }
+  },
+});
+
+export type EscalationOptions = {
+  // Invoked when the primary strategy fails and the fallback is about to run.
+  onEscalate?: (error: unknown) => void;
+};
+
+/**
+ * Wraps a primary strategy so that any failure (no active connection, RPC
+ * error, reconnect timeout, ...) falls back to running `fallback` instead of
+ * propagating the error. The composite reports the primary's `kind`, since
+ * that's the strategy that was requested.
+ */
+export const withEscalation = (
+  primary: EnvironmentResetStrategy,
+  fallback: EnvironmentResetStrategy,
+  options: EscalationOptions = {}
+): EnvironmentResetStrategy => ({
+  kind: primary.kind,
+  reset: async (ctx) => {
+    try {
+      await primary.reset(ctx);
+    } catch (error) {
+      options.onEscalate?.(error);
+      await fallback.reset(ctx);
+    }
+  },
+});