@react-native-harness/bridge 1.1.0 → 1.2.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/events.d.ts

@@ -0,0 +1,45 @@
+export type ExecutionStartedEvent = {
+    type: 'execution-started';
+    path: string;
+    numberOfTests: number;
+};
+export type ExecutionFinishedEvent = {
+    type: 'execution-finished';
+    path: string;
+    duration: number;
+};
+export type SuiteStartedEvent = {
+    type: 'suite-started';
+    path: string;
+    name: string;
+};
+export type SuiteFinishedEvent = {
+    type: 'suite-finished';
+    path: string;
+    name: string;
+    duration: number;
+    reason: 'passed' | 'failed' | 'skipped' | 'todo';
+};
+export type TestStartedEvent = {
+    type: 'test-started';
+    path: string;
+    suite: string;
+    name: string;
+};
+export type TestFinishedEvent = {
+    type: 'test-finished';
+    path: string;
+    suite: string;
+    name: string;
+    duration: number;
+    reason: 'passed' | 'failed' | 'skipped' | 'todo';
+};
+export type BridgeEvents = {
+    'execution-started': ExecutionStartedEvent;
+    'execution-finished': ExecutionFinishedEvent;
+    'suite-started': SuiteStartedEvent;
+    'suite-finished': SuiteFinishedEvent;
+    'test-started': TestStartedEvent;
+    'test-finished': TestFinishedEvent;
+};
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,eAAe,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,eAAe,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,mBAAmB,EAAE,qBAAqB,CAAC;IAC3C,oBAAoB,EAAE,sBAAsB,CAAC;IAC7C,eAAe,EAAE,iBAAiB,CAAC;IACnC,gBAAgB,EAAE,kBAAkB,CAAC;IACrC,cAAc,EAAE,gBAAgB,CAAC;IACjC,eAAe,EAAE,iBAAiB,CAAC;CACpC,CAAC"}

package/dist/events.js

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

package/dist/platform-bridge.d.ts

@@ -0,0 +1,4 @@
+import type { HarnessPlatformRunner } from '@react-native-harness/platforms';
+import type { BridgeServerFunctions } from './shared.js';
+export declare const createPlatformBridgeFunctions: (platformRunner: HarnessPlatformRunner) => Partial<BridgeServerFunctions>;
+//# sourceMappingURL=platform-bridge.d.ts.map

package/dist/platform-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-bridge.d.ts","sourceRoot":"","sources":["../src/platform-bridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,qBAAqB,EACtB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,eAAO,MAAM,6BAA6B,GACxC,gBAAgB,qBAAqB,KACpC,OAAO,CAAC,qBAAqB,CAwB/B,CAAC"}

package/dist/platform-bridge.js

@@ -0,0 +1,25 @@
+export const createPlatformBridgeFunctions = (platformRunner) => {
+    return {
+        'platform.actions.tap': async (x, y) => {
+            await platformRunner.actions.tap(x, y);
+        },
+        'platform.actions.inputText': async (text) => {
+            await platformRunner.actions.inputText(text);
+        },
+        'platform.actions.tapElement': async (element) => {
+            await platformRunner.actions.tapElement(element);
+        },
+        'platform.actions.screenshot': async () => {
+            return await platformRunner.actions.screenshot();
+        },
+        'platform.queries.getUiHierarchy': async () => {
+            return await platformRunner.queries.getUiHierarchy();
+        },
+        'platform.queries.findByTestId': async (testId) => {
+            return await platformRunner.queries.findByTestId(testId);
+        },
+        'platform.queries.findAllByTestId': async (testId) => {
+            return await platformRunner.queries.findAllByTestId(testId);
+        },
+    };
+};

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,CAyIvB,CAAC"}

package/dist/server.js

@@ -1,133 +1,151 @@
 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');
-        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({
-                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);
-                            }
+        bridgeLogger.debug('app connected');
+        const binaryStore = new BinaryStore();
+        const serverFunctions = {
+            reportReady: (device) => {
+                const conn = {
+                    device,
+                    runTests: (testPath, opts) => rpc.runTests(testPath, opts),
+                };
+                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);
                         }
-                        const message = event.toString();
-                        handler(message);
-                    });
-                },
-                serialize,
-                deserialize,
-            });
+                        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);
+            },
+        });
+        ws.on('close', () => {
+            bridgeLogger.debug('app disconnected');
+            binaryStore.dispose();
+            currentConnection = null;
+            emitter.emit('disconnected');
         });
     });
-    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();
+        },
     };
 };