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

package/dist/types.d.ts

@@ -0,0 +1,17 @@
+import type { TestContext, TestResult } from '@jest/test-result';
+import type { Config, TestRunnerOptions } from 'jest-runner';
+import type { CustomEnvironment } from '@react-native-harness/cli';
+export type RunTestOptions<ExtraOptions extends Record<string, unknown> = Record<string, unknown>> = {
+    config: Config.ProjectConfig;
+    extraOptions: ExtraOptions;
+    globalConfig: Config.GlobalConfig;
+    rawModuleMap: ReturnType<TestContext['moduleMap']['getRawModuleMap']> | null;
+    options: TestRunnerOptions;
+    testPath: string;
+};
+export type RunTest<ExtraOptions extends Record<string, unknown> = Record<string, unknown>> = (options: RunTestOptions<ExtraOptions>, environment: CustomEnvironment) => TestResult | Promise<TestResult>;
+export interface TestDetail {
+    title: string;
+    path: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEnE,MAAM,MAAM,cAAc,CACxB,YAAY,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IACpE;IACF,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC;IAC7B,YAAY,EAAE,YAAY,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC,YAAY,CAAC;IAClC,YAAY,EAAE,UAAU,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,iBAAiB,CAAC,CAAC,GAAG,IAAI,CAAC;IAC7E,OAAO,EAAE,iBAAiB,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,OAAO,CACjB,YAAY,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IACpE,CACF,OAAO,EAAE,cAAc,CAAC,YAAY,CAAC,EACrC,WAAW,EAAE,iBAAiB,KAC3B,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-native-harness/jest",
-  "version": "1.1.0-rc.2",
+  "version": "1.1.0-rc.4",
   "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/config": "1.1.0-rc.2",
-    "@react-native-harness/bundler-metro": "1.1.0-rc.2",
-    "@react-native-harness/bridge": "1.1.0-rc.2",
-    "@react-native-harness/plugins": "1.1.0-rc.2",
-    "@react-native-harness/tools": "1.1.0-rc.2",
-    "@react-native-harness/platforms": "1.1.0-rc.2"
+    "@react-native-harness/bridge": "1.1.0-rc.4",
+    "@react-native-harness/plugins": "1.1.0-rc.4",
+    "@react-native-harness/platforms": "1.1.0-rc.4",
+    "@react-native-harness/tools": "1.1.0-rc.4",
+    "@react-native-harness/config": "1.1.0-rc.4",
+    "@react-native-harness/bundler-metro": "1.1.0-rc.4"
   },
   "devDependencies": {
     "@types/yargs": "^17.0.32",

package/src/__tests__/errors.test.ts

@@ -1,5 +1,13 @@
 import { describe, expect, it } from 'vitest';
-import { NativeCrashError } from '../errors.js';
+import { NativeCrashError, PlatformReadyTimeoutError } from '../errors.js';
+
+describe('PlatformReadyTimeoutError', () => {
+  it('includes the configured timeout and config hint', () => {
+    expect(new PlatformReadyTimeoutError(300000).message).toBe(
+      'The platform did not become ready within 300000ms. Increase "platformReadyTimeout" if your device, simulator, or emulator needs more time to start.'
+    );
+  });
+});
 
 describe('NativeCrashError', () => {
   it('formats the extracted stack trace in the error message', () => {
@@ -35,7 +43,9 @@ describe('NativeCrashError', () => {
       exceptionType: 'EXC_CRASH',
     });
 
-    expect(error.message).not.toContain('notify_get_state check indicated test daemon not ready');
+    expect(error.message).not.toContain(
+      'notify_get_state check indicated test daemon not ready'
+    );
     expect(error.message).toContain('Signal: SIGABRT');
     expect(error.message).toContain('Exception: EXC_CRASH');
     expect(error.message).toContain('Process: HarnessPlayground (pid 18007)');
@@ -54,9 +64,9 @@ describe('NativeCrashError', () => {
       stackTrace: [frame],
     });
 
-    expect(error.message.match(/MainActivity\.onCreate\(MainActivity\.kt:38\)/g)).toHaveLength(
-      1
-    );
+    expect(
+      error.message.match(/MainActivity\.onCreate\(MainActivity\.kt:38\)/g)
+    ).toHaveLength(1);
   });
 
   it('collapses the native crash stack header so jest does not reprint multiline messages', () => {
@@ -65,6 +75,8 @@ describe('NativeCrashError', () => {
       summary: ['line one', 'line two'].join('\n'),
     });
 
-    expect(error.stack).toBe('NativeCrashError: The native app crashed while preparing to run this test file.');
+    expect(error.stack).toBe(
+      'NativeCrashError: The native app crashed while preparing to run this test file.'
+    );
   });
 });

package/src/__tests__/harness-cache.test.ts

@@ -24,6 +24,7 @@ const platform: HarnessPlatform = {
   platformId: 'ios',
   runner: '/virtual/platform-runner.js',
   config: {},
+  getResourceLockKey: () => 'ios:simulator:iPhone 17 Pro:26.2',
 };
 
 const createHarnessConfig = (
@@ -31,14 +32,13 @@ const createHarnessConfig = (
 ): HarnessConfig =>
   ({
     appRegistryComponentName: 'App',
-    webSocketPort: 8081,
     disableViewFlattening: false,
     bridgeTimeout: 5000,
     entryPoint: 'index.js',
     unstable__enableMetroCache: true,
     forwardClientLogs: false,
     ...overrides,
-  }) as HarnessConfig;
+  } as HarnessConfig);
 
 describe('maybeLogMetroCacheReuse', () => {
   beforeEach(() => {

package/src/__tests__/harness.test.ts

@@ -1,6 +1,8 @@
 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,
@@ -24,18 +26,23 @@ 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 () => {
-  const actual =
-    await vi.importActual<typeof import('@react-native-harness/bundler-metro')>(
-      '@react-native-harness/bundler-metro'
-    );
+  const actual = await vi.importActual<
+    typeof import('@react-native-harness/bundler-metro')
+  >('@react-native-harness/bundler-metro');
 
   return {
     ...actual,
     getMetroInstance: mocks.getMetroInstance,
+    isPortAvailable: mocks.isPortAvailable,
     isMetroCacheReusable: mocks.isMetroCacheReusable,
     waitForMetroBackedAppReady: mocks.waitForMetroBackedAppReady,
   };
@@ -47,13 +54,16 @@ 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,
 }));
 
 vi.mock('@react-native-harness/tools', async () => {
-  const actual =
-    await vi.importActual<typeof import('@react-native-harness/tools')>(
-      '@react-native-harness/tools'
-    );
+  const actual = await vi.importActual<
+    typeof import('@react-native-harness/tools')
+  >('@react-native-harness/tools');
 
   return {
     ...actual,
@@ -62,13 +72,14 @@ vi.mock('@react-native-harness/tools', async () => {
 });
 
 import { getHarness, waitForAppReady } from '../harness.js';
-import { StartupStallError } from '../errors.js';
+import { PlatformReadyTimeoutError, StartupStallError } from '../errors.js';
 
 const createBridgeServer = () => {
   const emitter = new EventEmitter();
 
   return {
     serverBridge: {
+      ws: {} as BridgeServer['ws'],
       rpc: {
         clients: [],
       },
@@ -117,6 +128,8 @@ const createMetroInstance = (
   overrides: Partial<MetroInstance> = {}
 ): MetroInstance => ({
   events: createReporter(),
+  httpServer: {} as never,
+  websocketEndpoints: {},
   waitUntilHealthy: vi.fn(async () => 'HTTP 200: packager-status:running'),
   prewarm: vi.fn(async () => false),
   dispose: vi.fn(async () => undefined),
@@ -176,16 +189,19 @@ const createHarnessConfig = (
     forwardClientLogs: false,
     maxAppRestarts: 2,
     metroPort: 8081,
+    platformReadyTimeout: 300_000,
     resetEnvironmentBetweenTestFiles: true,
     runners: [],
     unstable__enableMetroCache: false,
     unstable__skipAlreadyIncludedModules: false,
     webSocketPort: 3001,
     ...overrides,
-  }) as HarnessConfig;
+  } as HarnessConfig);
 
 beforeEach(() => {
   vi.clearAllMocks();
+  mocks.isPortAvailable.mockReset();
+  mocks.isPortAvailable.mockResolvedValue(true);
 });
 
 afterEach(() => {
@@ -291,6 +307,208 @@ describe('waitForAppReady', () => {
 });
 
 describe('getHarness', () => {
+  it('fails when the platform runner does not become ready within platformReadyTimeout', async () => {
+    const { serverBridge } = createBridgeServer();
+    const metroInstance = createMetroInstance();
+
+    mocks.getBridgeServer.mockResolvedValue(serverBridge);
+    mocks.getMetroInstance.mockResolvedValue(metroInstance);
+
+    (
+      globalThis as typeof globalThis & {
+        __HARNESS_PLATFORM_RUNNER__?: (...args: unknown[]) => Promise<unknown>;
+      }
+    ).__HARNESS_PLATFORM_RUNNER__ = vi.fn(
+      async () =>
+        await new Promise((_, reject) => {
+          setTimeout(() => {
+            reject(new DOMException('The operation was aborted', 'AbortError'));
+          }, 20);
+        })
+    );
+
+    const platform: HarnessPlatform = {
+      config: {},
+      getResourceLockKey: () => 'ios:test-platform-ready-timeout',
+      name: 'ios',
+      platformId: 'ios',
+      runner: `data:text/javascript,${encodeURIComponent(
+        'export default (...args) => globalThis.__HARNESS_PLATFORM_RUNNER__(...args);'
+      )}`,
+    };
+
+    await expect(
+      getHarness(
+        createHarnessConfig({
+          platformReadyTimeout: 10,
+        }),
+        platform,
+        '/tmp/project'
+      )
+    ).rejects.toBeInstanceOf(PlatformReadyTimeoutError);
+  });
+
+  it('passes a platform init signal to the runner factory', async () => {
+    const { serverBridge } = createBridgeServer();
+    const appMonitor = createAppMonitor();
+    const platformInstance = createPlatformRunner({
+      createAppMonitor: () => appMonitor.appMonitor,
+    });
+    const metroInstance = createMetroInstance();
+
+    mocks.getBridgeServer.mockResolvedValue(serverBridge);
+    mocks.getMetroInstance.mockResolvedValue(metroInstance);
+
+    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: () => 'ios:test-platform-init-signal',
+      name: 'ios',
+      platformId: 'ios',
+      runner: `data:text/javascript,${encodeURIComponent(
+        'export default (...args) => globalThis.__HARNESS_PLATFORM_RUNNER__(...args);'
+      )}`,
+    };
+
+    const harness = await getHarness(
+      createHarnessConfig(),
+      platform,
+      '/tmp/project'
+    );
+
+    expect(runner).toHaveBeenCalledWith(
+      platform.config,
+      expect.objectContaining({
+        metroPort: 8081,
+      }),
+      expect.objectContaining({
+        signal: expect.any(AbortSignal),
+      })
+    );
+
+    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();
+    const platformInstance = createPlatformRunner({
+      createAppMonitor: () => appMonitor.appMonitor,
+    });
+    const metroInstance = createMetroInstance();
+
+    mocks.getBridgeServer.mockResolvedValue(serverBridge);
+    mocks.getMetroInstance.mockResolvedValue(metroInstance);
+
+    (
+      globalThis as typeof globalThis & {
+        __HARNESS_PLATFORM_RUNNER__?: (...args: unknown[]) => Promise<unknown>;
+      }
+    ).__HARNESS_PLATFORM_RUNNER__ = vi.fn(async () => platformInstance);
+
+    const platform: HarnessPlatform = {
+      config: {},
+      name: 'legacy-ios',
+      platformId: 'ios',
+      runner: `data:text/javascript,${encodeURIComponent(
+        'export default (...args) => globalThis.__HARNESS_PLATFORM_RUNNER__(...args);'
+      )}`,
+    };
+
+    const harness = await getHarness(
+      createHarnessConfig(),
+      platform,
+      '/tmp/project'
+    );
+
+    await harness.dispose();
+  });
+
   it('routes ensureAppReady through the shared Metro startup helper', async () => {
     const { serverBridge, emitReady } = createBridgeServer();
     const appMonitor = createAppMonitor();
@@ -306,9 +524,7 @@ describe('getHarness', () => {
     mocks.waitForMetroBackedAppReady.mockImplementationOnce(
       async (options: WaitForMetroBackedAppReadyOptions) => {
         await options.startAttempt();
-        const readyPromise = options.waitForReady(
-          new AbortController().signal
-        );
+        const readyPromise = options.waitForReady(new AbortController().signal);
         emitReady();
         await readyPromise;
       }
@@ -333,10 +549,13 @@ describe('getHarness', () => {
       runner: `data:text/javascript,${encodeURIComponent(
         'export default (...args) => globalThis.__HARNESS_PLATFORM_RUNNER__(...args);'
       )}`,
+      getResourceLockKey: () => 'ios:simulator:iPhone 17 Pro:26.2',
     };
 
     const harness = await getHarness(
-      createHarnessConfig(),
+      createHarnessConfig({
+        bridgeTimeout: 1,
+      }),
       platform,
       '/tmp/project'
     );
@@ -371,9 +590,7 @@ describe('getHarness', () => {
     mocks.waitForMetroBackedAppReady.mockImplementationOnce(
       async (options: WaitForMetroBackedAppReadyOptions) => {
         await options.startAttempt();
-        const readyPromise = options.waitForReady(
-          new AbortController().signal
-        );
+        const readyPromise = options.waitForReady(new AbortController().signal);
         emitReady();
         await readyPromise;
       }
@@ -398,6 +615,7 @@ describe('getHarness', () => {
       runner: `data:text/javascript,${encodeURIComponent(
         'export default (...args) => globalThis.__HARNESS_PLATFORM_RUNNER__(...args);'
       )}`,
+      getResourceLockKey: () => 'ios:simulator:iPhone 17 Pro:26.2',
     };
 
     const harness = await getHarness(
@@ -406,6 +624,19 @@ describe('getHarness', () => {
       '/tmp/project'
     );
 
+    expect(mocks.getBridgeServer).toHaveBeenCalledWith(
+      expect.objectContaining({
+        noServer: true,
+      })
+    );
+    expect(mocks.getMetroInstance).toHaveBeenCalledWith(
+      expect.objectContaining({
+        websocketEndpoints: {
+          [HARNESS_BRIDGE_PATH]: serverBridge.ws,
+        },
+      }),
+      expect.any(AbortSignal)
+    );
     await harness.restart('/tmp/restart.harness.ts');
 
     expect(stopApp).toHaveBeenCalledTimes(1);
@@ -456,7 +687,25 @@ describe('plugins', () => {
           beforeCreation: (ctx) => {
             ctx.state.creationCount += 1;
             observedHooks.push(
-              `beforeCreation:${ctx.platform.platformId}:${ctx.appLaunchOptions == null ? 'no-launch-options' : 'launch-options'}`
+              `beforeCreation:${ctx.platform.platformId}:${
+                ctx.appLaunchOptions == null
+                  ? 'no-launch-options'
+                  : 'launch-options'
+              }`
+            );
+          },
+          beforeRun: (ctx) => {
+            observedHooks.push(
+              `beforeRun:${ctx.platform.platformId}:${
+                ctx.appLaunchOptions == null
+                  ? 'no-launch-options'
+                  : 'launch-options'
+              }`
+            );
+          },
+          afterRun: (ctx) => {
+            observedHooks.push(
+              `afterRun:${ctx.state.creationCount}:${ctx.reason}`
             );
           },
           beforeDispose: (ctx) => {
@@ -467,7 +716,9 @@ describe('plugins', () => {
         },
         runtime: {
           ready: (ctx) => {
-            observedHooks.push(`runtime.ready:${ctx.runId}:${ctx.device.platform}`);
+            observedHooks.push(
+              `runtime.ready:${ctx.runId}:${ctx.device.platform}`
+            );
           },
           disconnected: (ctx) => {
             observedHooks.push(`runtime.disconnected:${ctx.reason}`);
@@ -494,6 +745,7 @@ describe('plugins', () => {
       runner: `data:text/javascript,${encodeURIComponent(
         'export default (...args) => globalThis.__HARNESS_PLATFORM_RUNNER__(...args);'
       )}`,
+      getResourceLockKey: () => 'ios:simulator:iPhone 17 Pro:26.2',
     };
 
     const harness = await getHarness(
@@ -530,12 +782,83 @@ describe('plugins', () => {
 
     expect(observedHooks).toEqual([
       'beforeCreation:ios:launch-options',
+      'beforeRun:ios:launch-options',
       'runtime.ready:run-1:ios',
       'collection.started:example.harness.ts',
       'runtime.disconnected:bridge-disconnected',
+      'afterRun:1:normal',
       'beforeDispose:1:normal',
     ]);
   });
+
+  it('waits in queue before starting Metro and releases the lock on dispose', async () => {
+    const resourceKey = 'ios:simulator:iPhone 17 Pro:26.2';
+    const firstPlatformRunner = createPlatformRunner();
+    const secondPlatformRunner = createPlatformRunner();
+    const secondAppMonitor = createAppMonitor();
+    const firstMetroInstance = createMetroInstance();
+    const secondMetroInstance = createMetroInstance();
+    const firstBridge = createBridgeServer();
+    const secondBridge = createBridgeServer();
+
+    mocks.getBridgeServer
+      .mockResolvedValueOnce(firstBridge.serverBridge)
+      .mockResolvedValueOnce(secondBridge.serverBridge);
+    mocks.getMetroInstance
+      .mockResolvedValueOnce(firstMetroInstance)
+      .mockResolvedValueOnce(secondMetroInstance);
+
+    let invocationCount = 0;
+    (
+      globalThis as typeof globalThis & {
+        __HARNESS_PLATFORM_RUNNER__?: (...args: unknown[]) => Promise<unknown>;
+      }
+    ).__HARNESS_PLATFORM_RUNNER__ = vi.fn(async () => {
+      invocationCount += 1;
+      return invocationCount === 1
+        ? firstPlatformRunner
+        : createPlatformRunner({
+            createAppMonitor: () => secondAppMonitor.appMonitor,
+            dispose: secondPlatformRunner.dispose,
+          });
+    });
+
+    const platform: HarnessPlatform = {
+      config: {},
+      name: 'ios',
+      platformId: 'ios',
+      runner: `data:text/javascript,${encodeURIComponent(
+        'export default (...args) => globalThis.__HARNESS_PLATFORM_RUNNER__(...args);'
+      )}`,
+      getResourceLockKey: () => resourceKey,
+    };
+
+    const firstHarness = await getHarness(
+      createHarnessConfig(),
+      platform,
+      '/tmp/project'
+    );
+
+    const secondHarnessPromise = getHarness(
+      createHarnessConfig(),
+      platform,
+      '/tmp/project'
+    );
+
+    await new Promise((resolve) => setTimeout(resolve, 1100));
+
+    expect(mocks.logRunnerWaitingInQueue).toHaveBeenCalledWith(platform);
+    expect(mocks.logRunnerStarting).not.toHaveBeenCalled();
+    expect(mocks.getMetroInstance).toHaveBeenCalledTimes(1);
+
+    await firstHarness.dispose();
+    const secondHarness = await secondHarnessPromise;
+
+    expect(mocks.logRunnerStarting).toHaveBeenCalledWith(platform);
+    expect(mocks.getMetroInstance).toHaveBeenCalledTimes(2);
+
+    await secondHarness.dispose();
+  });
 });
 
 describe('StartupStallError', () => {

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();
+  });
+});