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

package/package.json

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

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

@@ -0,0 +1,74 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { Config as HarnessConfig } from '@react-native-harness/config';
+import type { HarnessPlatform } from '@react-native-harness/platforms';
+
+const mocks = vi.hoisted(() => ({
+  isMetroCacheReusable: vi.fn(),
+  logMetroCacheReused: vi.fn(),
+  logMetroPrewarmCompleted: vi.fn(),
+}));
+
+vi.mock('@react-native-harness/bundler-metro', () => ({
+  isMetroCacheReusable: mocks.isMetroCacheReusable,
+}));
+
+vi.mock('../logs.js', () => ({
+  logMetroCacheReused: mocks.logMetroCacheReused,
+  logMetroPrewarmCompleted: mocks.logMetroPrewarmCompleted,
+}));
+
+import { maybeLogMetroCacheReuse } from '../harness.js';
+
+const platform: HarnessPlatform = {
+  name: 'ios',
+  platformId: 'ios',
+  runner: '/virtual/platform-runner.js',
+  config: {},
+};
+
+const createHarnessConfig = (
+  overrides: Partial<HarnessConfig> = {}
+): HarnessConfig =>
+  ({
+    appRegistryComponentName: 'App',
+    webSocketPort: 8081,
+    disableViewFlattening: false,
+    bridgeTimeout: 5000,
+    entryPoint: 'index.js',
+    unstable__enableMetroCache: true,
+    forwardClientLogs: false,
+    ...overrides,
+  }) as HarnessConfig;
+
+describe('maybeLogMetroCacheReuse', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.isMetroCacheReusable.mockReturnValue(false);
+  });
+
+  it('logs when an existing metro cache will be reused', () => {
+    mocks.isMetroCacheReusable.mockReturnValue(true);
+
+    maybeLogMetroCacheReuse(createHarnessConfig(), platform, '/tmp/project');
+
+    expect(mocks.isMetroCacheReusable).toHaveBeenCalledWith('/tmp/project');
+    expect(mocks.logMetroCacheReused).toHaveBeenCalledWith(platform);
+  });
+
+  it('does not log when metro cache reuse is disabled', () => {
+    maybeLogMetroCacheReuse(
+      createHarnessConfig({ unstable__enableMetroCache: false }),
+      platform,
+      '/tmp/project'
+    );
+
+    expect(mocks.isMetroCacheReusable).not.toHaveBeenCalled();
+    expect(mocks.logMetroCacheReused).not.toHaveBeenCalled();
+  });
+
+  it('does not log when the metro cache is absent', () => {
+    maybeLogMetroCacheReuse(createHarnessConfig(), platform, '/tmp/project');
+
+    expect(mocks.logMetroCacheReused).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/harness.test.ts

@@ -1,106 +1,276 @@
 import { EventEmitter } from 'node:events';
-import { describe, expect, it, vi } from 'vitest';
-import { waitForAppReady } from '../harness.js';
-import type { BridgeServer } from '@react-native-harness/bridge/server';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { Config as HarnessConfig } from '@react-native-harness/config';
+import { definePlugin } from '@react-native-harness/plugins';
 import type {
   AppMonitor,
+  AppMonitorEvent,
   AppMonitorListener,
+  HarnessPlatform,
   HarnessPlatformRunner,
 } from '@react-native-harness/platforms';
+import type { BridgeServer } from '@react-native-harness/bridge/server';
+import type {
+  MetroInstance,
+  Reporter,
+  ReportableEvent,
+  WaitForMetroBackedAppReadyOptions,
+} from '@react-native-harness/bundler-metro';
 import { createCrashSupervisor } from '../crash-supervisor.js';
 
+const mocks = vi.hoisted(() => ({
+  createCrashArtifactWriter: vi.fn(() => ({})),
+  getBridgeServer: vi.fn(),
+  getMetroInstance: vi.fn(),
+  isMetroCacheReusable: vi.fn(() => false),
+  logMetroCacheReused: vi.fn(),
+  waitForMetroBackedAppReady: vi.fn(),
+}));
+
+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'
+    );
+
+  return {
+    ...actual,
+    getMetroInstance: mocks.getMetroInstance,
+    isMetroCacheReusable: mocks.isMetroCacheReusable,
+    waitForMetroBackedAppReady: mocks.waitForMetroBackedAppReady,
+  };
+});
+
+vi.mock('@react-native-harness/bridge/server', () => ({
+  getBridgeServer: mocks.getBridgeServer,
+}));
+
+vi.mock('../logs.js', () => ({
+  logMetroCacheReused: mocks.logMetroCacheReused,
+}));
+
+vi.mock('@react-native-harness/tools', async () => {
+  const actual =
+    await vi.importActual<typeof import('@react-native-harness/tools')>(
+      '@react-native-harness/tools'
+    );
+
+  return {
+    ...actual,
+    createCrashArtifactWriter: mocks.createCrashArtifactWriter,
+  };
+});
+
+import { getHarness, waitForAppReady } from '../harness.js';
+import { StartupStallError } from '../errors.js';
+
 const createBridgeServer = () => {
   const emitter = new EventEmitter();
 
   return {
     serverBridge: {
+      rpc: {
+        clients: [],
+      },
       on: emitter.on.bind(emitter),
       once: emitter.once.bind(emitter),
       off: emitter.off.bind(emitter),
+      dispose: vi.fn(),
     } as unknown as BridgeServer,
     emitReady: () => {
-      emitter.emit('ready');
+      emitter.emit('ready', {
+        platform: 'ios',
+        manufacturer: 'Apple',
+        model: 'Simulator',
+        osVersion: '18.0',
+      });
+    },
+    emitEvent: (event: unknown) => {
+      emitter.emit('event', event);
+    },
+    emitDisconnect: () => {
+      emitter.emit('disconnect');
     },
   };
 };
 
-const createAppMonitor = (): AppMonitor => {
-  const listeners = new Set<AppMonitorListener>();
+const createReporter = (): Reporter => {
+  const listeners = new Set<(event: ReportableEvent) => void>();
 
   return {
-    start: async () => undefined,
-    stop: async () => undefined,
-    dispose: async () => undefined,
     addListener: (listener) => {
       listeners.add(listener);
     },
     removeListener: (listener) => {
       listeners.delete(listener);
     },
+    emit: (event) => {
+      listeners.forEach((listener) => listener(event));
+    },
+    clearAllListeners: () => {
+      listeners.clear();
+    },
+  };
+};
+
+const createMetroInstance = (
+  overrides: Partial<MetroInstance> = {}
+): MetroInstance => ({
+  events: createReporter(),
+  waitUntilHealthy: vi.fn(async () => 'HTTP 200: packager-status:running'),
+  prewarm: vi.fn(async () => false),
+  dispose: vi.fn(async () => undefined),
+  ...overrides,
+});
+
+const createAppMonitor = (): {
+  appMonitor: AppMonitor;
+  emit: (event: AppMonitorEvent) => void;
+} => {
+  const listeners = new Set<AppMonitorListener>();
+
+  return {
+    appMonitor: {
+      start: vi.fn(async () => undefined),
+      stop: vi.fn(async () => undefined),
+      dispose: vi.fn(async () => undefined),
+      addListener: (listener) => {
+        listeners.add(listener);
+      },
+      removeListener: (listener) => {
+        listeners.delete(listener);
+      },
+    },
+    emit: (event) => {
+      for (const listener of listeners) {
+        listener(event);
+      }
+    },
   };
 };
 
 const createPlatformRunner = (
-  restartApp: HarnessPlatformRunner['restartApp']
+  overrides: Partial<HarnessPlatformRunner> = {}
 ): HarnessPlatformRunner => ({
-  startApp: async () => undefined,
-  restartApp,
-  stopApp: async () => undefined,
-  dispose: async () => undefined,
-  isAppRunning: async () => true,
-  createAppMonitor: createAppMonitor,
+  startApp: vi.fn(async () => undefined),
+  restartApp: vi.fn(async () => undefined),
+  stopApp: vi.fn(async () => undefined),
+  dispose: vi.fn(async () => undefined),
+  isAppRunning: vi.fn(async () => true),
+  createAppMonitor: () => createAppMonitor().appMonitor,
+  ...overrides,
+});
+
+const createHarnessConfig = (
+  overrides: Partial<HarnessConfig> = {}
+): HarnessConfig =>
+  ({
+    appRegistryComponentName: 'App',
+    bridgeTimeout: 60_000,
+    bundleStartTimeout: 60_000,
+    crashDetectionInterval: 500,
+    defaultRunner: 'ios',
+    detectNativeCrashes: true,
+    disableViewFlattening: false,
+    entryPoint: 'index.js',
+    forwardClientLogs: false,
+    maxAppRestarts: 2,
+    metroPort: 8081,
+    resetEnvironmentBetweenTestFiles: true,
+    runners: [],
+    unstable__enableMetroCache: false,
+    unstable__skipAlreadyIncludedModules: false,
+    webSocketPort: 3001,
+    ...overrides,
+  }) as HarnessConfig;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+afterEach(() => {
+  delete (
+    globalThis as typeof globalThis & {
+      __HARNESS_PLATFORM_RUNNER__?: (...args: unknown[]) => Promise<unknown>;
+    }
+  ).__HARNESS_PLATFORM_RUNNER__;
 });
 
 describe('waitForAppReady', () => {
-  it('passes launch options to the initial launch', async () => {
+  it('delegates startup orchestration to bundler-metro and resolves readiness from the bridge', async () => {
     const { serverBridge, emitReady } = createBridgeServer();
-    const restartApp = vi.fn().mockResolvedValue(undefined);
-    const platformInstance = createPlatformRunner(restartApp);
+    const metroInstance = createMetroInstance();
+    const platformInstance = createPlatformRunner();
+    const { appMonitor } = createAppMonitor();
     const crashSupervisor = createCrashSupervisor({
-      appMonitor: createAppMonitor(),
+      appMonitor,
       platformRunner: platformInstance,
     });
 
-    const promise = waitForAppReady({
+    mocks.waitForMetroBackedAppReady.mockImplementationOnce(
+      async (options: WaitForMetroBackedAppReadyOptions) => {
+        options.onAttemptStart?.();
+        const readyPromise = options.waitForReady(new AbortController().signal);
+        emitReady();
+        await readyPromise;
+        options.onAttemptReset?.();
+      }
+    );
+
+    await waitForAppReady({
+      metroInstance,
       serverBridge,
       platformInstance,
-      bridgeTimeout: 5000,
+      platformId: 'ios',
+      bundleStartTimeout: 1_500,
+      readyTimeout: 2_500,
+      maxAppRestarts: 3,
       testFilePath: '/tmp/test.harness.ts',
       crashSupervisor,
-      appLaunchOptions: {
-        extras: {
-          mode: 'startup',
-        },
-      },
     });
 
-    await Promise.resolve();
-    expect(restartApp).toHaveBeenCalledWith({
-      extras: {
-        mode: 'startup',
-      },
-    });
+    expect(mocks.waitForMetroBackedAppReady).toHaveBeenCalledWith(
+      expect.objectContaining({
+        metro: metroInstance,
+        platformId: 'ios',
+        bundleStartTimeout: 1_500,
+        readyTimeout: 2_500,
+        maxAppRestarts: 3,
+        startAttempt: expect.any(Function),
+        waitForReady: expect.any(Function),
+        waitForCrash: expect.any(Function),
+      })
+    );
+    expect(crashSupervisor.isReady()).toBe(true);
 
-    emitReady();
-    await promise;
     await crashSupervisor.dispose();
   });
 
-  it('does not retry launch when the app never becomes ready', async () => {
-    vi.useFakeTimers();
-
+  it('passes launch options through the shared Metro startup helper', async () => {
     const { serverBridge } = createBridgeServer();
-    const restartApp = vi.fn().mockResolvedValue(undefined);
-    const platformInstance = createPlatformRunner(restartApp);
+    const metroInstance = createMetroInstance();
+    const restartApp = vi.fn(async () => undefined);
+    const platformInstance = createPlatformRunner({ restartApp });
+    const { appMonitor } = createAppMonitor();
     const crashSupervisor = createCrashSupervisor({
-      appMonitor: createAppMonitor(),
+      appMonitor,
       platformRunner: platformInstance,
     });
 
-    const promise = waitForAppReady({
+    mocks.waitForMetroBackedAppReady.mockImplementationOnce(
+      async (options: WaitForMetroBackedAppReadyOptions) => {
+        await options.startAttempt();
+      }
+    );
+
+    await waitForAppReady({
+      metroInstance,
       serverBridge,
       platformInstance,
-      bridgeTimeout: 1000,
+      platformId: 'ios',
+      bundleStartTimeout: 1_500,
+      readyTimeout: 2_500,
+      maxAppRestarts: 3,
       testFilePath: '/tmp/test.harness.ts',
       crashSupervisor,
       appLaunchOptions: {
@@ -110,13 +280,6 @@ describe('waitForAppReady', () => {
       },
     });
 
-    await Promise.resolve();
-    await vi.advanceTimersByTimeAsync(1000);
-
-    await expect(promise).rejects.toMatchObject({
-      name: 'AbortError',
-    });
-    expect(restartApp).toHaveBeenCalledTimes(1);
     expect(restartApp).toHaveBeenCalledWith({
       extras: {
         mode: 'startup',
@@ -124,6 +287,261 @@ describe('waitForAppReady', () => {
     });
 
     await crashSupervisor.dispose();
-    vi.useRealTimers();
+  });
+});
+
+describe('getHarness', () => {
+  it('routes ensureAppReady through the shared Metro startup helper', async () => {
+    const { serverBridge, emitReady } = createBridgeServer();
+    const appMonitor = createAppMonitor();
+    const restartApp = vi.fn(async () => undefined);
+    const platformInstance = createPlatformRunner({
+      restartApp,
+      createAppMonitor: () => appMonitor.appMonitor,
+    });
+    const metroInstance = createMetroInstance();
+
+    mocks.getBridgeServer.mockResolvedValue(serverBridge);
+    mocks.getMetroInstance.mockResolvedValue(metroInstance);
+    mocks.waitForMetroBackedAppReady.mockImplementationOnce(
+      async (options: WaitForMetroBackedAppReadyOptions) => {
+        await options.startAttempt();
+        const readyPromise = options.waitForReady(
+          new AbortController().signal
+        );
+        emitReady();
+        await readyPromise;
+      }
+    );
+
+    (
+      globalThis as typeof globalThis & {
+        __HARNESS_PLATFORM_RUNNER__?: (...args: unknown[]) => Promise<unknown>;
+      }
+    ).__HARNESS_PLATFORM_RUNNER__ = vi.fn(async () => platformInstance);
+
+    const platform: HarnessPlatform = {
+      config: {
+        appLaunchOptions: {
+          extras: {
+            source: 'ensure-ready',
+          },
+        },
+      },
+      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'
+    );
+
+    await harness.ensureAppReady('/tmp/example.harness.ts');
+
+    expect(mocks.waitForMetroBackedAppReady).toHaveBeenCalledTimes(1);
+    expect(restartApp).toHaveBeenCalledWith({
+      extras: {
+        source: 'ensure-ready',
+      },
+    });
+
+    await harness.dispose();
+  });
+
+  it('routes restart(testFilePath) through the shared Metro startup helper', async () => {
+    const { serverBridge, emitReady } = createBridgeServer();
+    const appMonitor = createAppMonitor();
+    const restartApp = vi.fn(async () => undefined);
+    const stopApp = vi.fn(async () => undefined);
+    const platformInstance = createPlatformRunner({
+      restartApp,
+      stopApp,
+      isAppRunning: vi.fn(async () => false),
+      createAppMonitor: () => appMonitor.appMonitor,
+    });
+    const metroInstance = createMetroInstance();
+
+    mocks.getBridgeServer.mockResolvedValue(serverBridge);
+    mocks.getMetroInstance.mockResolvedValue(metroInstance);
+    mocks.waitForMetroBackedAppReady.mockImplementationOnce(
+      async (options: WaitForMetroBackedAppReadyOptions) => {
+        await options.startAttempt();
+        const readyPromise = options.waitForReady(
+          new AbortController().signal
+        );
+        emitReady();
+        await readyPromise;
+      }
+    );
+
+    (
+      globalThis as typeof globalThis & {
+        __HARNESS_PLATFORM_RUNNER__?: (...args: unknown[]) => Promise<unknown>;
+      }
+    ).__HARNESS_PLATFORM_RUNNER__ = vi.fn(async () => platformInstance);
+
+    const platform: HarnessPlatform = {
+      config: {
+        appLaunchOptions: {
+          extras: {
+            source: 'restart',
+          },
+        },
+      },
+      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'
+    );
+
+    await harness.restart('/tmp/restart.harness.ts');
+
+    expect(stopApp).toHaveBeenCalledTimes(1);
+    expect(mocks.waitForMetroBackedAppReady).toHaveBeenCalledTimes(1);
+    expect(restartApp).toHaveBeenCalledWith({
+      extras: {
+        source: 'restart',
+      },
+    });
+
+    await harness.dispose();
+  });
+});
+
+describe('plugins', () => {
+  it('invokes lifecycle and runtime plugin handlers for configured plugins', async () => {
+    const { serverBridge, emitReady, emitEvent, emitDisconnect } =
+      createBridgeServer();
+    const appMonitor = createAppMonitor();
+    const platformInstance = createPlatformRunner({
+      createAppMonitor: () => appMonitor.appMonitor,
+    });
+    const observedHooks: string[] = [];
+
+    mocks.getBridgeServer.mockResolvedValue(serverBridge);
+    const metroInstance = createMetroInstance();
+    mocks.getMetroInstance.mockResolvedValue(metroInstance);
+
+    (
+      globalThis as typeof globalThis & {
+        __HARNESS_PLATFORM_RUNNER__?: (...args: unknown[]) => Promise<unknown>;
+      }
+    ).__HARNESS_PLATFORM_RUNNER__ = vi.fn(async () => platformInstance);
+
+    const plugin = definePlugin<
+      {
+        creationCount: number;
+      },
+      HarnessConfig,
+      HarnessPlatform
+    >({
+      name: 'test-plugin',
+      createState: () => ({
+        creationCount: 0,
+      }),
+      hooks: {
+        harness: {
+          beforeCreation: (ctx) => {
+            ctx.state.creationCount += 1;
+            observedHooks.push(
+              `beforeCreation:${ctx.platform.platformId}:${ctx.appLaunchOptions == null ? 'no-launch-options' : 'launch-options'}`
+            );
+          },
+          beforeDispose: (ctx) => {
+            observedHooks.push(
+              `beforeDispose:${ctx.state.creationCount}:${ctx.reason}`
+            );
+          },
+        },
+        runtime: {
+          ready: (ctx) => {
+            observedHooks.push(`runtime.ready:${ctx.runId}:${ctx.device.platform}`);
+          },
+          disconnected: (ctx) => {
+            observedHooks.push(`runtime.disconnected:${ctx.reason}`);
+          },
+        },
+        collection: {
+          started: (ctx) => {
+            observedHooks.push(`collection.started:${ctx.file}`);
+          },
+        },
+      },
+    });
+
+    const platform: HarnessPlatform = {
+      config: {
+        appLaunchOptions: {
+          environment: {
+            MODE: 'test',
+          },
+        },
+      },
+      name: 'ios',
+      platformId: 'ios',
+      runner: `data:text/javascript,${encodeURIComponent(
+        'export default (...args) => globalThis.__HARNESS_PLATFORM_RUNNER__(...args);'
+      )}`,
+    };
+
+    const harness = await getHarness(
+      createHarnessConfig({
+        plugins: [plugin],
+      }),
+      platform,
+      '/tmp/project'
+    );
+
+    harness.setRunState({
+      runId: 'run-1',
+      startTime: Date.now(),
+      testFiles: ['example.harness.ts'],
+      watchMode: false,
+      coverageEnabled: false,
+      summary: {
+        passed: 1,
+        failed: 0,
+        skipped: 0,
+        todo: 0,
+      },
+      status: 'passed',
+    });
+
+    emitReady();
+    emitEvent({
+      type: 'collection-started',
+      file: 'example.harness.ts',
+    });
+    emitDisconnect();
+
+    await harness.dispose();
+
+    expect(observedHooks).toEqual([
+      'beforeCreation:ios:launch-options',
+      'runtime.ready:run-1:ios',
+      'collection.started:example.harness.ts',
+      'runtime.disconnected:bridge-disconnected',
+      'beforeDispose:1:normal',
+    ]);
+  });
+});
+
+describe('StartupStallError', () => {
+  it('includes the configured timeout and attempt count', () => {
+    expect(new StartupStallError(1_500, 4).message).toBe(
+      'The app did not request its Metro bundle after 4 launch attempts within 1500ms. Last Metro status: unknown.'
+    );
   });
 });