@react-native-harness/bridge 1.5.0 → 1.7.0

package/src/link/standard-websocket.ts

@@ -0,0 +1,251 @@
+import { globalClock, type Clock, type TimerHandle, type UplinkTransportConnection } from "./ports.js";
+
+export { globalClock } from "./ports.js";
+
+export interface StandardWebSocket {
+  binaryType: string;
+  // harness: React Native declares bufferedAmount but never sets it.
+  readonly bufferedAmount: number | undefined;
+  readonly readyState: number;
+  send(data: string | ArrayBufferView): void;
+  close(code?: number, reason?: string): void;
+  addEventListener(type: "open" | "close" | "error" | "message", listener: never): void;
+  removeEventListener(type: "open" | "close" | "error" | "message", listener: never): void;
+}
+
+const OPEN = 1;
+
+export interface StandardWebSocketOptions {
+  readonly clock?: Clock;
+  readonly pollMs?: number;
+}
+
+const DEFAULT_POLL_MS = 4;
+
+interface MessageLike {
+  readonly data: unknown;
+}
+
+interface Waiter {
+  readonly target: number;
+  readonly resolve: () => void;
+}
+
+export class StandardWebSocketConnection implements UplinkTransportConnection {
+  readonly #socket: StandardWebSocket;
+  readonly #clock: Clock;
+  readonly #pollMs: number;
+  readonly #dataListeners = new Set<(chunk: string) => void>();
+  readonly #binaryListeners = new Set<(bytes: Uint8Array) => void>();
+  readonly #closeListeners = new Set<() => void>();
+  readonly #errorListeners = new Set<(error: Error) => void>();
+  readonly #sentListeners = new Set<() => void>();
+  readonly #pending: string[] = [];
+  #waiters: Waiter[] = [];
+  #queued = 0;
+  #flushed = 0;
+  #checkScheduled = false;
+  #timer: TimerHandle | undefined;
+  #closed = false;
+
+  constructor(socket: StandardWebSocket, options: StandardWebSocketOptions = {}) {
+    this.#socket = socket;
+    this.#clock = options.clock ?? globalClock;
+    this.#pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+    // why: the default, "blob", cannot be read without awaiting, which would reorder messages.
+    socket.binaryType = "arraybuffer";
+    const onMessage = (event: MessageLike) => {
+      this.#onMessage(event.data);
+    };
+    const onClose = () => this.#markClosed();
+    const onError = (event: { readonly error?: unknown }) => {
+      const error = event.error instanceof Error ? event.error : new Error("WebSocket error");
+      for (const listener of this.#errorListeners) listener(error);
+      this.#markClosed();
+    };
+    socket.addEventListener("message", onMessage as never);
+    socket.addEventListener("close", onClose as never);
+    socket.addEventListener("error", onError as never);
+  }
+
+  get closed(): boolean {
+    return this.#closed;
+  }
+
+  get #buffered(): number {
+    return this.#socket.bufferedAmount ?? 0;
+  }
+
+  get unsentBytes(): number {
+    return this.#buffered;
+  }
+
+  onData(listener: (chunk: string) => void): () => void {
+    this.#dataListeners.add(listener);
+    if (this.#pending.length > 0) {
+      for (const chunk of this.#pending.splice(0)) listener(chunk);
+    }
+    return () => {
+      this.#dataListeners.delete(listener);
+    };
+  }
+
+  onBinary(listener: (bytes: Uint8Array) => void): () => void {
+    this.#binaryListeners.add(listener);
+    return () => {
+      this.#binaryListeners.delete(listener);
+    };
+  }
+
+  onClose(listener: () => void): () => void {
+    if (this.#closed) {
+      listener();
+      return () => undefined;
+    }
+    this.#closeListeners.add(listener);
+    return () => {
+      this.#closeListeners.delete(listener);
+    };
+  }
+
+  onError(listener: (error: Error) => void): () => void {
+    this.#errorListeners.add(listener);
+    return () => {
+      this.#errorListeners.delete(listener);
+    };
+  }
+
+  onSent(listener: () => void): () => void {
+    this.#sentListeners.add(listener);
+    return () => {
+      this.#sentListeners.delete(listener);
+    };
+  }
+
+  write(contents: string): Promise<void> {
+    return this.#send(contents);
+  }
+
+  writeBinary(bytes: Uint8Array): Promise<void> {
+    return this.#send(bytes);
+  }
+
+  async close(): Promise<void> {
+    if (this.#closed) return;
+    this.#socket.close();
+    this.#markClosed();
+  }
+
+  #send(data: string | Uint8Array): Promise<void> {
+    if (this.#closed || this.#socket.readyState !== OPEN) return Promise.resolve();
+    // why: the standard send() has no completion callback, so what has left the buffer is worked out from bufferedAmount.
+    const before = this.#buffered;
+    this.#socket.send(data);
+    this.#queued += Math.max(0, this.#buffered - before);
+    return new Promise<void>((resolve) => {
+      this.#waiters.push({ resolve, target: this.#queued });
+      this.#scheduleCheck();
+    });
+  }
+
+  #onMessage(data: unknown): void {
+    if (typeof data === "string") {
+      if (this.#dataListeners.size === 0) {
+        this.#pending.push(data);
+      } else {
+        for (const listener of this.#dataListeners) listener(data);
+      }
+    } else if (data instanceof ArrayBuffer) {
+      const bytes = new Uint8Array(data);
+      for (const listener of this.#binaryListeners) listener(bytes);
+    } else if (ArrayBuffer.isView(data)) {
+      const bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+      for (const listener of this.#binaryListeners) listener(bytes);
+    }
+    // why: a peer's message, a credit most of all, says bytes are moving, and is a cheaper look than a timer.
+    if (this.#waiters.length > 0 || this.#flushed < this.#queued) this.#check();
+  }
+
+  #scheduleCheck(): void {
+    if (this.#checkScheduled) return;
+    // why: a write must not settle, or report sent, before the call that made it has returned.
+    this.#checkScheduled = true;
+    void Promise.resolve().then(() => {
+      this.#checkScheduled = false;
+      this.#check();
+    });
+  }
+
+  #check(): void {
+    if (this.#closed) return;
+    const buffered = this.#buffered;
+    const flushed = Math.max(this.#flushed, this.#queued - buffered);
+    const moved = flushed > this.#flushed;
+    this.#flushed = flushed;
+    if (this.#waiters.some((waiter) => waiter.target <= flushed)) {
+      const due = this.#waiters.filter((waiter) => waiter.target <= flushed);
+      this.#waiters = this.#waiters.filter((waiter) => waiter.target > flushed);
+      for (const waiter of due) waiter.resolve();
+    }
+    if (moved) for (const listener of this.#sentListeners) listener();
+    if (buffered === 0 && this.#timer !== undefined) {
+      this.#clock.cancel(this.#timer);
+      this.#timer = undefined;
+    }
+    // why: a background tab throttles timers to about one a second, so a large transfer there slows until the tab is shown again.
+    if (buffered > 0 && this.#timer === undefined) {
+      this.#timer = this.#clock.setTimer(this.#pollMs, () => {
+        this.#timer = undefined;
+        this.#check();
+      });
+    }
+  }
+
+  #markClosed(): void {
+    if (this.#closed) return;
+    this.#closed = true;
+    if (this.#timer !== undefined) {
+      this.#clock.cancel(this.#timer);
+      this.#timer = undefined;
+    }
+    for (const waiter of this.#waiters.splice(0)) waiter.resolve();
+    for (const listener of this.#closeListeners) listener();
+  }
+}
+
+export interface StandardWebSocketDialOptions extends StandardWebSocketOptions {
+  readonly url: string;
+  readonly protocols?: string | string[];
+  readonly createSocket?: (url: string, protocols?: string | string[]) => StandardWebSocket;
+}
+
+export async function connectStandardWebSocket(
+  options: StandardWebSocketDialOptions,
+): Promise<UplinkTransportConnection> {
+  const create =
+    options.createSocket ??
+    ((url: string, protocols?: string | string[]) =>
+      new WebSocket(url, protocols) as unknown as StandardWebSocket);
+  const socket = create(options.url, options.protocols);
+  const connection = new StandardWebSocketConnection(socket, options);
+  await new Promise<void>((resolve, reject) => {
+    if (socket.readyState === OPEN) return resolve();
+    const onOpen = () => {
+      cleanup();
+      resolve();
+    };
+    const onFail = () => {
+      cleanup();
+      reject(new Error(`could not open a WebSocket to ${options.url}`));
+    };
+    const cleanup = () => {
+      socket.removeEventListener("open", onOpen as never);
+      socket.removeEventListener("error", onFail as never);
+      socket.removeEventListener("close", onFail as never);
+    };
+    socket.addEventListener("open", onOpen as never);
+    socket.addEventListener("error", onFail as never);
+    socket.addEventListener("close", onFail as never);
+  });
+  return connection;
+}

package/src/link/streams.ts

@@ -0,0 +1,34 @@
+import {
+  ByteLengthQueuingStrategy as PonyfillByteLengthQueuingStrategy,
+  ReadableStream as PonyfillReadableStream,
+  WritableStream as PonyfillWritableStream,
+} from "web-streams-polyfill";
+
+// harness: React Native has no WHATWG streams. The ponyfill fills the gap without
+// installing globals, so the app under test sees the runtime it would see in production.
+
+interface StreamGlobals {
+  readonly ReadableStream?: typeof globalThis.ReadableStream;
+  readonly WritableStream?: typeof globalThis.WritableStream;
+  readonly ByteLengthQueuingStrategy?: typeof globalThis.ByteLengthQueuingStrategy;
+}
+
+const host = globalThis as StreamGlobals;
+
+// why: one source for all three, so a native stream never meets a ponyfilled strategy.
+const native =
+  typeof host.ReadableStream === "function" &&
+  typeof host.WritableStream === "function" &&
+  typeof host.ByteLengthQueuingStrategy === "function";
+
+export const LinkReadableStream: typeof globalThis.ReadableStream = native
+  ? (host.ReadableStream as typeof globalThis.ReadableStream)
+  : (PonyfillReadableStream as unknown as typeof globalThis.ReadableStream);
+
+export const LinkWritableStream: typeof globalThis.WritableStream = native
+  ? (host.WritableStream as typeof globalThis.WritableStream)
+  : (PonyfillWritableStream as unknown as typeof globalThis.WritableStream);
+
+export const LinkByteLengthQueuingStrategy: typeof globalThis.ByteLengthQueuingStrategy = native
+  ? (host.ByteLengthQueuingStrategy as typeof globalThis.ByteLengthQueuingStrategy)
+  : (PonyfillByteLengthQueuingStrategy as unknown as typeof globalThis.ByteLengthQueuingStrategy);

package/src/protocol.ts

@@ -38,20 +38,25 @@ export type BridgeReadyMessage = {
   device: DeviceDescriptor;
 };
 
-export type BridgePingMessage = {
-  type: 'ping';
+/**
+ * Sent by the server to check that the app's JS thread is getting a turn to
+ * run. Only JS answers it, unlike WebSocket protocol pings, which the native
+ * WebSocket answers.
+ */
+export type BridgeJsProbeMessage = {
+  type: 'js-probe';
   id: number;
 };
 
-export type BridgePongMessage = {
-  type: 'pong';
+export type BridgeJsProbeAckMessage = {
+  type: 'js-probe-ack';
   id: number;
 };
 
 export type BridgeControlMessage =
   | BridgeReadyMessage
-  | BridgePingMessage
-  | BridgePongMessage;
+  | BridgeJsProbeMessage
+  | BridgeJsProbeAckMessage;
 
 export type BridgeMessage<Event extends { type: string } = BridgeEvents> =
   | BridgeInvokeMessage
@@ -171,10 +176,10 @@ export const parseBridgeMessage = (raw: string): BridgeMessage => {
       readDeviceDescriptor(parsed.device);
       return parsed as BridgeReadyMessage;
     }
-    case 'ping':
-    case 'pong': {
+    case 'js-probe':
+    case 'js-probe-ack': {
       readNumber(parsed.id, 'id');
-      return parsed as BridgePingMessage | BridgePongMessage;
+      return parsed as BridgeJsProbeMessage | BridgeJsProbeAckMessage;
     }
     default:
       throw new Error(`Invalid bridge message: unknown type ${messageType}`);

package/src/rpc-peer.ts

@@ -5,7 +5,10 @@ import {
   serializeBridgeMessage,
   type BridgeControlMessage,
 } from './protocol.js';
-import type { RpcTransport } from './transport.js';
+
+export type RpcTransport = {
+  send: (message: string) => void;
+};
 
 type RpcMethod = {
   bivarianceHack(...args: unknown[]): unknown;
@@ -217,8 +220,8 @@ export const createRpcPeer = <
           return null;
         }
         case 'ready':
-        case 'ping':
-        case 'pong':
+        case 'js-probe':
+        case 'js-probe-ack':
           return message;
       }
     },

package/src/server.ts

@@ -7,20 +7,26 @@ 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 { receiveBinary } from './binary.js';
 import {
   AppBridgeDisconnectedError,
   DeviceNotRespondingError,
 } from './errors.js';
-import { createHeartbeat } from './heartbeat.js';
+import {
+  createAppLiveness,
+  resolveAppLivenessOptions,
+  type AppLivenessOverrides,
+} from './app-liveness.js';
 import { matchImageSnapshot } from './image-snapshot.js';
+import {
+  createLink,
+  globalClock,
+  StandardWebSocketConnection,
+  type LinkConnection,
+  type StandardWebSocket,
+} from './link/index.js';
 import { serializeBridgeMessage } from './protocol.js';
 import { createRpcPeer } from './rpc-peer.js';
-import {
-  createRpcTransport,
-  type BridgeTransport,
-} from './transport.js';
-import { createNodeWebSocketTransport } from './websocket-server-transport.js';
 import type {
   BridgeServerFunctions,
   BridgeClientFunctions,
@@ -37,6 +43,10 @@ export {
   AppBridgeDisconnectedError,
   DeviceNotRespondingError,
 } from './errors.js';
+export {
+  DEFAULT_APP_LIVENESS_OPTIONS,
+  type AppLivenessOverrides,
+} from './app-liveness.js';
 
 const bridgeLogger = logger.child('bridge');
 const noop = (): void => undefined;
@@ -61,6 +71,8 @@ type TransportOptions =
 export type HarnessBridgeOptions = TransportOptions & {
   timeout?: number;
   context: HarnessContext;
+  /** Overrides for the connection check and JS watchdog limits. */
+  liveness?: AppLivenessOverrides;
 };
 
 export type HarnessBridge = {
@@ -92,17 +104,17 @@ const createWss = (transport: TransportOptions): Promise<WebSocketServer> => {
 };
 
 const receiveScreenshot = async (
-  binaryStore: BinaryStore,
+  link: LinkConnection,
   reference: BinaryDataReference,
 ): Promise<FileReference> => {
-  const data = binaryStore.get(reference.transferId);
-  if (!data) {
+  const data = await receiveBinary(link, reference.channelId);
+
+  if (data.length !== reference.size) {
     throw new Error(
-      `Binary data for transfer ${reference.transferId} not found or expired`,
+      `Screenshot transfer ended after ${data.length} of ${reference.size} bytes`,
     );
   }
 
-  binaryStore.delete(reference.transferId);
   const file = path.join(os.tmpdir(), `harness-screenshot-${randomUUID()}.png`);
   await fs.writeFile(file, data);
   return { path: file };
@@ -111,13 +123,18 @@ const receiveScreenshot = async (
 export const createHarnessBridge = async (
   options: HarnessBridgeOptions,
 ): Promise<HarnessBridge> => {
-  const { timeout, context, ...transportOptions } = options;
+  const { timeout, context, liveness, ...transportOptions } = options;
+  const livenessOptions = resolveAppLivenessOptions(liveness);
   const wss = await createWss(transportOptions);
   bridgeLogger.debug('bridge server ready');
 
   const emitter = new EventEmitter();
+  // Screenshot files written by this bridge that have not been compared yet.
+  const receivedScreenshots = new Set<string>();
+  const removeScreenshot = (file: string) =>
+    fs.rm(file, { force: true }).catch(() => undefined);
   let currentConnection: AppConnection | null = null;
-  let activeSession: { disconnect: (reason?: Error) => void; transport: BridgeTransport } | null =
+  let activeSession: { disconnect: (reason?: Error) => void; link: LinkConnection } | null =
     null;
   const connectionWaiters: Array<{
     resolve: (c: AppConnection) => void;
@@ -131,34 +148,55 @@ export const createHarnessBridge = async (
     }
 
     bridgeLogger.debug('app connected');
-    const transport = createNodeWebSocketTransport(ws);
-    const binaryStore = new BinaryStore();
+    const link = createLink(
+      new StandardWebSocketConnection(ws as unknown as StandardWebSocket),
+      {
+        end: 'gateway',
+        clock: globalClock,
+        logger: bridgeLogger.child('link'),
+      },
+    );
     let readyConnection: AppConnection | null = null;
     let disconnected = false;
     let offMessage: () => void = noop;
     let offClose: () => void = noop;
     let offError: () => void = noop;
 
-    const closeTransport = () => {
-      if (transport.state === 'closing' || transport.state === 'closed') {
-        return;
-      }
-
-      transport.close(1012);
-    };
-
     const rpc = createRpcPeer<
       BridgeServerFunctions,
       BridgeClientFunctions,
       BridgeEvents
     >({
       localMethods: {
-        'device.screenshot.receive': (ref) => receiveScreenshot(binaryStore, ref),
-        'test.matchImageSnapshot': (screenshot, testPath, opts) =>
-          matchImageSnapshot(screenshot, testPath, opts, context.platform.name),
+        'device.screenshot.receive': async (ref) => {
+          const file = await receiveScreenshot(link, ref);
+          receivedScreenshots.add(file.path);
+          return file;
+        },
+        'test.matchImageSnapshot': async (screenshot, testPath, opts) => {
+          try {
+            return await matchImageSnapshot(
+              screenshot,
+              testPath,
+              opts,
+              context.platform.name,
+              context.updateSnapshot ?? 'new'
+            );
+          } finally {
+            // Only delete files this bridge created, never a client-supplied path.
+            if (receivedScreenshots.delete(screenshot.path)) {
+              await removeScreenshot(screenshot.path);
+            }
+          }
+        },
+      },
+      transport: {
+        send: (message) => {
+          void link.write(message);
+        },
       },
-      transport: createRpcTransport(transport),
       onEvent: (event) => {
+        appLiveness.handleEvent(event);
         emitter.emit('event', event);
       },
       callTimeoutMs: (method) => method === 'runTests' ? undefined : timeout,
@@ -167,14 +205,24 @@ export const createHarnessBridge = async (
       },
     });
 
-    const heartbeat = createHeartbeat({
-      sendPing: (id) => {
-        transport.send(serializeBridgeMessage({ type: 'ping', id }));
+    const appLiveness = createAppLiveness({
+      socket: ws,
+      sendProbe: (id) => {
+        void link.write(serializeBridgeMessage({ type: 'js-probe', id }));
       },
-      onTimeout: () => {
-        bridgeLogger.warn('app heartbeat timed out');
-        disconnect(new AppBridgeDisconnectedError('heartbeat-timeout'));
+      onLost: (error) => {
+        if (error.reason === 'connection-lost') {
+          bridgeLogger.warn('app connection lost (no response to WebSocket ping)');
+        } else {
+          bridgeLogger.warn('app JS thread unresponsive: %s', error.detail);
+        }
+
+        disconnect(error);
+        // Neither a half-open socket nor a blocked JS thread completes a
+        // close handshake, so drop the socket instead of waiting for one.
+        ws.terminate();
       },
+      config: livenessOptions,
     });
 
     const disconnect = (reason?: Error) => {
@@ -187,10 +235,9 @@ export const createHarnessBridge = async (
       offClose();
       offError();
       bridgeLogger.debug('app disconnected');
-      heartbeat.dispose();
-      binaryStore.dispose();
+      appLiveness.dispose();
 
-      if (activeSession?.transport === transport) {
+      if (activeSession?.link === link) {
         activeSession = null;
       }
 
@@ -199,14 +246,14 @@ export const createHarnessBridge = async (
       }
 
       rpc.close(reason ?? new AppBridgeDisconnectedError('app-disconnected'));
-      closeTransport();
+      void link.close();
 
       if (readyConnection) {
         emitter.emit('disconnected');
       }
     };
 
-    activeSession = { disconnect, transport };
+    activeSession = { disconnect, link };
 
     const handleControlMessage = async (message: string) => {
       const controlMessage = await rpc.handleMessage(message);
@@ -241,34 +288,14 @@ export const createHarnessBridge = async (
           }
           return;
         }
-        case 'ping': {
-          transport.send(
-            serializeBridgeMessage({ type: 'pong', id: controlMessage.id }),
-          );
-          return;
-        }
-        case 'pong': {
-          heartbeat.notifyPong(controlMessage.id);
+        case 'js-probe-ack': {
+          appLiveness.handleProbeAck(controlMessage.id);
           return;
         }
       }
     };
 
-    const handleBinaryMessage = (message: Uint8Array) => {
-      try {
-        const { transferId, data } = parseBinaryFrame(message);
-        binaryStore.add(transferId, data);
-      } catch (error) {
-        bridgeLogger.warn('failed to parse binary frame: %s', error);
-      }
-    };
-
-    offMessage = transport.onMessage((message) => {
-      if (typeof message !== 'string') {
-        handleBinaryMessage(message);
-        return;
-      }
-
+    offMessage = link.onData((message) => {
       void handleControlMessage(message).catch((error) => {
         bridgeLogger.warn('failed to handle bridge message: %s', error);
         disconnect(
@@ -279,17 +306,17 @@ export const createHarnessBridge = async (
       });
     });
 
-    offClose = transport.onClose(() => {
-      disconnect();
-    });
-
-    offError = transport.onError((error) => {
+    offError = link.onError((error) => {
       disconnect(
         error instanceof Error
           ? error
           : new AppBridgeDisconnectedError('socket-error'),
       );
     });
+
+    offClose = link.onClose(() => {
+      disconnect();
+    });
   });
 
   return {
@@ -344,6 +371,11 @@ export const createHarnessBridge = async (
 
       wss.close();
       emitter.removeAllListeners();
+
+      for (const file of receivedScreenshots) {
+        void removeScreenshot(file);
+      }
+      receivedScreenshots.clear();
     },
   };
 };

package/src/shared/test-runner.ts

@@ -14,6 +14,8 @@ export type TestResultStatus = 'passed' | 'failed' | 'skipped' | 'todo';
 export type SerializedError = {
   name: string;
   message: string;
+  // Expected/received diff of a failed assertion, formatted like Vitest's.
+  diff?: string;
   codeFrame?: CodeFrame;
   diagnostics?: {
     pendingPromises?: {
@@ -42,6 +44,11 @@ export type TestRunnerSuiteStartedEvent = {
   type: 'suite-started';
   name: string;
   file: string;
+  /**
+   * The timeout in ms of the suite's `beforeAll`/`afterAll` hooks. Absent
+   * for suites that are skipped or todo.
+   */
+  timeout?: number;
 };
 
 export type TestRunnerTestStartedEvent = {
@@ -53,6 +60,11 @@ export type TestRunnerTestStartedEvent = {
   fullName: string;
   startedAt: number;
   declarationMode?: TestDeclarationMode;
+  /**
+   * The test's timeout in ms, covering its `beforeEach`/`afterEach` hooks.
+   * Absent for tests that are skipped or todo.
+   */
+  timeout?: number;
 };
 
 export type TestRunnerTestFinishedEvent = {