@react-native-harness/jest 1.1.0-rc.3 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-native-harness/jest",
-  "version": "1.1.0-rc.3",
+  "version": "1.1.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -40,12 +40,12 @@
     "p-limit": "^7.1.1",
     "tslib": "^2.3.0",
     "yargs": "^17.7.2",
-    "@react-native-harness/bridge": "1.1.0-rc.3",
-    "@react-native-harness/config": "1.1.0-rc.3",
-    "@react-native-harness/bundler-metro": "1.1.0-rc.3",
-    "@react-native-harness/platforms": "1.1.0-rc.3",
-    "@react-native-harness/tools": "1.1.0-rc.3",
-    "@react-native-harness/plugins": "1.1.0-rc.3"
+    "@react-native-harness/bridge": "1.1.0",
+    "@react-native-harness/plugins": "1.1.0",
+    "@react-native-harness/bundler-metro": "1.1.0",
+    "@react-native-harness/platforms": "1.1.0",
+    "@react-native-harness/config": "1.1.0",
+    "@react-native-harness/tools": "1.1.0"
   },
   "devDependencies": {
     "@types/yargs": "^17.0.32",

package/src/__tests__/harness.test.ts

@@ -2,6 +2,7 @@ import { EventEmitter } from 'node:events';
 import { HARNESS_BRIDGE_PATH } from '@react-native-harness/bridge';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import type { Config as HarnessConfig } from '@react-native-harness/config';
+import { MetroPortRangeExhaustedError } from '../errors.js';
 import { definePlugin } from '@react-native-harness/plugins';
 import type {
   AppMonitor,
@@ -25,10 +26,12 @@ const mocks = vi.hoisted(() => ({
   getMetroInstance: vi.fn(),
   isMetroCacheReusable: vi.fn(() => false),
   logMetroCacheReused: vi.fn(),
+  logMetroPortFallback: vi.fn(),
   logRunnerStarting: vi.fn(),
   logRunnerStillWaitingInQueue: vi.fn(),
   logRunnerWaitingInQueue: vi.fn(),
   waitForMetroBackedAppReady: vi.fn(),
+  isPortAvailable: vi.fn(async () => true),
 }));
 
 vi.mock('@react-native-harness/bundler-metro', async () => {
@@ -39,6 +42,7 @@ vi.mock('@react-native-harness/bundler-metro', async () => {
   return {
     ...actual,
     getMetroInstance: mocks.getMetroInstance,
+    isPortAvailable: mocks.isPortAvailable,
     isMetroCacheReusable: mocks.isMetroCacheReusable,
     waitForMetroBackedAppReady: mocks.waitForMetroBackedAppReady,
   };
@@ -50,6 +54,7 @@ vi.mock('@react-native-harness/bridge/server', () => ({
 
 vi.mock('../logs.js', () => ({
   logMetroCacheReused: mocks.logMetroCacheReused,
+  logMetroPortFallback: mocks.logMetroPortFallback,
   logRunnerStarting: mocks.logRunnerStarting,
   logRunnerStillWaitingInQueue: mocks.logRunnerStillWaitingInQueue,
   logRunnerWaitingInQueue: mocks.logRunnerWaitingInQueue,
@@ -195,6 +200,8 @@ const createHarnessConfig = (
 
 beforeEach(() => {
   vi.clearAllMocks();
+  mocks.isPortAvailable.mockReset();
+  mocks.isPortAvailable.mockResolvedValue(true);
 });
 
 afterEach(() => {
@@ -377,7 +384,9 @@ describe('getHarness', () => {
 
     expect(runner).toHaveBeenCalledWith(
       platform.config,
-      expect.any(Object),
+      expect.objectContaining({
+        metroPort: 8081,
+      }),
       expect.objectContaining({
         signal: expect.any(AbortSignal),
       })
@@ -386,6 +395,85 @@ describe('getHarness', () => {
     await harness.dispose();
   });
 
+  it('resolves and exposes a fallback Metro port before platform init', async () => {
+    const { serverBridge } = createBridgeServer();
+    const appMonitor = createAppMonitor();
+    const platformInstance = createPlatformRunner({
+      createAppMonitor: () => appMonitor.appMonitor,
+    });
+    const metroInstance = createMetroInstance();
+
+    mocks.getBridgeServer.mockResolvedValue(serverBridge);
+    mocks.getMetroInstance.mockResolvedValue(metroInstance);
+    mocks.isPortAvailable
+      .mockResolvedValueOnce(false)
+      .mockResolvedValueOnce(true);
+
+    const runner = vi.fn(async () => platformInstance);
+    (
+      globalThis as typeof globalThis & {
+        __HARNESS_PLATFORM_RUNNER__?: (...args: unknown[]) => Promise<unknown>;
+      }
+    ).__HARNESS_PLATFORM_RUNNER__ = runner;
+
+    const platform: HarnessPlatform = {
+      config: {},
+      getResourceLockKey: () => 'android:emulator:Pixel_8_API_35',
+      name: 'android',
+      platformId: 'android',
+      runner: `data:text/javascript,${encodeURIComponent(
+        'export default (...args) => globalThis.__HARNESS_PLATFORM_RUNNER__(...args);'
+      )}`,
+    };
+
+    const harness = await getHarness(
+      createHarnessConfig(),
+      platform,
+      '/tmp/project'
+    );
+
+    expect(harness.config.metroPort).toBe(8082);
+    expect(mocks.getMetroInstance).toHaveBeenCalledWith(
+      expect.objectContaining({
+        harnessConfig: expect.objectContaining({
+          metroPort: 8082,
+        }),
+      }),
+      expect.any(AbortSignal)
+    );
+    expect(runner).toHaveBeenCalledWith(
+      platform.config,
+      expect.objectContaining({
+        metroPort: 8082,
+      }),
+      expect.objectContaining({
+        signal: expect.any(AbortSignal),
+      })
+    );
+    expect(mocks.logMetroPortFallback).toHaveBeenCalledWith(8081, 8082);
+
+    await harness.dispose();
+  });
+
+  it('fails when no Metro port is available in the retry window', async () => {
+    mocks.isPortAvailable.mockResolvedValue(false);
+
+    const platform: HarnessPlatform = {
+      config: {},
+      getResourceLockKey: () => 'android:emulator:Pixel_8_API_35',
+      name: 'android',
+      platformId: 'android',
+      runner: 'data:text/javascript,export default async () => ({})',
+    };
+
+    await expect(
+      getHarness(createHarnessConfig(), platform, '/tmp/project')
+    ).rejects.toBeInstanceOf(MetroPortRangeExhaustedError);
+
+    expect(mocks.getBridgeServer).not.toHaveBeenCalled();
+    expect(mocks.getMetroInstance).not.toHaveBeenCalled();
+  });
+
   it('falls back to a default resource lock key for platforms without getResourceLockKey', async () => {
     const { serverBridge } = createBridgeServer();
     const appMonitor = createAppMonitor();

package/src/__tests__/metro-port.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { Config as HarnessConfig } from '@react-native-harness/config';
+import type { HarnessPlatform } from '@react-native-harness/platforms';
+import { resolveHarnessMetroPort } from '../metro-port.js';
+
+const mocks = vi.hoisted(() => ({
+  isPortAvailable: vi.fn(async () => true),
+}));
+
+vi.mock('@react-native-harness/bundler-metro', () => ({
+  isPortAvailable: mocks.isPortAvailable,
+}));
+
+const createConfig = (overrides: Partial<HarnessConfig> = {}): HarnessConfig =>
+  ({
+    appRegistryComponentName: 'App',
+    bridgeTimeout: 60_000,
+    bundleStartTimeout: 60_000,
+    crashDetectionInterval: 500,
+    defaultRunner: 'ios-device',
+    detectNativeCrashes: true,
+    disableViewFlattening: false,
+    entryPoint: 'index.js',
+    forwardClientLogs: false,
+    maxAppRestarts: 2,
+    metroPort: 8081,
+    platformReadyTimeout: 300_000,
+    resetEnvironmentBetweenTestFiles: true,
+    runners: [],
+    unstable__enableMetroCache: false,
+    unstable__skipAlreadyIncludedModules: false,
+    ...overrides,
+  } as HarnessConfig);
+
+describe('resolveHarnessMetroPort', () => {
+  it('skips fallback allocation for iOS physical device runners', async () => {
+    const acquire = vi.fn();
+    const config = createConfig();
+    const platform: HarnessPlatform = {
+      config: {},
+      name: 'ios-device',
+      platformId: 'ios',
+      runner: 'unused',
+    };
+
+    const result = await resolveHarnessMetroPort({
+      config,
+      platform,
+      resourceLockManager: {
+        acquire,
+      },
+      signal: new AbortController().signal,
+    });
+
+    expect(result.config).toBe(config);
+    expect(result.metroPortLease).toBeNull();
+    expect(result.didFallback).toBe(false);
+    expect(acquire).not.toHaveBeenCalled();
+    expect(mocks.isPortAvailable).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/resource-lock.test.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import {
   createResourceLockManager,
   hashResourceLockKey,
@@ -12,7 +12,7 @@ describe('resource lock manager', () => {
 
   beforeEach(async () => {
     rootDir = await fs.mkdtemp(
-      path.join(os.tmpdir(), 'react-native-harness-resource-lock-test-')
+      path.join(os.tmpdir(), 'react-native-harness-resource-lock-test-'),
     );
   });
 
@@ -30,7 +30,7 @@ describe('resource lock manager', () => {
     const order: string[] = [];
 
     const firstLease = await manager.acquire(
-      'ios:simulator:iPhone 17 Pro:26.2'
+      'ios:simulator:iPhone 17 Pro:26.2',
     );
     const secondAcquire = manager
       .acquire('ios:simulator:iPhone 17 Pro:26.2', {
@@ -124,7 +124,7 @@ describe('resource lock manager', () => {
         createdAt: Date.now() - 1000,
         heartbeatAt: Date.now() - 1000,
       }),
-      'utf8'
+      'utf8',
     );
 
     const lease = await manager.acquire(key);
@@ -135,4 +135,58 @@ describe('resource lock manager', () => {
 
     await lease.release();
   });
+
+  it('keeps owner metadata valid when heartbeat writes overlap', async () => {
+    const manager = createResourceLockManager({
+      rootDir,
+      pollIntervalMs: 5,
+      heartbeatIntervalMs: 10,
+      staleLockTimeoutMs: 200,
+    });
+    const key = 'ios:simulator:iPhone 17 Pro:26.2';
+    const ownerFilePath = path.join(
+      rootDir,
+      hashResourceLockKey(key),
+      'owner.json',
+    );
+    const actualWriteFile = fs.writeFile.bind(fs);
+    const writeFileSpy = vi
+      .spyOn(fs, 'writeFile')
+      .mockImplementation(async (file, data, options) => {
+        if (
+          typeof file === 'string' &&
+          file.startsWith(ownerFilePath) &&
+          file !== ownerFilePath
+        ) {
+          await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+
+        return await actualWriteFile(file, data, options);
+      });
+
+    try {
+      const lease = await manager.acquire(key);
+      const initialOwner = JSON.parse(
+        await fs.readFile(ownerFilePath, 'utf8'),
+      ) as ResourceLockOwner;
+
+      await new Promise((resolve) => setTimeout(resolve, 80));
+
+      for (let index = 0; index < 5; index += 1) {
+        const owner = JSON.parse(
+          await fs.readFile(ownerFilePath, 'utf8'),
+        ) as ResourceLockOwner;
+        expect(owner.ticketId).toBe(initialOwner.ticketId);
+        await new Promise((resolve) => setTimeout(resolve, 10));
+      }
+
+      await lease.release();
+    } finally {
+      writeFileSpy.mockRestore();
+    }
+  });
 });
+
+type ResourceLockOwner = {
+  ticketId: string;
+};

package/src/errors.ts

@@ -36,6 +36,19 @@ export class PlatformReadyTimeoutError extends HarnessError {
   }
 }
 
+export class MetroPortRangeExhaustedError extends HarnessError {
+  constructor(
+    public readonly initialPort: number,
+    public readonly attempts: number
+  ) {
+    const finalPort = initialPort + attempts - 1;
+    super(
+      `Harness could not find an available Metro port in the range ${initialPort}-${finalPort}.`
+    );
+    this.name = 'MetroPortRangeExhaustedError';
+  }
+}
+
 export type NativeCrashPhase = 'startup' | 'execution';
 
 export type NativeCrashDetails = AppCrashDetails & {

package/src/harness.ts

@@ -49,11 +49,13 @@ import { createClientLogListener } from './client-log-handler.js';
 import path from 'node:path';
 import {
   logMetroCacheReused,
+  logMetroPortFallback,
   logRunnerStarting,
   logRunnerStillWaitingInQueue,
   logRunnerWaitingInQueue,
 } from './logs.js';
 import { createResourceLockManager } from './resource-lock.js';
+import { resolveHarnessMetroPort } from './metro-port.js';
 
 const harnessLogger = logger.child('runtime');
 const resourceLockManager = createResourceLockManager();
@@ -73,6 +75,7 @@ export type HarnessRunState = {
 
 export type Harness = {
   context: HarnessContext;
+  config: HarnessConfig;
   runTests: (
     path: string,
     options: HarnessRunTestsOptions
@@ -285,17 +288,33 @@ const getHarnessInternal = async (
     resourceLockKey
   );
   try {
-    maybeLogMetroCacheReuse(config, platform, projectRoot);
+    const {
+      config: runtimeConfig,
+      metroPortLease,
+      initialMetroPort,
+      didFallback,
+    } = await resolveHarnessMetroPort({
+      config,
+      platform,
+      resourceLockManager,
+      signal,
+    });
+
+    if (didFallback) {
+      logMetroPortFallback(initialMetroPort, runtimeConfig.metroPort);
+    }
+
+    maybeLogMetroCacheReuse(runtimeConfig, platform, projectRoot);
     const pluginAbortController = new AbortController();
     const pluginManager = createHarnessPluginManager<
       HarnessConfig,
       HarnessPlatform
     >({
-      plugins: (config.plugins ?? []) as Array<
+      plugins: (runtimeConfig.plugins ?? []) as Array<
         HarnessPlugin<object, HarnessConfig, HarnessPlatform>
       >,
       projectRoot,
-      config,
+      config: runtimeConfig,
       runner: platform,
       abortSignal: pluginAbortController.signal,
     });
@@ -361,7 +380,7 @@ const getHarnessInternal = async (
 
     const serverBridge = await getBridgeServer({
       noServer: true,
-      timeout: config.bridgeTimeout,
+      timeout: runtimeConfig.bridgeTimeout,
       context,
     });
     harnessLogger.debug(
@@ -377,7 +396,7 @@ const getHarnessInternal = async (
           getMetroInstance(
             {
               projectRoot,
-              harnessConfig: config,
+              harnessConfig: runtimeConfig,
               websocketEndpoints: {
                 [HARNESS_BRIDGE_PATH]:
                   serverBridge.ws as unknown as MetroWebSocketEndpoint,
@@ -389,12 +408,12 @@ const getHarnessInternal = async (
             return instance;
           }),
           withPlatformReadyTimeout({
-            timeout: config.platformReadyTimeout,
+            timeout: runtimeConfig.platformReadyTimeout,
             signal,
             work: async () => {
               return await import(platform.runner)
                 .then((module) =>
-                  module.default(platform.config, config, {
+                  module.default(platform.config, runtimeConfig, {
                     signal,
                   } satisfies HarnessPlatformInitOptions)
                 )
@@ -408,6 +427,7 @@ const getHarnessInternal = async (
       } catch (error) {
         await Promise.allSettled([
           resourceLease.release(),
+          metroPortLease?.release(),
           serverBridge.dispose(),
         ]);
         throw error;
@@ -625,7 +645,7 @@ const getHarnessInternal = async (
     appMonitor.addListener(onAppMonitorEvent);
     harnessLogger.debug('registered runtime, bridge, and Metro listeners');
 
-    if (config.forwardClientLogs) {
+    if (runtimeConfig.forwardClientLogs) {
       metroInstance.events.addListener(clientLogListener);
       harnessLogger.debug('client log forwarding enabled');
     }
@@ -656,7 +676,7 @@ const getHarnessInternal = async (
         hookError = error;
       }
 
-      if (config.forwardClientLogs) {
+      if (runtimeConfig.forwardClientLogs) {
         metroInstance.events.removeListener(clientLogListener);
       }
       metroInstance.events.removeListener(onMetroEvent);
@@ -671,6 +691,7 @@ const getHarnessInternal = async (
           serverBridge.dispose(),
           platformInstance.dispose(),
           metroInstance.dispose(),
+          metroPortLease?.release(),
         ]);
       } catch (error) {
         cleanupError = error;
@@ -744,9 +765,9 @@ const getHarnessInternal = async (
         serverBridge,
         platformInstance: platformInstance as HarnessPlatformRunner,
         platformId: platform.platformId,
-        bundleStartTimeout: config.bundleStartTimeout ?? 60000,
-        readyTimeout: config.bridgeTimeout,
-        maxAppRestarts: config.maxAppRestarts ?? 2,
+        bundleStartTimeout: runtimeConfig.bundleStartTimeout ?? 60000,
+        readyTimeout: runtimeConfig.bridgeTimeout,
+        maxAppRestarts: runtimeConfig.maxAppRestarts ?? 2,
         testFilePath,
         crashSupervisor,
         appLaunchOptions,
@@ -786,6 +807,7 @@ const getHarnessInternal = async (
 
     return {
       context,
+      config: runtimeConfig,
       runTests: async (path, options) => {
         await flushPendingHooks();
         activeTestFilePath = path;

package/src/logs.ts

@@ -45,6 +45,17 @@ export const logMetroCacheReused = (runner: HarnessPlatform): void => {
   log(`${TAG} Reusing Metro cache for ${chalk.bold(runner.name)}\n`);
 };
 
+export const logMetroPortFallback = (
+  initialPort: number,
+  selectedPort: number
+): void => {
+  log(
+    `${TAG} Harness could not use Metro port ${chalk.bold(
+      String(initialPort)
+    )} and is using ${chalk.bold(String(selectedPort))} instead.\n`
+  );
+};
+
 export const getErrorMessage = (error: HarnessError): string => {
   return `${ERROR_TAG} ${error.message}\n`;
 };

package/src/metro-port.ts

@@ -0,0 +1,76 @@
+import type { Config as HarnessConfig } from '@react-native-harness/config';
+import { isPortAvailable } from '@react-native-harness/bundler-metro';
+import type { HarnessPlatform } from '@react-native-harness/platforms';
+import { MetroPortRangeExhaustedError } from './errors.js';
+import type { ResourceLease, ResourceLockManager } from './resource-lock.js';
+
+export const METRO_PORT_SCAN_ATTEMPTS = 10;
+
+const getPortLockKey = (host: string | undefined, port: number): string => {
+  return `metro-port:${host?.trim() || '*'}:${port}`;
+};
+
+const isIosPhysicalRunner = (platform: HarnessPlatform): boolean => {
+  return platform.platformId === 'ios' && platform.name.includes('device');
+};
+
+export const resolveHarnessMetroPort = async (options: {
+  config: HarnessConfig;
+  platform: HarnessPlatform;
+  resourceLockManager: ResourceLockManager;
+  signal: AbortSignal;
+}): Promise<{
+  config: HarnessConfig;
+  metroPortLease: ResourceLease | null;
+  initialMetroPort: number;
+  didFallback: boolean;
+}> => {
+  const { config, platform, resourceLockManager, signal } = options;
+  const initialMetroPort = config.metroPort;
+  const host = config.host?.trim();
+
+  if (isIosPhysicalRunner(platform)) {
+    return {
+      config,
+      metroPortLease: null,
+      initialMetroPort,
+      didFallback: false,
+    };
+  }
+
+  for (let attempt = 0; attempt < METRO_PORT_SCAN_ATTEMPTS; attempt += 1) {
+    const candidatePort = initialMetroPort + attempt;
+    const metroPortLease = await resourceLockManager.acquire(
+      getPortLockKey(host, candidatePort),
+      { signal }
+    );
+
+    try {
+      if (!(await isPortAvailable(candidatePort, host))) {
+        await metroPortLease.release();
+        continue;
+      }
+
+      return {
+        config:
+          candidatePort === initialMetroPort
+            ? config
+            : {
+                ...config,
+                metroPort: candidatePort,
+              },
+        metroPortLease,
+        initialMetroPort,
+        didFallback: candidatePort !== initialMetroPort,
+      };
+    } catch (error) {
+      await metroPortLease.release();
+      throw error;
+    }
+  }
+
+  throw new MetroPortRangeExhaustedError(
+    initialMetroPort,
+    METRO_PORT_SCAN_ATTEMPTS
+  );
+};