@react-native-harness/jest 1.5.0 → 1.7.0

package/src/execute-run.ts

@@ -5,11 +5,12 @@ import type {
   TestEvents,
 } from 'jest-runner';
 import { randomUUID } from 'node:crypto';
-import path from 'node:path';
 import { type HarnessSession, type HarnessRunState } from './harness-session.js';
 import { runHarnessTestFile } from './run.js';
+import { toRelativePosixPath } from './relative-path.js';
 import { resolveResetStrategyKind } from './environment-reset.js';
 import {
+  HostSurfaceReplacedError,
   NativeCrashError,
   RuntimeDisconnectError,
   StartupStallError,
@@ -31,7 +32,13 @@ import {
 } from './test-file-platform-filter.js';
 import { formatHarnessErrorMessage } from './format-harness-error.js';
 import { logger } from '@react-native-harness/tools';
-import { printSummary, writeTraceFile } from './diagnostics/index.js';
+import {
+  appendStepSummary,
+  printSummary,
+  summarizeRunKpis,
+  writeSummaryFile,
+  writeTraceFile,
+} from './diagnostics/index.js';
 import { toJestStatus } from './toJestStatus.js';
 
 const diagnosticsLogger = logger.child('diagnostics');
@@ -60,15 +67,30 @@ class CancelRun extends Error {
   }
 }
 
-const buildTestFailure = (err: unknown): { message: string; stack: string } => {
-  if (
-    err instanceof NativeCrashError ||
-    err instanceof RuntimeDisconnectError ||
-    err instanceof StartupStallError ||
-    err instanceof AppBridgeDisconnectedError ||
-    err instanceof DeviceNotRespondingError
-  ) {
-    return { message: (err as Error).message, stack: '' };
+const isRuntimeFailure = (err: unknown): err is Error =>
+  err instanceof NativeCrashError ||
+  err instanceof RuntimeDisconnectError ||
+  err instanceof StartupStallError ||
+  err instanceof AppBridgeDisconnectedError ||
+  err instanceof DeviceNotRespondingError;
+
+const formatRunningTest = (test: TestRunnerTestStartedEvent): string =>
+  `Running test: "${[...test.ancestorTitles, test.name].join(' › ')}"`;
+
+const buildTestFailure = (
+  err: unknown,
+  runningTest: TestRunnerTestStartedEvent | null = null,
+): { message: string; stack: string } => {
+  if (isRuntimeFailure(err)) {
+    if (!runningTest) {
+      return { message: err.message, stack: '' };
+    }
+
+    const [headline, ...details] = err.message.split('\n');
+    return {
+      message: [headline, formatRunningTest(runningTest), ...details].join('\n'),
+      stack: '',
+    };
   }
   return err as { message: string; stack: string };
 };
@@ -147,10 +169,19 @@ export const executeRun = async (
   const startTime = Date.now();
   const watchMode = globalConfig.watch || globalConfig.watchAll;
   const rootDir = globalConfig.rootDir ?? process.cwd();
-  const testFiles = tests.map((t) => path.relative(rootDir, t.path));
+  const testFiles = tests.map((t) => toRelativePosixPath(rootDir, t.path));
   const summary = createRunSummary();
   let caseEventChain = Promise.resolve();
+  // The device runs one test at a time, so a test that started and has not
+  // finished is the one the app was running if it crashes or disconnects.
+  let runningTest: TestRunnerTestStartedEvent | null = null;
   const unsubscribe = session.onTestRunnerEvent((event) => {
+    if (event.type === 'test-started') {
+      runningTest = event;
+    } else if (event.type === 'test-finished') {
+      runningTest = null;
+    }
+
     if (isHarnessCaseEvent(event)) {
       caseEventChain = caseEventChain.then(() =>
         event.type === 'test-started'
@@ -177,6 +208,11 @@ export const executeRun = async (
   };
 
   updateRunState();
+  session.lifecycle.emit({
+    type: 'phase',
+    phase: 'run.start',
+    attrs: { runId },
+  });
 
   await session.callHook('run:started', {
     runId,
@@ -206,8 +242,9 @@ export const executeRun = async (
     for (const test of tests) {
       if (watcher.isInterrupted()) throw new CancelRun();
 
-      const relativeTestPath = path.relative(rootDir, test.path);
+      const relativeTestPath = toRelativePosixPath(rootDir, test.path);
       const fileStartedAt = Date.now();
+      runningTest = null;
       let emittedTestFileFinished = false;
 
       const emitTestFileFinished = async (options: {
@@ -227,6 +264,11 @@ export const executeRun = async (
 
       await session.callHook('test-file:started', { runId, file: relativeTestPath });
       const fileSpan = diagnostics.start('run.file', { file: relativeTestPath });
+      session.lifecycle.emit({
+        type: 'phase',
+        phase: 'test-file.start',
+        attrs: { file: relativeTestPath },
+      });
       let fileStatus: 'passed' | 'failed' | 'skipped' | 'todo' = 'failed';
 
       try {
@@ -304,7 +346,11 @@ export const executeRun = async (
             await session.restartApp(test.path);
             shouldRestartAfterTimeout = false;
           }
-        } catch (err) {
+        } catch (error) {
+          const err =
+            error instanceof Error && error.name === 'HostSurfaceReplacedError'
+              ? new HostSurfaceReplacedError(test.path, error)
+              : error;
           fileStatus = 'failed';
           if (!emittedTestFileFinished) {
             await emitTestFileFinished({
@@ -314,14 +360,10 @@ export const executeRun = async (
             });
           }
 
-          const isRuntimeFailure =
-            err instanceof NativeCrashError ||
-            err instanceof RuntimeDisconnectError ||
-            err instanceof StartupStallError ||
-            err instanceof AppBridgeDisconnectedError ||
-            err instanceof DeviceNotRespondingError;
+          const isFileRuntimeFailure =
+            err instanceof HostSurfaceReplacedError || isRuntimeFailure(err);
 
-          if (isRuntimeFailure) {
+          if (isFileRuntimeFailure) {
             summary.failed += 1;
             updateRunState();
           }
@@ -330,12 +372,26 @@ export const executeRun = async (
             session.resetCrashState();
           }
 
-          updateRunState({ error: isRuntimeFailure ? undefined : err });
+          updateRunState({ error: isFileRuntimeFailure ? undefined : err });
           await caseEventChain;
-          await emitEvent('test-file-failure', test, buildTestFailure(err));
+          await emitEvent(
+            'test-file-failure',
+            test,
+            buildTestFailure(err, runningTest),
+          );
+          if (err instanceof HostSurfaceReplacedError) {
+            // Abandoned async test work may still be running in this process.
+            await session.restartApp(test.path);
+            isFirstTest = true;
+          }
         }
       } finally {
         fileSpan.end({ status: fileStatus });
+        session.lifecycle.emit({
+          type: 'phase',
+          phase: 'test-file.end',
+          attrs: { file: relativeTestPath, status: fileStatus },
+        });
       }
     }
   } catch (err) {
@@ -358,6 +414,12 @@ export const executeRun = async (
     await caseEventChain;
     unsubscribe();
     runSpan.end({ runId, status: finalStatus });
+    // Idle time between runs (watch mode) is not part of any run's metrics.
+    session.lifecycle.emit({
+      type: 'phase',
+      phase: 'run.end',
+      attrs: { runId, status: finalStatus },
+    });
 
     if (session.diagnostics.enabled) {
       const entries = session.diagnostics.flush();
@@ -365,6 +427,14 @@ export const executeRun = async (
         printSummary(entries, (line) => diagnosticsLogger.info(line));
         const tracePath = await writeTraceFile(entries, { projectRoot: rootDir, runId });
         diagnosticsLogger.info(`wrote diagnostics trace to ${tracePath}`);
+        const kpis = summarizeRunKpis(entries);
+        const summaryPath = await writeSummaryFile(kpis, {
+          projectRoot: rootDir,
+          runId,
+          sessionId: session.sessionId,
+        });
+        diagnosticsLogger.info(`wrote diagnostics summary to ${summaryPath}`);
+        await appendStepSummary(kpis);
       } catch (reportError) {
         diagnosticsLogger.warn('failed to write diagnostics report: %s', reportError);
       }

package/src/format-harness-error.ts

@@ -54,6 +54,11 @@ export const formatHarnessErrorMessage = (
   }
 
   const parts = [error.message];
+
+  if (error.diff) {
+    parts.push(error.diff);
+  }
+
   const pendingPromiseDetails = error.diagnostics?.pendingPromises
     ? formatPendingPromises(
         error.diagnostics.pendingPromises,

package/src/harness-session.ts

@@ -43,7 +43,13 @@ import {
   getTimeoutSignal,
   ensureSignalsDeliverable,
   waitForAbort,
+  checkHostHealth,
+  formatGitHubWarning,
+  formatSaturatedHostMessage,
+  isCI,
+  readProcessUsage,
   type Diagnostics,
+  type HostPressure,
 } from '@react-native-harness/tools';
 import {
   getConfig,
@@ -75,7 +81,12 @@ import {
   type ResourceLockManager,
   type ResourceLease,
 } from './resource-lock.js';
-import { observeBridgeEvents, observeMetroEvents } from './diagnostics/index.js';
+import {
+  observeBridgeEvents,
+  observeMetroEvents,
+  startSessionTelemetry,
+  type SessionTelemetry,
+} from './diagnostics/index.js';
 import { resolveHarnessMetroPort } from './metro-port.js';
 import { getAdditionalCliArgs } from './cli-args.js';
 import {
@@ -96,6 +107,8 @@ const isBridgeDisconnectError = (error: unknown) =>
   error instanceof Error && error.message === 'App bridge disconnected';
 const TEST_RUN_BRIDGE_STABILITY_WAIT_MS = 500;
 const DISPOSE_HOOK_TIMEOUT_MS = 5_000;
+// Upper bound on waiting for end-of-run telemetry before tearing resources down.
+const DISPOSE_TELEMETRY_TIMEOUT_MS = 10_000;
 
 const waitForBoundedSettlement = async <T>(
   promise: Promise<T>,
@@ -194,6 +207,10 @@ export type HarnessSession = {
   readonly config: HarnessConfig;
   readonly context: HarnessContext;
   readonly diagnostics: Diagnostics;
+  /** Identifies this session; names its incremental diagnostics log. */
+  readonly sessionId: string;
+  /** Run lifecycle phases, for telemetry probes (see `SessionTelemetry`). */
+  readonly lifecycle: SessionTelemetry['lifecycle'];
   onTestRunnerEvent: (listener: (event: TestRunnerEvents) => void) => () => void;
   runTestFile: (path: string, options: HarnessRunTestsOptions) => Promise<TestSuiteResult>;
   ensureAppReady: (testFilePath: string) => Promise<void>;
@@ -235,6 +252,8 @@ export const withPlatformReadyTimeout = async <T>(options: {
   timeout: number;
   signal: AbortSignal;
   work: (signal: AbortSignal) => Promise<T>;
+  /** Host pressure at the moment of the timeout, attached to the error. */
+  getHostPressure?: () => HostPressure | null;
 }): Promise<T> => {
   const timeoutSignal = getTimeoutSignal(options.timeout);
   const abortWait = waitForAbort(timeoutSignal);
@@ -242,7 +261,10 @@ export const withPlatformReadyTimeout = async <T>(options: {
     return await Promise.race([
       options.work(options.signal),
       abortWait.promise.catch(() => {
-        throw new PlatformReadyTimeoutError(options.timeout);
+        throw new PlatformReadyTimeoutError(
+          options.timeout,
+          options.getHostPressure?.() ?? null
+        );
       }),
     ]);
   } finally {
@@ -250,6 +272,39 @@ export const withPlatformReadyTimeout = async <T>(options: {
   }
 };
 
+// A saturated host is exactly where `ps` is slow; it took over 10s on CI.
+const HOST_HEALTH_PROCESS_LISTING_TIMEOUT_MS = 30_000;
+
+// Tells, before anything is booted, whether the host is already saturated by
+// something other than this run. Only a warning: a saturated runner can still
+// pass, but a later startup timeout then has an explanation.
+const reportSaturatedHost = async (diagnostics: Diagnostics): Promise<void> => {
+  try {
+    const verdict = await checkHostHealth();
+    diagnostics.mark('telemetry.host_health', {
+      load1: verdict.load1,
+      cpuCount: verdict.cpuCount,
+      idlePct: verdict.idlePct ?? undefined,
+      saturated: verdict.saturated,
+    });
+    if (!verdict.saturated) {
+      return;
+    }
+
+    const processes = await readProcessUsage(
+      AbortSignal.timeout(HOST_HEALTH_PROCESS_LISTING_TIMEOUT_MS)
+    ).catch(() => null);
+    const message = formatSaturatedHostMessage(verdict, processes?.topByCpu);
+    sessionLogger.warn(message);
+    const annotation = formatGitHubWarning('Saturated CI runner', message);
+    if (annotation) {
+      process.stdout.write(`${annotation}\n`);
+    }
+  } catch (error) {
+    sessionLogger.debug('host health check failed: %s', error);
+  }
+};
+
 type AppReadyOptions = {
   metroInstance: MetroInstance;
   bridge: HarnessBridge;
@@ -484,6 +539,9 @@ export const createHarnessSession = async (
 
   const setupStartedAt = Date.now();
   const { harnessConfig, platform, projectRoot, configProjectRoot } = await loadConfig(globalConfig);
+  // Metro platform for prewarm and startup detection. Vega apps request
+  // "kepler" bundles while the harness platform id stays "vega".
+  const bundlePlatform = platform.bundlePlatform ?? platform.platformId;
   applyEnvVars(harnessConfig, globalConfig);
 
   const diagnostics = createDiagnostics({
@@ -494,6 +552,25 @@ export const createHarnessSession = async (
     duration: Date.now() - setupStartedAt,
   });
 
+  // The one composition point for run telemetry. Everything below only emits
+  // lifecycle phases; probes translate them and polled data into diagnostics.
+  const telemetry = startSessionTelemetry({
+    diagnostics,
+    config: harnessConfig,
+    projectRoot,
+  });
+  telemetry.phase('session.created');
+  if (isCI()) {
+    void reportSaturatedHost(diagnostics);
+  }
+  // Telemetry runs timers and listens on `exit`, so a setup failure before the
+  // main try/catch below must still stop it.
+  const disposeTelemetryOnFailure = <T>(work: Promise<T>): Promise<T> =>
+    work.catch(async (error) => {
+      await telemetry.dispose();
+      throw error;
+    });
+
   sessionLogger.debug(
     'creating session for runner=%s platform=%s',
     platform.name,
@@ -515,13 +592,15 @@ export const createHarnessSession = async (
   process.once('SIGTERM', onEarlySignal);
   process.once('SIGINT', onEarlySignal);
 
-  const resourceLockKey = await (platform.getResourceLockKey?.() ?? getDefaultResourceLockKey(platform));
+  const resourceLockKey = await disposeTelemetryOnFailure(
+    Promise.resolve(platform.getResourceLockKey?.() ?? getDefaultResourceLockKey(platform))
+  );
   let didWaitForResourceLock = false;
   let lastStillWaitingLogAt = 0;
 
   logTestRunHeader(platform);
 
-  const resourceLease = await diagnostics.measure(
+  const resourceLease = await disposeTelemetryOnFailure(diagnostics.measure(
     'session.lock.wait',
     () =>
       lockManager.acquire(resourceLockKey, {
@@ -539,7 +618,7 @@ export const createHarnessSession = async (
         },
       }),
     { lockKey: resourceLockKey }
-  );
+  ));
 
   if (didWaitForResourceLock) logRunnerStarting(platform);
   sessionLogger.debug('resource lock acquired for runner=%s key=%s', platform.name, resourceLockKey);
@@ -590,7 +669,10 @@ export const createHarnessSession = async (
     const getCurrentRunId = () => currentRun?.runId;
     const clientLogCollector = createClientLogCollector();
 
-    const context: HarnessContext = { platform };
+    const context = {
+      platform,
+      updateSnapshot: globalConfig.updateSnapshot,
+    } satisfies Required<HarnessContext>;
     const crashArtifactWriter = createCrashArtifactWriter({
       runnerName: platform.name,
       platformId: platform.platformId,
@@ -602,6 +684,11 @@ export const createHarnessSession = async (
         noServer: true,
         timeout: runtimeConfig.bridgeTimeout,
         context,
+        liveness: {
+          // Loading a test file runs user code that has no timeout of its
+          // own, so it gets the same allowance as starting the bundle.
+          jsBlockBudget: { fileLoadMs: runtimeConfig.bundleStartTimeout },
+        },
       })
     );
     sessionLogger.debug('bridge initialized on Metro websocket path %s', HARNESS_BRIDGE_PATH);
@@ -616,6 +703,29 @@ export const createHarnessSession = async (
     // Noop until the Metro instance resolves and the deriver is attached.
     let disposeMetroDiagnostics: () => void = () => undefined;
 
+    const eagerPrewarm = runtimeConfig.eagerPrewarm !== false;
+    // On small hosts the bundle build and the platform boot compete for the
+    // same few cores, so the platform may ask to boot first.
+    const deferPrewarm = eagerPrewarm && (platform.deferMetroPrewarm?.() ?? false);
+    if (deferPrewarm) {
+      sessionLogger.debug('deferring Metro prewarm until the platform is ready');
+    }
+    const startPrewarm = (instance: MetroInstance) => {
+      // prewarm() memoizes this first call, so its session-lifetime setup
+      // signal is the one that matters — later callers' signals cannot
+      // cancel it. Not awaited: callers must not wait for the bundle.
+      const prewarmSpan = diagnostics.start('metro.prewarm', { deferred: deferPrewarm });
+      instance
+        .prewarm({
+          platform: bundlePlatform,
+          signal: sessionController.signal,
+        })
+        .then((completed) => prewarmSpan.end({ completed }))
+        // Swallow AbortError on teardown so it never becomes an
+        // unhandled rejection; non-abort failures resolve false.
+        .catch((error) => prewarmSpan.fail(error));
+    };
+
     try {
       [metroInstance, platformInstance] = await Promise.all([
         diagnostics.measure('metro.init', () =>
@@ -638,24 +748,13 @@ export const createHarnessSession = async (
             }
             initialized.metro = instance;
             sessionLogger.debug('Metro initialized');
+            telemetry.phase('metro.ready');
             // Attach the Metro diagnostics deriver before the eager prewarm
             // fires so its bundle build/request events land in the trace.
             disposeMetroDiagnostics = observeMetroEvents(instance.events, diagnostics);
-            if (runtimeConfig.eagerPrewarm !== false) {
+            if (eagerPrewarm && !deferPrewarm) {
               // Kick off the first bundle build while the platform is still booting.
-              // prewarm() memoizes this first call, so its session-lifetime setup
-              // signal is the one that matters — later callers' signals cannot
-              // cancel it. Not awaited: metro.init must resolve immediately.
-              const prewarmSpan = diagnostics.start('metro.prewarm');
-              instance
-                .prewarm({
-                  platform: platform.platformId,
-                  signal: sessionController.signal,
-                })
-                .then((completed) => prewarmSpan.end({ completed }))
-                // Swallow AbortError on teardown so it never becomes an
-                // unhandled rejection; non-abort failures resolve false.
-                .catch((error) => prewarmSpan.fail(error));
+              startPrewarm(instance);
             }
             return instance;
           })
@@ -666,6 +765,7 @@ export const createHarnessSession = async (
             withPlatformReadyTimeout({
               timeout: runtimeConfig.platformReadyTimeout,
               signal: sessionController.signal,
+              getHostPressure: telemetry.hostPressure,
               work: async (signal) => {
                 return await import(platform.runner).then((module) =>
                   module.default(platform.config, runtimeConfig, {
@@ -679,6 +779,8 @@ export const createHarnessSession = async (
                   }
                   initialized.platform = instance;
                   sessionLogger.debug('platform runner initialized');
+                  telemetry.attachPlatform(instance);
+                  telemetry.phase('platform.ready');
                   return instance;
                 });
               },
@@ -700,6 +802,10 @@ export const createHarnessSession = async (
       throw error;
     }
 
+    if (deferPrewarm) {
+      startPrewarm(metroInstance);
+    }
+
     const appLaunchOptions = (platform.config as { appLaunchOptions?: AppLaunchOptions }).appLaunchOptions;
 
     let currentAppSession: AppSession | null = null;
@@ -731,7 +837,7 @@ export const createHarnessSession = async (
     const appReadyBaseOptions: AppReadyOptions = {
       metroInstance,
       bridge,
-      platformId: platform.platformId,
+      platformId: bundlePlatform,
       bundleStartTimeout: runtimeConfig.bundleStartTimeout ?? 60000,
       readyTimeout: runtimeConfig.bridgeTimeout,
       maxAppRestarts: runtimeConfig.maxAppRestarts ?? 2,
@@ -808,6 +914,7 @@ export const createHarnessSession = async (
       // Abort only cancels finite/in-flight work. Ownership remains explicit
       // below, so this cannot race a platform or app-session disposal path.
       sessionController.abort();
+      telemetry.phase('dispose');
 
       const hookWork = (async () => {
         await hooks.drain();
@@ -840,6 +947,13 @@ export const createHarnessSession = async (
         hookError = hookResult.reason;
       }
 
+      // End-of-run telemetry has to observe the platform before it is torn
+      // down, but must never be able to hold teardown up for long.
+      await waitForBoundedSettlement(
+        telemetry.settled(),
+        DISPOSE_TELEMETRY_TIMEOUT_MS
+      );
+
       if (runtimeConfig.forwardClientLogs) {
         metroInstance.events.removeListener(clientLogListener);
       }
@@ -900,7 +1014,7 @@ export const createHarnessSession = async (
     };
 
     const dispose = (reason: 'normal' | 'abort' | 'error' = 'normal') => {
-      disposePromise ??= disposeOnce(reason);
+      disposePromise ??= disposeOnce(reason).finally(() => telemetry.dispose());
       return disposePromise;
     };
 
@@ -966,6 +1080,7 @@ export const createHarnessSession = async (
       await hooks.drain();
       sessionLogger.debug('app is ready for %s', testFilePath);
       appReadySpan.end({ file: testFilePath, reused: false });
+      telemetry.phase('app.ready', { file: testFilePath });
     };
 
     // Shared by restartApp (crash/timeout recovery) and the 'process' reset
@@ -1118,6 +1233,8 @@ export const createHarnessSession = async (
       config: runtimeConfig,
       context,
       diagnostics,
+      sessionId: telemetry.sessionId,
+      lifecycle: telemetry.lifecycle,
       onTestRunnerEvent: (listener) => {
         testRunnerEventListeners.add(listener);
         return () => {
@@ -1141,6 +1258,9 @@ export const createHarnessSession = async (
       },
       setRunState: (state) => {
         currentRun = state;
+        if (state) {
+          telemetry.trackRun(state.runId);
+        }
       },
       dispose: async (reason = 'normal') => {
         try {
@@ -1157,6 +1277,7 @@ export const createHarnessSession = async (
     // Cancels any inflight init work still holding sessionController.signal
     // (e.g. a platform init call abandoned after a readiness timeout race).
     sessionController.abort();
+    await telemetry.dispose();
     await Promise.allSettled([resourceLease.release(), metroPortLease?.release()]);
     if (receivedEarlySignal) {
       process.exit(1);

package/src/index.ts

@@ -7,6 +7,7 @@ import type {
   TestWatcher,
 } from 'jest-runner';
 import { createHarnessSession, type HarnessSession } from './harness-session.js';
+import { getWatchSession } from './watch-session.js';
 import { executeRun } from './execute-run.js';
 import { HarnessError } from '@react-native-harness/tools';
 import { getErrorMessage } from './logs.js';
@@ -20,7 +21,6 @@ export default class JestHarness implements EmittingTestRunnerInterface {
   readonly supportsEventEmitters = true as const;
 
   #globalConfig: Config.GlobalConfig;
-  #session: HarnessSession | null = null;
   #listeners = new Map<keyof TestEvents, Set<TestEventListener<keyof TestEvents>>>();
 
   constructor(globalConfig: Config.GlobalConfig) {
@@ -54,13 +54,15 @@ export default class JestHarness implements EmittingTestRunnerInterface {
 
     const isWatchMode = this.#globalConfig.watch || this.#globalConfig.watchAll;
 
+    let session: HarnessSession | null = null;
+
     try {
-      if (!this.#session) {
-        this.#session = await createHarnessSession(this.#globalConfig);
-      }
+      session = isWatchMode
+        ? await getWatchSession(this.#globalConfig)
+        : await createHarnessSession(this.#globalConfig);
 
       await executeRun(
-        this.#session,
+        session,
         tests,
         watcher,
         this.#emit,
@@ -73,8 +75,7 @@ export default class JestHarness implements EmittingTestRunnerInterface {
       throw error;
     } finally {
       if (!isWatchMode) {
-        await this.#session?.dispose();
-        this.#session = null;
+        await session?.dispose();
       }
     }
   }

package/src/jest-preset.ts

@@ -1,3 +1,21 @@
 export default {
   runner: '@react-native-harness/jest',
+  // Tests run serially on the device, so Jest only uses its workers to build
+  // the haste map. On a cold cache or after any file change that starts a pool
+  // of `availableParallelism() - 1` processes, which roughly doubles Jest's
+  // CPU time without making the run faster.
+  maxWorkers: 1,
+  // Build and cache output never contains tests, but it can hold tens of
+  // thousands of files. Jest checks these patterns before descending into a
+  // directory, so its crawl skips them entirely. Jest appends a project's own
+  // patterns to the preset's.
+  modulePathIgnorePatterns: [
+    '/\\.harness(/|$)',
+    '/ios/(Pods|build)(/|$)',
+    '/android/(build|\\.gradle|app/build|app/\\.cxx)(/|$)',
+  ],
+  // With the build output skipped, Jest's own crawl is cheaper than querying
+  // watchman, which costs two CLI process spawns per run and still lists every
+  // file. Metro keeps using watchman.
+  watchman: false,
 };

package/src/relative-path.ts

@@ -0,0 +1,10 @@
+import path from 'node:path';
+
+/**
+ * Returns `filePath` relative to `rootDir`, always using `/` as the separator.
+ *
+ * These paths leave the host (they are sent to the device and used in Metro
+ * bundle URLs and plugin hooks), so they must not depend on the host OS.
+ */
+export const toRelativePosixPath = (rootDir: string, filePath: string): string =>
+  path.relative(rootDir, filePath).split(path.sep).join('/');