@react-native-harness/bridge 1.2.0-rc.1 → 1.3.0

package/src/server.ts

@@ -1,6 +1,5 @@
 import { WebSocketServer, type WebSocket } from 'ws';
-import { type BirpcGroup, createBirpcGroup } from 'birpc';
-import { logger } from '@react-native-harness/tools';
+import { createBirpc, type BirpcReturn } from 'birpc';
 import { EventEmitter } from 'node:events';
 import type { Server as HttpServer } from 'node:http';
 import type { Server as HttpsServer } from 'node:https';
@@ -8,231 +7,276 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { logger } from '@react-native-harness/tools';
 import { BinaryStore, parseBinaryFrame } from './binary-transfer.js';
+import { deserialize, serialize } from './serializer.js';
+import { DeviceNotRespondingError } from './errors.js';
+import { matchImageSnapshot } from './image-snapshot.js';
 import type {
   BridgeServerFunctions,
   BridgeClientFunctions,
   DeviceDescriptor,
   BridgeEvents,
-  ImageSnapshotOptions,
-  HarnessContext,
   BinaryDataReference,
   FileReference,
+  HarnessContext,
+  TestExecutionOptions,
+  TestSuiteResult,
 } from './shared.js';
-import { deserialize, serialize } from './serializer.js';
-import { DeviceNotRespondingError } from './errors.js';
-import { matchImageSnapshot } from './image-snapshot.js';
 
 export { DeviceNotRespondingError } from './errors.js';
+
 const bridgeLogger = logger.child('bridge');
 
-type BridgeServerStandaloneOptions = {
-  port: number;
-  host?: string;
-};
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
 
-type BridgeServerAttachedOptions = {
-  server: HttpServer | HttpsServer;
-  path?: string;
+/**
+ * Represents a single app session — one app launch to the next restart.
+ * Obtained via HarnessBridge.nextConnection().
+ */
+export type AppConnection = {
+  readonly device: DeviceDescriptor;
+  runTests: (path: string, options: TestExecutionOptions) => Promise<TestSuiteResult>;
 };
 
-type BridgeServerNoServerOptions = {
-  noServer: true;
+export type HarnessBridgeEvents = {
+  /** Fired when the app connects and calls reportReady. */
+  connected: (connection: AppConnection) => void;
+  /** Fired when the app's WebSocket closes. */
+  disconnected: () => void;
+  /** Fired for every test/bundler event the app emits. */
+  event: (event: BridgeEvents) => void;
 };
 
-export type BridgeServerOptions = (
-  | BridgeServerStandaloneOptions
-  | BridgeServerAttachedOptions
-  | BridgeServerNoServerOptions
-) & {
+type TransportOptions =
+  | { noServer: true }
+  | { port: number; host?: string }
+  | { server: HttpServer | HttpsServer; path?: string };
+
+export type HarnessBridgeOptions = TransportOptions & {
   timeout?: number;
   context: HarnessContext;
 };
 
-export type BridgeServerEvents = {
-  ready: (device: DeviceDescriptor) => void;
-  event: (event: BridgeEvents) => void;
-  disconnect: () => void;
-};
-
-export type BridgeServer = {
-  ws: WebSocketServer;
-  rpc: BirpcGroup<BridgeClientFunctions, BridgeServerFunctions>;
-  on: <T extends keyof BridgeServerEvents>(
-    event: T,
-    listener: BridgeServerEvents[T]
-  ) => void;
-  once: <T extends keyof BridgeServerEvents>(
-    event: T,
-    listener: BridgeServerEvents[T]
-  ) => void;
-  off: <T extends keyof BridgeServerEvents>(
-    event: T,
-    listener: BridgeServerEvents[T]
-  ) => void;
+/**
+ * The persistent CLI-side bridge. Spans the full test run regardless of how
+ * many times the app is restarted. Each restart produces a new AppConnection
+ * via nextConnection().
+ */
+export type HarnessBridge = {
+  /** The underlying WebSocket server, used to attach to Metro's HTTP server. */
+  readonly ws: WebSocketServer;
+  /** The currently active app connection, null if the app is not connected. */
+  readonly connection: AppConnection | null;
+  /**
+   * Resolves with the next AppConnection once the app connects and reports
+   * ready. Register this waiter before restarting the app so no ready signal
+   * is missed. Rejects if the supplied signal is aborted.
+   */
+  nextConnection: (signal?: AbortSignal) => Promise<AppConnection>;
+  on: <T extends keyof HarnessBridgeEvents>(event: T, listener: HarnessBridgeEvents[T]) => void;
+  off: <T extends keyof HarnessBridgeEvents>(event: T, listener: HarnessBridgeEvents[T]) => void;
   dispose: () => void;
 };
 
-export const getBridgeServer = async ({
-  timeout,
-  context,
-  ...transport
-}: BridgeServerOptions): Promise<BridgeServer> => {
-  const wss =
-    'port' in transport
-      ? await new Promise<WebSocketServer>((resolve) => {
-          const server = new WebSocketServer(
-            {
-              port: transport.port,
-              host: transport.host ?? '0.0.0.0',
-            },
-            () => {
-              resolve(server);
-            }
-          );
-        })
-      : new WebSocketServer(
-          'server' in transport
-            ? {
-                server: transport.server,
-                path: transport.path,
-              }
-            : {
-                noServer: true,
-              }
-        );
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const createWss = (transport: TransportOptions): Promise<WebSocketServer> => {
   if ('port' in transport) {
-    bridgeLogger.debug('bridge server listening on port %d', transport.port);
-  } else if ('server' in transport) {
-    bridgeLogger.debug(
-      'bridge server attached to existing HTTP server at path %s',
-      transport.path ?? '/'
+    return new Promise<WebSocketServer>((resolve) => {
+      const wss: WebSocketServer = new WebSocketServer(
+        { port: transport.port, host: transport.host ?? '0.0.0.0' },
+        () => resolve(wss),
+      );
+    });
+  }
+  return Promise.resolve<WebSocketServer>(
+    new WebSocketServer(
+      'server' in transport
+        ? { server: transport.server, path: transport.path }
+        : { noServer: true },
+    ),
+  );
+};
+
+const receiveScreenshot = async (
+  binaryStore: BinaryStore,
+  reference: BinaryDataReference,
+): Promise<FileReference> => {
+  const data = binaryStore.get(reference.transferId);
+  if (!data) {
+    throw new Error(
+      `Binary data for transfer ${reference.transferId} not found or expired`,
     );
-  } else {
-    bridgeLogger.debug('bridge server created in noServer mode');
   }
-  const emitter = new EventEmitter();
-  const clients = new Set<WebSocket>();
-  const binaryStore = new BinaryStore();
+  binaryStore.delete(reference.transferId);
+  const file = path.join(os.tmpdir(), `harness-screenshot-${randomUUID()}.png`);
+  await fs.writeFile(file, data);
+  return { path: file };
+};
 
-  const baseFunctions: BridgeServerFunctions = {
-    reportReady: (device) => {
-      emitter.emit('ready', device);
-    },
-    emitEvent: (_, data) => {
-      emitter.emit('event', data);
-    },
-    'device.screenshot.receive': async (
-      reference: BinaryDataReference,
-      metadata: { width: number; height: number }
-    ) => {
-      const data = binaryStore.get(reference.transferId);
-      if (!data) {
-        throw new Error(
-          `Binary data for transfer ${reference.transferId} not found or expired`
-        );
-      }
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
 
-      // Clean up from store
-      binaryStore.delete(reference.transferId);
+export const createHarnessBridge = async (
+  options: HarnessBridgeOptions,
+): Promise<HarnessBridge> => {
+  const { timeout, context, ...transport } = options;
+  const wss = await createWss(transport);
+  bridgeLogger.debug('bridge server ready');
 
-      // Write to temp file
-      const tempFile = path.join(
-        os.tmpdir(),
-        `harness-screenshot-${randomUUID()}.png`
-      );
-      await fs.writeFile(tempFile, data);
+  const emitter = new EventEmitter();
+  let currentConnection: AppConnection | null = null;
+  const connectionWaiters: Array<{
+    resolve: (c: AppConnection) => void;
+    reject: (e: unknown) => void;
+  }> = [];
 
-      return {
-        path: tempFile,
-        width: metadata.width,
-        height: metadata.height,
-      };
-    },
-    'test.matchImageSnapshot': async (
-      screenshot: FileReference,
-      testPath: string,
-      options: ImageSnapshotOptions
-    ) => {
-      return await matchImageSnapshot(
-        screenshot,
-        testPath,
-        options,
-        context.platform.name
-      );
-    },
-  };
+  wss.on('connection', (ws: WebSocket) => {
+    bridgeLogger.debug('app connected');
+    const binaryStore = new BinaryStore();
+    let readyConnection: AppConnection | null = null;
+    let disconnected = false;
 
-  const group = createBirpcGroup<BridgeClientFunctions, BridgeServerFunctions>(
-    baseFunctions,
-    [],
-    {
-      timeout,
-      onFunctionError: (error, functionName, args) => {
-        bridgeLogger.error('rpc function failed: %s args=%o', functionName, args);
-        bridgeLogger.error(error);
-        throw error;
+    const serverFunctions: BridgeServerFunctions = {
+      reportReady: (device) => {
+        const conn: AppConnection = {
+          device,
+          runTests: (testPath, opts) => rpc.runTests(testPath, opts),
+        };
+        readyConnection = conn;
+        currentConnection = conn;
+        bridgeLogger.debug(
+          'app ready: platform=%s model=%s',
+          device.platform,
+          device.model,
+        );
+        emitter.emit('connected', conn);
+        for (const { resolve } of connectionWaiters.splice(0)) resolve(conn);
       },
-      onTimeoutError(functionName, args) {
-        throw new DeviceNotRespondingError(functionName, args);
+      emitEvent: (_, data) => {
+        emitter.emit('event', data);
       },
-    }
-  );
+      'device.screenshot.receive': (ref) => receiveScreenshot(binaryStore, ref),
+      'test.matchImageSnapshot': (screenshot, testPath, opts) =>
+        matchImageSnapshot(screenshot, testPath, opts, context.platform.name),
+    };
 
-  wss.on('connection', (ws: WebSocket) => {
-    bridgeLogger.debug('client connected');
-    ws.on('close', () => {
-      bridgeLogger.debug('client disconnected');
-
-      // TODO: Remove channel when connection is closed.
-      clients.delete(ws);
-      emitter.emit('disconnect');
-    });
-
-    group.updateChannels((channels) => {
-      channels.push({
+    const rpc: BirpcReturn<BridgeClientFunctions, BridgeServerFunctions> = createBirpc<BridgeClientFunctions, BridgeServerFunctions>(
+      serverFunctions,
+      {
         post: (data) => ws.send(data),
         on: (handler) => {
           ws.on(
             'message',
-            (event: Buffer | ArrayBuffer | Buffer[], isBinary: boolean) => {
+            (msg: Buffer | ArrayBuffer | Buffer[], isBinary: boolean) => {
               if (isBinary) {
-                const uint8Array = new Uint8Array(event as any);
                 try {
-                  const { transferId, data } = parseBinaryFrame(uint8Array);
+                  const messageBuffer = Array.isArray(msg)
+                    ? Buffer.concat(msg)
+                    : Buffer.isBuffer(msg)
+                      ? msg
+                      : Buffer.from(msg);
+                  const { transferId, data } = parseBinaryFrame(
+                    new Uint8Array(messageBuffer),
+                  );
                   binaryStore.add(transferId, data);
-                  return;
-                } catch (error) {
-                  bridgeLogger.warn('failed to parse binary frame', error);
+                } catch (err) {
+                  bridgeLogger.warn('failed to parse binary frame: %s', err);
                 }
+              } else {
+                handler(msg.toString());
               }
-              const message = event.toString();
-              handler(message);
-            }
+            },
           );
         },
         serialize,
         deserialize,
-      });
+        timeout,
+        onFunctionError: (error, functionName, args) => {
+          bridgeLogger.error(
+            'rpc function failed: %s args=%o',
+            functionName,
+            args,
+          );
+          throw error;
+        },
+        onTimeoutError: (fn, args) => {
+          throw new DeviceNotRespondingError(fn, args);
+        },
+      },
+    );
+
+    const disconnect = (reason?: Error) => {
+      if (disconnected) return;
+      disconnected = true;
+
+      bridgeLogger.debug('app disconnected');
+      binaryStore.dispose();
+      if (currentConnection === readyConnection) {
+        currentConnection = null;
+      }
+      rpc.$close(reason ?? new Error('App bridge disconnected'));
+      emitter.emit('disconnected');
+    };
+
+    ws.on('close', () => {
+      disconnect();
     });
-  });
 
-  const dispose = () => {
-    bridgeLogger.debug('disposing bridge server');
-    for (const client of wss.clients) {
-      client.terminate();
-    }
-    wss.close();
-    emitter.removeAllListeners();
-    binaryStore.dispose();
-  };
+    ws.on('error', (error) => {
+      disconnect(error instanceof Error ? error : new Error('App bridge socket error'));
+    });
+  });
 
   return {
-    ws: wss,
-    rpc: group,
-    on: emitter.on.bind(emitter),
-    once: emitter.once.bind(emitter),
-    off: emitter.off.bind(emitter),
-    dispose,
+    get ws() {
+      return wss;
+    },
+    get connection() {
+      return currentConnection;
+    },
+    nextConnection: (signal) => {
+      if (signal?.aborted) {
+        return Promise.reject(
+          signal.reason ?? new DOMException('Aborted', 'AbortError'),
+        );
+      }
+      // If the app already connected before this call (e.g. fast simulator
+      // startup between startAttempt and waitForReady), return it immediately
+      // rather than waiting for a second reportReady that will never come.
+      if (currentConnection) {
+        return Promise.resolve(currentConnection);
+      }
+      return new Promise((resolve, reject) => {
+        const entry = { resolve, reject };
+        connectionWaiters.push(entry);
+        signal?.addEventListener(
+          'abort',
+          () => {
+            const idx = connectionWaiters.indexOf(entry);
+            if (idx !== -1) connectionWaiters.splice(idx, 1);
+            reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
+          },
+          { once: true },
+        );
+      });
+    },
+    on: (event, listener) => emitter.on(event, listener),
+    off: (event, listener) => emitter.off(event, listener),
+    dispose: () => {
+      bridgeLogger.debug('disposing bridge');
+      for (const { reject } of connectionWaiters.splice(0)) {
+        reject(new Error('Bridge disposed'));
+      }
+      for (const client of wss.clients) client.terminate();
+      wss.close();
+      emitter.removeAllListeners();
+    },
   };
 };

package/src/shared/test-collector.ts

@@ -1,6 +1,10 @@
+import type { HarnessTestContext } from './test-context.js';
+
 export type TestStatus = 'active' | 'skipped' | 'todo';
 
-export type TestFn = () => void | Promise<void>;
+export type TestFn = (context: HarnessTestContext) => void | Promise<void>;
+
+export type SuiteHookFn = () => void | Promise<void>;
 
 export type TestCase = {
   name: string;
@@ -13,8 +17,8 @@ export type TestSuite = {
   tests: TestCase[];
   suites: TestSuite[];
   parent?: TestSuite;
-  beforeAll: TestFn[];
-  afterAll: TestFn[];
+  beforeAll: SuiteHookFn[];
+  afterAll: SuiteHookFn[];
   beforeEach: TestFn[];
   afterEach: TestFn[];
   status?: TestStatus;

package/src/shared/test-context.ts

@@ -0,0 +1,21 @@
+export type HarnessTaskContext = {
+  name: string;
+  type: 'test';
+  mode: 'run' | 'skip' | 'todo';
+  file: {
+    name: string;
+  };
+  suite: {
+    name: string;
+  };
+};
+
+export type HarnessTestContext = {
+  task: HarnessTaskContext;
+  onTestFailed: (fn: () => void | Promise<void>) => void;
+  onTestFinished: (fn: () => void | Promise<void>) => void;
+  skip: {
+    (note?: string): never;
+    (condition: boolean, note?: string): void;
+  };
+};

package/src/shared.ts

@@ -81,7 +81,13 @@ export type {
   TestSuite,
   TestCase,
   CollectionResult,
+  TestFn,
+  SuiteHookFn,
 } from './shared/test-collector.js';
+export type {
+  HarnessTaskContext,
+  HarnessTestContext,
+} from './shared/test-context.js';
 export type {
   TestRunnerEvents,
   TestRunnerFileStartedEvent,
@@ -149,10 +155,7 @@ export type ScreenshotData = BinaryDataReference;
 
 export type BridgeServerFunctions = {
   reportReady: (device: DeviceDescriptor) => void;
-  emitEvent: <TEvent extends BridgeEvents>(
-    event: TEvent['type'],
-    data: TEvent
-  ) => void;
+  emitEvent: (event: BridgeEvents['type'], data: BridgeEvents) => void;
   'device.screenshot.receive': (
     reference: BinaryDataReference,
     metadata: { width: number; height: number }