@react-native-harness/bridge 1.3.0 → 1.4.0

package/src/__tests__/protocol.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import {
+  deserializeBridgeError,
+  parseBridgeMessage,
+  serializeBridgeError,
+  serializeBridgeMessage,
+} from '../protocol.js';
+
+describe('bridge protocol', () => {
+  it('round-trips invoke messages', () => {
+    const raw = serializeBridgeMessage({
+      type: 'invoke',
+      id: 1,
+      method: 'runTests',
+      args: ['example.ts', { runner: '/runner.js' }],
+    });
+
+    expect(parseBridgeMessage(raw)).toEqual({
+      type: 'invoke',
+      id: 1,
+      method: 'runTests',
+      args: ['example.ts', { runner: '/runner.js' }],
+    });
+  });
+
+  it('serializes and restores errors with metadata', () => {
+    const cause = new Error('inner');
+    const error = new TypeError('boom', { cause });
+    error.stack = 'stack trace';
+
+    const restored = deserializeBridgeError(serializeBridgeError(error));
+
+    expect(restored.name).toBe('TypeError');
+    expect(restored.message).toBe('boom');
+    expect(restored.stack).toBe('stack trace');
+    expect(restored.cause).toBe(cause);
+  });
+
+  it('serializes non-Error thrown values explicitly', () => {
+    expect(serializeBridgeError('boom')).toEqual({
+      name: 'NonErrorThrown',
+      message: 'boom',
+    });
+  });
+
+  it('rejects malformed messages', () => {
+    expect(() => parseBridgeMessage('{"type":"invoke","id":"1"}')).toThrow(
+      'Invalid bridge message: id must be a number',
+    );
+  });
+});

package/src/__tests__/rpc-peer.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createRpcPeer } from '../rpc-peer.js';
+import type { BridgeEvents } from '../shared.js';
+import type { RpcTransport } from '../transport.js';
+
+type LocalMethods = {
+  add: (left: number, right: number) => Promise<number>;
+  fail: () => Promise<never>;
+};
+
+const createMockTransport = (): RpcTransport & { messages: string[] } => {
+  const messages: string[] = [];
+
+  return {
+    state: 'open',
+    messages,
+    send: (message) => {
+      messages.push(message);
+    },
+  };
+};
+
+describe('rpc-peer', () => {
+  it('resolves successful RPC calls', async () => {
+    let serverHandleMessage: ((message: string) => Promise<unknown>) | null = null;
+
+    const client = createRpcPeer<Record<string, never>, { add: LocalMethods['add'] }, BridgeEvents>({
+      localMethods: {},
+      transport: {
+        state: 'open',
+        send: (message) => {
+          if (!serverHandleMessage) {
+            throw new Error('Server peer not initialized');
+          }
+
+          void serverHandleMessage(message);
+        },
+      },
+    });
+
+    const server = createRpcPeer<LocalMethods, Record<string, never>, BridgeEvents>({
+      localMethods: {
+        add: async (left, right) => left + right,
+        fail: async () => {
+          throw new Error('unused');
+        },
+      },
+      transport: {
+        state: 'open',
+        send: (message) => {
+          void client.handleMessage(message);
+        },
+      },
+    });
+
+    serverHandleMessage = server.handleMessage;
+
+    const result = await client.invoke('add', 2, 3);
+
+    expect(result).toBe(5);
+  });
+
+  it('rejects failed RPC calls with restored errors', async () => {
+    const client = createRpcPeer<Record<string, never>, { fail: () => Promise<void> }, BridgeEvents>({
+      localMethods: {},
+      transport: createMockTransport(),
+    });
+
+    const server = createRpcPeer<
+      { fail: () => Promise<void> },
+      Record<string, never>,
+      BridgeEvents
+    >({
+      localMethods: {
+        fail: async () => {
+          throw new TypeError('boom');
+        },
+      },
+      transport: {
+        state: 'open',
+        send: (message) => {
+          void client.handleMessage(message);
+        },
+      },
+    });
+
+    await server.handleMessage(
+      JSON.stringify({ type: 'invoke', id: 1, method: 'fail', args: [] }),
+    );
+
+    await expect(client.handleMessage('{"type":"return","id":1,"ok":false,"error":{"name":"TypeError","message":"boom"}}')).resolves.toBeNull();
+  });
+
+  it('rejects unknown methods', async () => {
+    let response = '';
+    const peer = createRpcPeer<Record<string, never>, Record<string, never>, BridgeEvents>({
+      localMethods: {},
+      transport: {
+        state: 'open',
+        send: (message) => {
+          response = message;
+        },
+      },
+    });
+
+    await peer.handleMessage(
+      JSON.stringify({ type: 'invoke', id: 1, method: 'missing', args: [] }),
+    );
+
+    expect(JSON.parse(response)).toMatchObject({
+      type: 'return',
+      id: 1,
+      ok: false,
+    });
+  });
+
+  it('dispatches incoming events', async () => {
+    const onEvent = vi.fn();
+    const peer = createRpcPeer<Record<string, never>, Record<string, never>, BridgeEvents>({
+      localMethods: {},
+      transport: createMockTransport(),
+      onEvent,
+    });
+
+    await peer.handleMessage(
+      JSON.stringify({
+        type: 'event',
+        event: { type: 'collection-started', file: 'example.ts' },
+      }),
+    );
+
+    expect(onEvent).toHaveBeenCalledWith({
+      type: 'collection-started',
+      file: 'example.ts',
+    });
+  });
+
+  it('rejects pending calls when closed', async () => {
+    const peer = createRpcPeer<
+      Record<string, never>,
+      { runTests: (path: string, options: { runner: string }) => Promise<void> },
+      BridgeEvents
+    >({
+      localMethods: {},
+      transport: createMockTransport(),
+    });
+
+    const pending = peer.invoke('runTests', 'example.ts', { runner: '/runner.js' });
+    peer.close(new Error('closed'));
+
+    await expect(pending).rejects.toThrow('closed');
+  });
+
+  it('rejects pending calls on timeout', async () => {
+    const peer = createRpcPeer<
+      Record<string, never>,
+      { runTests: (path: string, options: { runner: string }) => Promise<void> },
+      BridgeEvents
+    >({
+      localMethods: {},
+      transport: createMockTransport(),
+      callTimeoutMs: 10,
+      createTimeoutError: () => new Error('timed out'),
+    });
+
+    const pending = peer.invoke('runTests', 'example.ts', { runner: '/runner.js' });
+
+    await expect(pending).rejects.toThrow('timed out');
+  });
+
+  it('does not time out calls when method-specific timeout returns undefined', async () => {
+    const peer = createRpcPeer<
+      Record<string, never>,
+      { runTests: (path: string, options: { runner: string }) => Promise<void> },
+      BridgeEvents
+    >({
+      localMethods: {},
+      transport: createMockTransport(),
+      callTimeoutMs: () => undefined,
+      createTimeoutError: () => new Error('timed out'),
+    });
+
+    let rejected = false;
+    const pending = peer.invoke('runTests', 'example.ts', { runner: '/runner.js' });
+    pending.catch(() => {
+      rejected = true;
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    expect(rejected).toBe(false);
+    peer.close(new Error('closed'));
+    await expect(pending).rejects.toThrow('closed');
+  });
+
+  it('throws on malformed messages', async () => {
+    const peer = createRpcPeer<Record<string, never>, Record<string, never>, BridgeEvents>({
+      localMethods: {},
+      transport: createMockTransport(),
+    });
+
+    await expect(peer.handleMessage('{"type":"invoke"}')).rejects.toThrow(
+      'Invalid bridge message: id must be a number',
+    );
+  });
+});

package/src/client.ts

@@ -1,6 +1,11 @@
-import { createBirpc } from 'birpc';
-import { deserialize, serialize } from './serializer.js';
 import { createBinaryFrame, generateTransferId } from './binary-transfer.js';
+import { serializeBridgeMessage } from './protocol.js';
+import { createRpcPeer } from './rpc-peer.js';
+import {
+  createRpcTransport,
+  type BridgeTransport,
+} from './transport.js';
+import { createWebSocketClientTransport } from './websocket-client-transport.js';
 import type {
   BridgeClientFunctions,
   BridgeServerFunctions,
@@ -12,27 +17,18 @@ import type {
   TestSuiteResult,
 } from './shared.js';
 
-// ---------------------------------------------------------------------------
-// Public types
-// ---------------------------------------------------------------------------
-
-/** Handlers the app must implement for the CLI to call into. */
 export type HarnessCallbacks = {
   runTests: (path: string, options: TestExecutionOptions) => Promise<TestSuiteResult>;
+  resetEnvironment: () => Promise<void>;
 };
 
-/** 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,
@@ -42,83 +38,173 @@ export type HarnessHandle = {
   disconnect: () => void;
 };
 
-// ---------------------------------------------------------------------------
-// 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 type ConnectToHarnessOptions = {
+  transport?: BridgeTransport;
+};
+
+export { createWebSocketClientTransport };
+
+const noop = (): void => undefined;
+
 export const connectToHarness = (
   url: string,
   callbacks: HarnessCallbacks,
+  options: ConnectToHarnessOptions = {},
 ): Promise<HarnessHandle> =>
   new Promise((resolve, reject) => {
-    const ws = new WebSocket(url);
-    ws.binaryType = 'arraybuffer';
+    const transport = options.transport ?? createWebSocketClientTransport(url);
     let settled = false;
+    let peerClosed = false;
+    let offOpen: () => void = noop;
+    let offError: () => void = noop;
+    let offClose: () => void = noop;
 
     const cleanup = () => {
-      ws.removeEventListener('open', handleOpen);
-      ws.removeEventListener('error', handleError);
-      ws.removeEventListener('close', handleClose);
+      offOpen();
+      offError();
+      offClose();
     };
 
     const fail = (message: string) => {
-      if (settled) return;
+      if (settled) {
+        return;
+      }
+
       settled = true;
       cleanup();
       reject(new Error(message));
     };
 
     const handleOpen = () => {
+      if (settled) {
+        return;
+      }
+
       settled = true;
       cleanup();
 
-      const rpc = createBirpc<BridgeServerFunctions, BridgeClientFunctions>(
-        callbacks,
-        {
-          post: (data) => ws.send(data),
-          on: (handler) => {
-            ws.addEventListener('message', (event: MessageEvent<string | ArrayBuffer>) => {
-              if (typeof event.data === 'string') handler(event.data);
-            });
-          },
-          serialize,
-          deserialize,
-        },
-      );
+      const getTransportNotOpenError = () => {
+        return new Error('Harness bridge transport is not open');
+      };
+
+      const rpc = createRpcPeer<
+        BridgeClientFunctions,
+        BridgeServerFunctions,
+        BridgeEvents
+      >({
+        localMethods: callbacks,
+        transport: createRpcTransport(transport),
+      });
+
+      let offMessage: () => void = noop;
+      let offRuntimeClose: () => void = noop;
+      let offRuntimeError: () => void = noop;
+
+      const closePeer = (reason: Error) => {
+        if (peerClosed) {
+          return;
+        }
+
+        peerClosed = true;
+        offMessage();
+        offRuntimeClose();
+        offRuntimeError();
+        rpc.close(reason);
+      };
+
+      const handleMessage = async (data: string) => {
+        const controlMessage = await rpc.handleMessage(data);
+
+        if (!controlMessage) {
+          return;
+        }
+
+        if (controlMessage.type === 'ping') {
+          transport.send(
+            serializeBridgeMessage({ type: 'pong', id: controlMessage.id }),
+          );
+        }
+      };
+
+      offMessage = transport.onMessage((message) => {
+        if (typeof message !== 'string') {
+          return;
+        }
+
+        void handleMessage(message).catch((error) => {
+          closePeer(
+            error instanceof Error
+              ? error
+              : new Error('Received invalid Harness bridge message'),
+          );
+
+          if (transport.state === 'open') {
+            transport.close(1002, 'Invalid message');
+          }
+        });
+      });
+
+      offRuntimeClose = transport.onClose((event) => {
+        closePeer(
+          new Error(
+            `Harness connection closed (code ${event.code}${
+              event.reason ? `, reason: ${event.reason}` : ''
+            })`,
+          ),
+        );
+      });
+
+      offRuntimeError = transport.onError((error) => {
+        closePeer(error);
+      });
 
       resolve({
-        reportReady: (device) => void rpc.reportReady(device),
-        emitEvent: (event) => void rpc.emitEvent(event.type, event),
+        reportReady: (device) => {
+          try {
+            if (transport.state !== 'open') {
+              throw getTransportNotOpenError();
+            }
+
+            transport.send(serializeBridgeMessage({ type: 'ready', device }));
+          } catch (error) {
+            closePeer(
+              error instanceof Error ? error : getTransportNotOpenError(),
+            );
+          }
+        },
+        emitEvent: (event) => {
+          rpc.sendEvent(event);
+        },
         transferScreenshot: async (data, metadata) => {
           const transferId = generateTransferId();
-          ws.send(createBinaryFrame(transferId, data));
-          return rpc['device.screenshot.receive'](
+          transport.send(createBinaryFrame(transferId, data));
+          return rpc.invoke(
+            '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(),
+          rpc.invoke(
+            'test.matchImageSnapshot',
+            screenshot,
+            testPath,
+            options,
+            runner,
+          ),
+        disconnect: () => {
+          closePeer(new Error('Harness connection closed by client'));
+          transport.close();
+        },
       });
     };
 
-    const handleError = (event: Event & { message?: string }) => {
-      const detail =
-        typeof event.message === 'string' && event.message
-          ? `: ${event.message}`
-          : '';
+    const handleError = (error: Error) => {
+      const detail = error.message ? `: ${error.message}` : '';
       fail(`Failed to connect to Harness at ${url}${detail}`);
     };
 
-    const handleClose = (event: CloseEvent) => {
+    const handleClose = (event: { code: number; reason: string }) => {
       fail(
         `Harness connection at ${url} closed before becoming ready (code ${event.code}${
           event.reason ? `, reason: ${event.reason}` : ''
@@ -126,7 +212,11 @@ export const connectToHarness = (
       );
     };
 
-    ws.addEventListener('open', handleOpen);
-    ws.addEventListener('error', handleError);
-    ws.addEventListener('close', handleClose);
+    offOpen = transport.onOpen(handleOpen);
+    offError = transport.onError(handleError);
+    offClose = transport.onClose(handleClose);
+
+    if (transport.state === 'open') {
+      handleOpen();
+    }
   });

package/src/errors.ts

@@ -9,3 +9,35 @@ export class DeviceNotRespondingError extends HarnessError {
     this.name = 'DeviceNotRespondingError';
   }
 }
+
+export type AppBridgeDisconnectedReason =
+  | 'app-disconnected'
+  | 'app-replaced'
+  | 'heartbeat-timeout'
+  | 'socket-error'
+  | 'bridge-disposed';
+
+const appBridgeDisconnectedMessage = (
+  reason: AppBridgeDisconnectedReason,
+): string => {
+  switch (reason) {
+    case 'app-replaced':
+      return 'The app bridge was replaced by a newer app connection. This can happen when the app reloads, restarts, or reconnects while a test file is still running.';
+    case 'heartbeat-timeout':
+      return 'The app bridge stopped responding during test execution. This can happen if the app was killed, crashed, became unresponsive, or lost its WebSocket connection.';
+    case 'socket-error':
+      return 'The app bridge connection failed during test execution. This can happen if the app was killed, crashed, or the underlying WebSocket connection closed unexpectedly.';
+    case 'bridge-disposed':
+      return 'The app bridge was disposed before the test file finished running.';
+    case 'app-disconnected':
+      return 'The app bridge disconnected during test execution. This can happen if the app was killed, crashed, reloaded, or restarted while the test file was running.';
+  }
+};
+
+export class AppBridgeDisconnectedError extends HarnessError {
+  constructor(public readonly reason: AppBridgeDisconnectedReason) {
+    super(appBridgeDisconnectedMessage(reason));
+    this.name = 'AppBridgeDisconnectedError';
+    this.stack = `${this.name}: ${this.message}`;
+  }
+}

package/src/heartbeat.ts

@@ -0,0 +1,67 @@
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 5_000;
+export const DEFAULT_HEARTBEAT_TIMEOUT_MS = 20_000;
+
+export type BridgeHeartbeat = {
+  notifyPong: (id: number) => void;
+  dispose: () => void;
+};
+
+export const createHeartbeat = (options: {
+  sendPing: (id: number) => void;
+  onTimeout: () => void;
+  intervalMs?: number;
+  timeoutMs?: number;
+}): BridgeHeartbeat => {
+  const intervalMs = options.intervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;
+  let nextPingId = 1;
+  let pendingPingId: number | null = null;
+  let disposed = false;
+  let timeoutHandle: ReturnType<typeof setTimeout> | null = null;
+
+  const clearPendingTimeout = () => {
+    if (timeoutHandle) {
+      clearTimeout(timeoutHandle);
+      timeoutHandle = null;
+    }
+  };
+
+  const intervalHandle = setInterval(() => {
+    if (disposed || pendingPingId !== null) {
+      return;
+    }
+
+    const pingId = nextPingId++;
+    pendingPingId = pingId;
+    options.sendPing(pingId);
+    timeoutHandle = setTimeout(() => {
+      if (disposed || pendingPingId !== pingId) {
+        return;
+      }
+
+      pendingPingId = null;
+      timeoutHandle = null;
+      options.onTimeout();
+    }, timeoutMs);
+  }, intervalMs);
+
+  return {
+    notifyPong: (id) => {
+      if (id !== pendingPingId) {
+        return;
+      }
+
+      pendingPingId = null;
+      clearPendingTimeout();
+    },
+    dispose: () => {
+      if (disposed) {
+        return;
+      }
+
+      disposed = true;
+      clearInterval(intervalHandle);
+      clearPendingTimeout();
+    },
+  };
+};

package/src/index.ts

@@ -1,2 +1,3 @@
 export * from './shared.js';
 export * from './binary-transfer.js';
+export * from './transport.js';