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

package/dist/binary-transfer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"binary-transfer.d.ts","sourceRoot":"","sources":["../src/binary-transfer.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,IAAI,CAAC;AAE7B,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,UAAU,GACf,UAAU,CAcZ;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,UAAU,CAAC;CAClB,CAMA;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,QAAQ,CAA0B;IAE1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;IAE5C,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI;IAS/C,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI/C,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IASnC,OAAO,IAAI,IAAI;CAOhB;AAGD,wBAAgB,kBAAkB,IAAI,MAAM,CAQ3C"}
+{"version":3,"file":"binary-transfer.d.ts","sourceRoot":"","sources":["../src/binary-transfer.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,IAAI,CAAC;AAE7B,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,UAAU,GACf,UAAU,CAcZ;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,UAAU,CAAC;CAClB,CAMA;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,QAAQ,CAAoD;IAEpE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;IAE5C,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI;IAS/C,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI/C,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IASnC,OAAO,IAAI,IAAI;CAOhB;AAGD,wBAAgB,kBAAkB,IAAI,MAAM,CAQ3C"}

package/dist/client.d.ts

@@ -1,10 +1,32 @@
-import { BirpcReturn } from 'birpc';
-import type { BridgeClientFunctions, BridgeServerFunctions } from './shared.js';
-export type BridgeClient = {
-    rpc: BirpcReturn<BridgeServerFunctions, BridgeClientFunctions>;
+import type { DeviceDescriptor, BridgeEvents, FileReference, ImageSnapshotOptions, TestExecutionOptions, TestSuiteResult } from './shared.js';
+/** Handlers the app must implement for the CLI to call into. */
+export type HarnessCallbacks = {
+    runTests: (path: string, options: TestExecutionOptions) => Promise<TestSuiteResult>;
+};
+/** The app-side handle returned by connectToHarness. */
+export type HarnessHandle = {
+    /** Call once when the app is initialised and ready to run tests. */
+    reportReady: (device: DeviceDescriptor) => void;
+    /** Forward a test or bundler event to the CLI. */
+    emitEvent: (event: BridgeEvents) => void;
+    /** Send a screenshot to the CLI and receive a file reference for snapshot comparison. */
+    transferScreenshot: (data: Uint8Array, metadata: {
+        width: number;
+        height: number;
+    }) => Promise<FileReference>;
+    /** Request an image snapshot comparison on the CLI. */
+    matchImageSnapshot: (screenshot: FileReference, testPath: string, options: ImageSnapshotOptions, runner: string) => Promise<{
+        pass: boolean;
+        message: string;
+    }>;
     disconnect: () => void;
-    sendBinary: (transferId: number, data: Uint8Array) => void;
 };
-declare const getBridgeClient: (url: string, handlers: BridgeClientFunctions) => Promise<BridgeClient>;
-export { getBridgeClient };
+/**
+ * Connect the app to the CLI harness bridge.
+ *
+ * Pass the handlers the CLI can call (runTests). Returns a HarnessHandle
+ * exposing the operations the app needs to drive a test run. The binary
+ * transfer protocol and RPC wiring are fully encapsulated.
+ */
+export declare const connectToHarness: (url: string, callbacks: HarnessCallbacks) => Promise<HarnessHandle>;
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAe,MAAM,OAAO,CAAC;AACjD,OAAO,KAAK,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAIhF,MAAM,MAAM,YAAY,GAAG;IACzB,GAAG,EAAE,WAAW,CAAC,qBAAqB,EAAE,qBAAqB,CAAC,CAAC;IAC/D,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,UAAU,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;CAC5D,CAAC;AAEF,QAAA,MAAM,eAAe,GACnB,KAAK,MAAM,EACX,UAAU,qBAAqB,KAC9B,OAAO,CAAC,YAAY,CA6EtB,CAAC;AAEF,OAAO,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAGV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,eAAe,EAChB,MAAM,aAAa,CAAC;AAMrB,gEAAgE;AAChE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;CACrF,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,aAAa,GAAG;IAC1B,oEAAoE;IACpE,WAAW,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAChD,kDAAkD;IAClD,SAAS,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IACzC,yFAAyF;IACzF,kBAAkB,EAAE,CAClB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KACxC,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5B,uDAAuD;IACvD,kBAAkB,EAAE,CAClB,UAAU,EAAE,aAAa,EACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,oBAAoB,EAC7B,MAAM,EAAE,MAAM,KACX,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB,CAAC;AAMF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC3B,KAAK,MAAM,EACX,WAAW,gBAAgB,KAC1B,OAAO,CAAC,aAAa,CAyEpB,CAAC"}

package/dist/client.js

@@ -1,63 +1,68 @@
 import { createBirpc } from 'birpc';
 import { deserialize, serialize } from './serializer.js';
-import { createBinaryFrame } from './binary-transfer.js';
-const getBridgeClient = async (url, handlers) => {
-    return new Promise((resolve, reject) => {
-        const ws = new WebSocket(url);
-        ws.binaryType = 'arraybuffer';
-        let settled = false;
-        const cleanup = () => {
-            ws.removeEventListener('open', handleOpen);
-            ws.removeEventListener('error', handleError);
-            ws.removeEventListener('close', handleClose);
-        };
-        const rejectConnection = (message) => {
-            if (settled) {
-                return;
-            }
-            settled = true;
-            cleanup();
-            reject(new Error(message));
-        };
-        const handleOpen = () => {
-            settled = true;
-            cleanup();
-            const rpc = createBirpc(handlers, {
-                post: (data) => ws.send(data),
-                on: (handler) => {
-                    ws.addEventListener('message', (event) => {
-                        if (typeof event.data === 'string') {
-                            handler(event.data);
-                        }
-                    });
-                },
-                serialize,
-                deserialize,
-            });
-            const client = {
-                rpc,
-                disconnect: () => {
-                    ws.close();
-                },
-                sendBinary: (transferId, data) => {
-                    const frame = createBinaryFrame(transferId, data);
-                    ws.send(frame);
-                },
-            };
-            resolve(client);
-        };
-        const handleError = (event) => {
-            const reason = typeof event.message === 'string' && event.message.length > 0
-                ? `: ${event.message}`
-                : '';
-            rejectConnection(`Failed to connect to the Harness bridge at ${url}${reason}`);
-        };
-        const handleClose = (event) => {
-            rejectConnection(`Harness bridge connection to ${url} closed before it became ready (code ${event.code}${event.reason ? `, reason: ${event.reason}` : ''})`);
-        };
-        ws.addEventListener('open', handleOpen);
-        ws.addEventListener('error', handleError);
-        ws.addEventListener('close', handleClose);
-    });
-};
-export { getBridgeClient };
+import { createBinaryFrame, generateTransferId } from './binary-transfer.js';
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Connect the app to the CLI harness bridge.
+ *
+ * Pass the handlers the CLI can call (runTests). Returns a HarnessHandle
+ * exposing the operations the app needs to drive a test run. The binary
+ * transfer protocol and RPC wiring are fully encapsulated.
+ */
+export const connectToHarness = (url, callbacks) => new Promise((resolve, reject) => {
+    const ws = new WebSocket(url);
+    ws.binaryType = 'arraybuffer';
+    let settled = false;
+    const cleanup = () => {
+        ws.removeEventListener('open', handleOpen);
+        ws.removeEventListener('error', handleError);
+        ws.removeEventListener('close', handleClose);
+    };
+    const fail = (message) => {
+        if (settled)
+            return;
+        settled = true;
+        cleanup();
+        reject(new Error(message));
+    };
+    const handleOpen = () => {
+        settled = true;
+        cleanup();
+        const rpc = createBirpc(callbacks, {
+            post: (data) => ws.send(data),
+            on: (handler) => {
+                ws.addEventListener('message', (event) => {
+                    if (typeof event.data === 'string')
+                        handler(event.data);
+                });
+            },
+            serialize,
+            deserialize,
+        });
+        resolve({
+            reportReady: (device) => void rpc.reportReady(device),
+            emitEvent: (event) => void rpc.emitEvent(event.type, event),
+            transferScreenshot: async (data, metadata) => {
+                const transferId = generateTransferId();
+                ws.send(createBinaryFrame(transferId, data));
+                return rpc['device.screenshot.receive']({ type: 'binary', transferId, size: data.length, mimeType: 'image/png' }, metadata);
+            },
+            matchImageSnapshot: (screenshot, testPath, options, runner) => rpc['test.matchImageSnapshot'](screenshot, testPath, options, runner),
+            disconnect: () => ws.close(),
+        });
+    };
+    const handleError = (event) => {
+        const detail = typeof event.message === 'string' && event.message
+            ? `: ${event.message}`
+            : '';
+        fail(`Failed to connect to Harness at ${url}${detail}`);
+    };
+    const handleClose = (event) => {
+        fail(`Harness connection at ${url} closed before becoming ready (code ${event.code}${event.reason ? `, reason: ${event.reason}` : ''})`);
+    };
+    ws.addEventListener('open', handleOpen);
+    ws.addEventListener('error', handleError);
+    ws.addEventListener('close', handleClose);
+});

package/dist/server.d.ts

@@ -1,36 +1,56 @@
 import { WebSocketServer } from 'ws';
-import { type BirpcGroup } from 'birpc';
 import type { Server as HttpServer } from 'node:http';
 import type { Server as HttpsServer } from 'node:https';
-import type { BridgeServerFunctions, BridgeClientFunctions, DeviceDescriptor, BridgeEvents, HarnessContext } from './shared.js';
+import type { DeviceDescriptor, BridgeEvents, HarnessContext, TestExecutionOptions, TestSuiteResult } from './shared.js';
 export { DeviceNotRespondingError } from './errors.js';
-type BridgeServerStandaloneOptions = {
+/**
+ * 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>;
+};
+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;
+};
+type TransportOptions = {
+    noServer: true;
+} | {
     port: number;
     host?: string;
-};
-type BridgeServerAttachedOptions = {
+} | {
     server: HttpServer | HttpsServer;
     path?: string;
 };
-type BridgeServerNoServerOptions = {
-    noServer: true;
-};
-export type BridgeServerOptions = (BridgeServerStandaloneOptions | BridgeServerAttachedOptions | BridgeServerNoServerOptions) & {
+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 declare const getBridgeServer: ({ timeout, context, ...transport }: BridgeServerOptions) => Promise<BridgeServer>;
+export declare const createHarnessBridge: (options: HarnessBridgeOptions) => Promise<HarnessBridge>;
 //# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAkB,MAAM,IAAI,CAAC;AACrD,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,OAAO,CAAC;AAG1D,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,YAAY,CAAC;AAMxD,OAAO,KAAK,EACV,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,YAAY,EAEZ,cAAc,EAGf,MAAM,aAAa,CAAC;AAKrB,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAGvD,KAAK,6BAA6B,GAAG;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,KAAK,2BAA2B,GAAG;IACjC,MAAM,EAAE,UAAU,GAAG,WAAW,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,KAAK,2BAA2B,GAAG;IACjC,QAAQ,EAAE,IAAI,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,CAC9B,6BAA6B,GAC7B,2BAA2B,GAC3B,2BAA2B,CAC9B,GAAG;IACF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,cAAc,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC1C,KAAK,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IACrC,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,eAAe,CAAC;IACpB,GAAG,EAAE,UAAU,CAAC,qBAAqB,EAAE,qBAAqB,CAAC,CAAC;IAC9D,EAAE,EAAE,CAAC,CAAC,SAAS,MAAM,kBAAkB,EACrC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC,KAC5B,IAAI,CAAC;IACV,IAAI,EAAE,CAAC,CAAC,SAAS,MAAM,kBAAkB,EACvC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC,KAC5B,IAAI,CAAC;IACV,GAAG,EAAE,CAAC,CAAC,SAAS,MAAM,kBAAkB,EACtC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC,KAC5B,IAAI,CAAC;IACV,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,eAAe,GAAU,oCAInC,mBAAmB,KAAG,OAAO,CAAC,YAAY,CA8J5C,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAkB,MAAM,IAAI,CAAC;AAGrD,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,YAAY,CAAC;AAUxD,OAAO,KAAK,EAGV,gBAAgB,EAChB,YAAY,EAGZ,cAAc,EACd,oBAAoB,EACpB,eAAe,EAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAQvD;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;CACrF,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,yDAAyD;IACzD,SAAS,EAAE,CAAC,UAAU,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/C,6CAA6C;IAC7C,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,wDAAwD;IACxD,KAAK,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;CACtC,CAAC;AAEF,KAAK,gBAAgB,GACjB;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,MAAM,EAAE,UAAU,GAAG,WAAW,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,GAAG;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,cAAc,CAAC;CACzB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAC;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,aAAa,GAAG,IAAI,CAAC;IAC1C;;;;OAIG;IACH,cAAc,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IACjE,EAAE,EAAE,CAAC,CAAC,SAAS,MAAM,mBAAmB,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,mBAAmB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC9F,GAAG,EAAE,CAAC,CAAC,SAAS,MAAM,mBAAmB,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,mBAAmB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC/F,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AA4CF,eAAO,MAAM,mBAAmB,GAC9B,SAAS,oBAAoB,KAC5B,OAAO,CAAC,aAAa,CA0JvB,CAAC"}

package/dist/server.js

@@ -1,133 +1,166 @@
 import { WebSocketServer } from 'ws';
-import { createBirpcGroup } from 'birpc';
-import { logger } from '@react-native-harness/tools';
+import { createBirpc } from 'birpc';
 import { EventEmitter } from 'node:events';
 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';
 export { DeviceNotRespondingError } from './errors.js';
 const bridgeLogger = logger.child('bridge');
-export const getBridgeServer = async ({ timeout, context, ...transport }) => {
-    const wss = 'port' in transport
-        ? await new Promise((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) => {
     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((resolve) => {
+            const wss = new WebSocketServer({ port: transport.port, host: transport.host ?? '0.0.0.0' }, () => resolve(wss));
+        });
     }
-    else {
-        bridgeLogger.debug('bridge server created in noServer mode');
+    return Promise.resolve(new WebSocketServer('server' in transport
+        ? { server: transport.server, path: transport.path }
+        : { noServer: true }));
+};
+const receiveScreenshot = async (binaryStore, reference) => {
+    const data = binaryStore.get(reference.transferId);
+    if (!data) {
+        throw new Error(`Binary data for transfer ${reference.transferId} not found or expired`);
     }
+    binaryStore.delete(reference.transferId);
+    const file = path.join(os.tmpdir(), `harness-screenshot-${randomUUID()}.png`);
+    await fs.writeFile(file, data);
+    return { path: file };
+};
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+export const createHarnessBridge = async (options) => {
+    const { timeout, context, ...transport } = options;
+    const wss = await createWss(transport);
+    bridgeLogger.debug('bridge server ready');
     const emitter = new EventEmitter();
-    const clients = new Set();
-    const binaryStore = new BinaryStore();
-    const baseFunctions = {
-        reportReady: (device) => {
-            emitter.emit('ready', device);
-        },
-        emitEvent: (_, data) => {
-            emitter.emit('event', data);
-        },
-        'device.screenshot.receive': async (reference, metadata) => {
-            const data = binaryStore.get(reference.transferId);
-            if (!data) {
-                throw new Error(`Binary data for transfer ${reference.transferId} not found or expired`);
-            }
-            // Clean up from store
-            binaryStore.delete(reference.transferId);
-            // Write to temp file
-            const tempFile = path.join(os.tmpdir(), `harness-screenshot-${randomUUID()}.png`);
-            await fs.writeFile(tempFile, data);
-            return {
-                path: tempFile,
-                width: metadata.width,
-                height: metadata.height,
-            };
-        },
-        'test.matchImageSnapshot': async (screenshot, testPath, options) => {
-            return await matchImageSnapshot(screenshot, testPath, options, context.platform.name);
-        },
-    };
-    const group = createBirpcGroup(baseFunctions, [], {
-        timeout,
-        onFunctionError: (error, functionName, args) => {
-            bridgeLogger.error('rpc function failed: %s args=%o', functionName, args);
-            bridgeLogger.error(error);
-            throw error;
-        },
-        onTimeoutError(functionName, args) {
-            throw new DeviceNotRespondingError(functionName, args);
-        },
-    });
+    let currentConnection = null;
+    const connectionWaiters = [];
     wss.on('connection', (ws) => {
-        bridgeLogger.debug('client connected');
+        bridgeLogger.debug('app connected');
+        const binaryStore = new BinaryStore();
+        let readyConnection = null;
+        let disconnected = false;
+        const serverFunctions = {
+            reportReady: (device) => {
+                const conn = {
+                    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);
+            },
+            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),
+        };
+        const rpc = createBirpc(serverFunctions, {
+            post: (data) => ws.send(data),
+            on: (handler) => {
+                ws.on('message', (msg, isBinary) => {
+                    if (isBinary) {
+                        try {
+                            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);
+                        }
+                        catch (err) {
+                            bridgeLogger.warn('failed to parse binary frame: %s', err);
+                        }
+                    }
+                    else {
+                        handler(msg.toString());
+                    }
+                });
+            },
+            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) => {
+            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', () => {
-            bridgeLogger.debug('client disconnected');
-            // TODO: Remove channel when connection is closed.
-            clients.delete(ws);
-            emitter.emit('disconnect');
+            disconnect();
         });
-        group.updateChannels((channels) => {
-            channels.push({
-                post: (data) => ws.send(data),
-                on: (handler) => {
-                    ws.on('message', (event, isBinary) => {
-                        if (isBinary) {
-                            const uint8Array = new Uint8Array(event);
-                            try {
-                                const { transferId, data } = parseBinaryFrame(uint8Array);
-                                binaryStore.add(transferId, data);
-                                return;
-                            }
-                            catch (error) {
-                                bridgeLogger.warn('failed to parse binary frame', error);
-                            }
-                        }
-                        const message = event.toString();
-                        handler(message);
-                    });
-                },
-                serialize,
-                deserialize,
-            });
+        ws.on('error', (error) => {
+            disconnect(error instanceof Error ? error : new Error('App bridge socket error'));
         });
     });
-    const dispose = () => {
-        bridgeLogger.debug('disposing bridge server');
-        for (const client of wss.clients) {
-            client.terminate();
-        }
-        wss.close();
-        emitter.removeAllListeners();
-        binaryStore.dispose();
-    };
     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/dist/shared/test-collector.d.ts

@@ -1,5 +1,7 @@
+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;
     fn: TestFn;
@@ -10,8 +12,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/dist/shared/test-collector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-collector.d.ts","sourceRoot":"","sources":["../../src/shared/test-collector.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAEvD,MAAM,MAAM,MAAM,GAAG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEhD,MAAM,MAAM,QAAQ,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,EAAE,SAAS,CAAC;IACrB,uFAAuF;IACvF,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAC3B,0BAA0B,GAC1B,2BAA2B,CAAC"}
+{"version":3,"file":"test-collector.d.ts","sourceRoot":"","sources":["../../src/shared/test-collector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAEvD,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE3E,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAErD,MAAM,MAAM,QAAQ,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,EAAE,SAAS,CAAC;IACrB,uFAAuF;IACvF,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAC3B,0BAA0B,GAC1B,2BAA2B,CAAC"}

package/dist/shared/test-context.d.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;
+    };
+};
+//# sourceMappingURL=test-context.d.ts.map

package/dist/shared/test-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-context.d.ts","sourceRoot":"","sources":["../../src/shared/test-context.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IAC9B,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,kBAAkB,CAAC;IACzB,YAAY,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;IACvD,cAAc,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;IACzD,IAAI,EAAE;QACJ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;QACvB,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC3C,CAAC;CACH,CAAC"}

package/dist/shared/test-context.js

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

package/dist/shared.d.ts

@@ -67,7 +67,8 @@ export type ImageSnapshotOptions = {
      */
     diffColorAlt?: [number, number, number];
 };
-export type { TestCollectorEvents, TestCollectionStartedEvent, TestCollectionFinishedEvent, TestSuite, TestCase, CollectionResult, } from './shared/test-collector.js';
+export type { TestCollectorEvents, TestCollectionStartedEvent, TestCollectionFinishedEvent, TestSuite, TestCase, CollectionResult, TestFn, SuiteHookFn, } from './shared/test-collector.js';
+export type { HarnessTaskContext, HarnessTestContext, } from './shared/test-context.js';
 export type { TestRunnerEvents, TestRunnerFileStartedEvent, TestRunnerFileFinishedEvent, TestRunnerSuiteStartedEvent, TestRunnerTestStartedEvent, TestRunnerTestFinishedEvent, TestRunnerSuiteFinishedEvent, TestSuiteResult, TestResult, TestResultStatus, SerializedError, CodeFrame, } from './shared/test-runner.js';
 export type { ModuleBundlingStartedEvent, ModuleBundlingFinishedEvent, ModuleBundlingFailedEvent, SetupFileBundlingStartedEvent, SetupFileBundlingFinishedEvent, SetupFileBundlingFailedEvent, BundlerEvents, } from './shared/bundler.js';
 export type DeviceDescriptor = {
@@ -100,7 +101,7 @@ export type BinaryDataReference = {
 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;