react-native-web-serial-api 0.1.0 → 0.2.0

package/src/testing/expose.ts

@@ -0,0 +1,147 @@
+/**
+ * `exposeSimulatedDevice` — run a {@link SimulatedDevice} simulator behind a WebSocket
+ * server so a real app (on a device/emulator) can connect to it with
+ * `new Serial(new WebSocketSerialTransport(url))` and drive the *same* simulated
+ * peripheral your Jest tests drive. The test process keeps the
+ * {@link DeviceHandle} handle, so it can inject frames / move the GPS and
+ * `await whenOpened()` for the app to connect — turning an in-memory device
+ * suite into an on-device E2E without changing the device code.
+ *
+ * `ws` is an *optional* dependency: it is loaded lazily (and only in Node), via
+ * an indirect require so app bundlers never pull it into a mobile bundle. Pass
+ * `options.WebSocketServer` to inject your own (e.g. `import {WebSocketServer}
+ * from 'ws'`) and skip the lazy load entirely.
+ *
+ * @example
+ * import {WebSocketServer} from 'ws';
+ * const ex = exposeSimulatedDevice(new WMBusGateway('iU891A-XL'), {
+ *   port: 8090,
+ *   WebSocketServer,
+ * });
+ * // …app connects to ex.url…
+ * await ex.whenOpened();
+ * ex.simulatedDevice.addMeter(meter);
+ * meter.sendTelegram(); // the app receives the 0x20 telegram event
+ * await ex.close();
+ */
+
+import {
+  attachBridge,
+  portInfoFromDevice,
+  SimulatedDeviceToSerialLike,
+  type WsLike,
+} from '../websocket';
+import type {DeviceOptions} from './in-memory-serial-transport';
+import {
+  type DeviceHandle,
+  InMemorySerialTransport,
+} from './in-memory-serial-transport';
+import type {
+  SimulatedDevice,
+  SimulatedDeviceOpenOptions,
+} from './simulated-device';
+
+/** The `ws` WebSocketServer surface this helper uses. */
+export type WebSocketServerLike = {
+  on(event: 'connection', listener: (socket: WsLike) => void): void;
+  close(cb?: () => void): void;
+};
+
+/** A `ws`-compatible `WebSocketServer` constructor. */
+export type WebSocketServerCtor = new (options: {
+  port: number;
+  host?: string;
+}) => WebSocketServerLike;
+
+export type ExposeSimulatedDeviceOptions = {
+  /** TCP port for the WebSocket server. */
+  port: number;
+  /** Listen address. Defaults to `localhost`. Use `0.0.0.0` for an emulator. */
+  host?: string;
+  /** Inject a `ws`-compatible `WebSocketServer` (skips the lazy `require('ws')`). */
+  WebSocketServer?: WebSocketServerCtor;
+  /** Forward device→client data before the app sends startReading. Default true. */
+  readingByDefault?: boolean;
+  /** Diagnostics logger. */
+  log?: (message: string) => void;
+  /** Transport-side device options (hasPermission defaults to true). */
+  device?: DeviceOptions;
+};
+
+export type ExposedDevice<D extends SimulatedDevice = SimulatedDevice> = {
+  /** The URL the app connects to, e.g. `ws://localhost:8090`. */
+  url: string;
+  transport: InMemorySerialTransport;
+  /** The transport-side handle: push/emitError/whenOpened/whenClosed/… */
+  device: DeviceHandle;
+  /** The concrete device simulator, typed (drive it from the test). */
+  simulatedDevice: D;
+  /** Resolve when the app opens the port (now if already open). */
+  whenOpened(): Promise<SimulatedDeviceOpenOptions>;
+  /** Resolve when the app closes the port (now if not open). */
+  whenClosed(): Promise<void>;
+  /** Stop the WebSocket server. */
+  close(): Promise<void>;
+};
+
+/** Resolve a `ws` WebSocketServer lazily, in Node only, invisibly to bundlers. */
+function loadWebSocketServer(): WebSocketServerCtor {
+  const specifier = 'ws';
+  const nodeRequire =
+    // @ts-ignore
+    typeof module !== 'undefined' &&
+    // @ts-ignore
+    typeof (module as {require?: unknown}).require === 'function'
+      ? // @ts-ignore
+        (module as {require: (id: string) => unknown}).require.bind(module)
+      : /* istanbul ignore next */ undefined;
+  /* istanbul ignore next — only reachable in non-Node bundled environments */
+  if (!nodeRequire) {
+    throw new Error(
+      "exposeSimulatedDevice could not load 'ws'. Pass options.WebSocketServer, " +
+        'or run it in a Node process with the optional `ws` package installed.',
+    );
+  }
+  const ws = nodeRequire(specifier) as {
+    WebSocketServer?: WebSocketServerCtor;
+    Server?: WebSocketServerCtor;
+  };
+  const Ctor = ws.WebSocketServer ?? ws.Server;
+  if (!Ctor) {
+    throw new Error("the 'ws' package did not export a WebSocketServer.");
+  }
+  return Ctor;
+}
+
+export function exposeSimulatedDevice<D extends SimulatedDevice>(
+  simulatedDevice: D,
+  options: ExposeSimulatedDeviceOptions,
+): ExposedDevice<D> {
+  const transport = new InMemorySerialTransport();
+  const device = transport.addDevice(simulatedDevice, {
+    hasPermission: true,
+    ...options.device,
+  });
+
+  const Ctor = options.WebSocketServer ?? loadWebSocketServer();
+  const server = new Ctor({port: options.port, host: options.host});
+  server.on('connection', socket => {
+    const serial = SimulatedDeviceToSerialLike(transport, device);
+    attachBridge(serial, socket, {
+      portInfo: portInfoFromDevice(device),
+      readingByDefault: options.readingByDefault,
+      log: options.log,
+    });
+  });
+
+  const host = options.host ?? 'localhost';
+  return {
+    url: `ws://${host}:${options.port}`,
+    transport,
+    device,
+    simulatedDevice,
+    whenOpened: () => device.whenOpened(),
+    whenClosed: () => device.whenClosed(),
+    close: () => new Promise<void>(resolve => server.close(() => resolve())),
+  };
+}

package/src/testing/harness.ts

@@ -0,0 +1,124 @@
+/**
+ * Tiny, dependency-free test helpers for driving serial devices — shared by the
+ * library's own conformance suite, the {@link SerialClient}, and consumers' app
+ * tests. Free of `jest` and `react-native`, so they run under any test runner
+ * and on a real device (e.g. an on-device Self-Test screen).
+ */
+
+/** Throw `message` if `condition` is falsy. */
+export function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+/** Throw if `actual !== expected`, including both values in the message. */
+export function assertEqual<T>(actual: T, expected: T, message: string): void {
+  if (actual !== expected) {
+    throw new Error(
+      `${message} (expected ${String(expected)}, got ${String(actual)})`,
+    );
+  }
+}
+
+/** Byte-for-byte equality of two sequences. */
+export function bytesEqual(
+  a: ArrayLike<number>,
+  b: ArrayLike<number>,
+): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/** What {@link assertRejects} may additionally check about the thrown error. */
+export type RejectionExpectation = {
+  name?: string;
+  type?: new (...args: never[]) => Error;
+  message?: string | RegExp;
+};
+
+/** Assert `fn()` rejects (optionally matching the error name/type/message). */
+export async function assertRejects(
+  fn: () => Promise<unknown>,
+  message: string,
+  expected?: RejectionExpectation,
+): Promise<void> {
+  try {
+    await fn();
+  } catch (e) {
+    const err = e as Error;
+    if (expected?.name && err.name !== expected.name) {
+      throw new Error(
+        `${message}: expected error "${expected.name}" but got "${err.name}"`,
+      );
+    }
+    if (expected?.type && !(err instanceof expected.type)) {
+      throw new Error(`${message}: expected a ${expected.type.name}`);
+    }
+    if (expected?.message !== undefined) {
+      const ok =
+        expected.message instanceof RegExp
+          ? expected.message.test(err.message)
+          : err.message.includes(expected.message);
+      if (!ok) {
+        throw new Error(
+          `${message}: expected the error message to match ${String(expected.message)}`,
+        );
+      }
+    }
+    return;
+  }
+  throw new Error(`${message}: expected a rejection but none occurred`);
+}
+
+/** Normalise any thrown value into a `"Name: message"` string. */
+export function errorMessage(e: unknown): string {
+  return e instanceof Error ? `${e.name}: ${e.message}` : String(e);
+}
+
+/** Reject if `promise` doesn't settle within `ms`; `label` names it on timeout. */
+export function withTimeout<T>(
+  promise: Promise<T>,
+  ms: number,
+  label: string,
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error(`timed out: ${label}`)),
+      ms,
+    );
+    promise.then(
+      v => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      e => {
+        clearTimeout(timer);
+        reject(e);
+      },
+    );
+  });
+}
+
+/** The slice of `ReadableStreamDefaultReader` the helpers need. */
+export type ByteReader = {
+  read(): Promise<{done: boolean; value?: Uint8Array}>;
+};
+
+/** Read exactly `count` bytes from a reader (accumulating chunks), with a timeout. */
+export async function readBytes(
+  reader: ByteReader,
+  count: number,
+  timeoutMs = 2000,
+): Promise<number[]> {
+  const out: number[] = [];
+  while (out.length < count) {
+    const {done, value} = await withTimeout(
+      reader.read(),
+      timeoutMs,
+      `reading ${count} bytes (got ${out.length})`,
+    );
+    if (done) break;
+    if (value) out.push(...value);
+  }
+  return out;
+}

package/src/testing/{virtual-serial.ts → in-memory-serial-transport.ts}

@@ -1,5 +1,5 @@
 /**
- * VirtualSerialTransport — an in-memory {@link SerialTransport} for tests and
+ * InMemorySerialTransport — an in-memory {@link SerialTransport} for tests and
  * on-device demos.
  *
  * It implements the exact same interface the production `UsbSerialModule` does,
@@ -13,8 +13,8 @@
  * Inject it via `new Serial(transport)` or globally with `setUsbSerial(transport)`.
  *
  * @example
- * const transport = new VirtualSerialTransport();
- * transport.addDevice(new EchoDevice(), {hasPermission: true});
+ * const transport = new InMemorySerialTransport();
+ * transport.addDevice(new LoopbackDevice(), {hasPermission: true});
  * const serial = new Serial(transport);
  * const [port] = await serial.getPorts();
  * await port.open({baudRate: 115200});
@@ -36,13 +36,13 @@ import type {
 } from '../transport';
 import {DEFAULT_OPEN_OPTIONS} from '../transport';
 import type {
-  SerialDevice,
-  SerialDeviceHost,
   SerialInputSignals,
-} from './serial-device';
+  SimulatedDevice,
+  SimulatedDeviceHost,
+} from './simulated-device';
 
-/** Transport-side knobs when registering a {@link SerialDevice}. */
-export type VirtualDeviceOptions = {
+/** Transport-side knobs when registering a {@link SimulatedDevice}. */
+export type DeviceOptions = {
   /** Whether the app already holds USB permission. Defaults to false. */
   hasPermission?: boolean;
   /** Defaults to 0. A USB device may expose several ports. */
@@ -63,9 +63,9 @@ export type VirtualDeviceOptions = {
   flowControlThreshold?: number;
 };
 
-export type VirtualSerialOptions = {
+export type InMemorySerialTransportOptions = {
   /** Devices to register on construction (same as calling addDevice). */
-  devices?: SerialDevice[];
+  devices?: SimulatedDevice[];
   /**
    * Delay (ms) applied to async operations and to inbound data delivery.
    * 0 (default) resolves on a microtask — deterministic for Jest. A small
@@ -113,11 +113,11 @@ function mapInputSignals(s: SerialInputSignals): Partial<InputSignals> {
 }
 
 /**
- * A simulated USB-serial device. Returned by {@link VirtualSerialTransport.addDevice}.
+ * A simulated USB-serial device. Returned by {@link InMemorySerialTransport.addDevice}.
  * The mutable fields and the helper methods let a test or demo drive the device
  * the way physical hardware (and a human plugging cables) otherwise would.
  */
-export class VirtualDevice {
+export class DeviceHandle {
   readonly usbVendorId: number;
   readonly usbProductId: number;
   readonly portNumber: number;
@@ -130,7 +130,7 @@ export class VirtualDevice {
   isOpen = false;
   reading = false;
   /** The hosted behaviour. */
-  readonly serialDevice: SerialDevice;
+  readonly simulatedDevice: SimulatedDevice;
   loopbackSignals: boolean;
   flowControl: FlowControl = 'NONE';
   flowControlThreshold: number;
@@ -159,17 +159,17 @@ export class VirtualDevice {
   readonly written: number[][] = [];
 
   readonly #fails = new Set<FailableOp>();
-  readonly #transport: VirtualSerialTransport;
+  readonly #transport: InMemorySerialTransport;
 
   constructor(
-    transport: VirtualSerialTransport,
+    transport: InMemorySerialTransport,
     deviceId: number,
-    device: SerialDevice,
-    options: VirtualDeviceOptions,
+    device: SimulatedDevice,
+    options: DeviceOptions,
   ) {
     this.#transport = transport;
     this.deviceId = deviceId;
-    this.serialDevice = device;
+    this.simulatedDevice = device;
     this.usbVendorId = device.usbVendorId;
     this.usbProductId = device.usbProductId;
     this.portNumber = options.portNumber ?? 0;
@@ -241,15 +241,49 @@ export class VirtualDevice {
   loseDevice(): void {
     this.#transport.loseDevice(this);
   }
+
+  readonly #openWaiters = new Set<(options: Required<OpenOptions>) => void>();
+  readonly #closeWaiters = new Set<() => void>();
+
+  /**
+   * Resolve when the host opens this port (immediately if already open). Lets a
+   * test `await` the app connecting before driving the device.
+   */
+  whenOpened(): Promise<Required<OpenOptions>> {
+    if (this.isOpen && this.openOptions) {
+      return Promise.resolve(this.openOptions);
+    }
+    return new Promise(resolve => this.#openWaiters.add(resolve));
+  }
+
+  /** Resolve when the host closes this port (immediately if not open). */
+  whenClosed(): Promise<void> {
+    if (!this.isOpen) {
+      return Promise.resolve();
+    }
+    return new Promise(resolve => this.#closeWaiters.add(resolve));
+  }
+
+  /** @internal The transport calls this right after the port opens. */
+  _notifyOpen(options: Required<OpenOptions>): void {
+    for (const waiter of [...this.#openWaiters]) waiter(options);
+    this.#openWaiters.clear();
+  }
+
+  /** @internal The transport calls this right after the port closes/detaches. */
+  _notifyClose(): void {
+    for (const waiter of [...this.#closeWaiters]) waiter();
+    this.#closeWaiters.clear();
+  }
 }
 
 type Listener<E> = (event: E) => void;
 
 /**
- * In-memory transport backing one or more {@link VirtualDevice}s.
+ * In-memory transport backing one or more {@link DeviceHandle}s.
  */
-export class VirtualSerialTransport implements SerialTransport {
-  readonly #devices: VirtualDevice[] = [];
+export class InMemorySerialTransport implements SerialTransport {
+  readonly #devices: DeviceHandle[] = [];
   readonly #latencyMs: number;
   readonly #autoGrant: boolean;
   readonly #chunkSize: number;
@@ -262,12 +296,12 @@ export class VirtualSerialTransport implements SerialTransport {
 
   /** Scripts the next showPortPicker() outcome. */
   #pendingPick:
-    | VirtualDevice
-    | ((d: VirtualDevice) => boolean)
+    | DeviceHandle
+    | ((d: DeviceHandle) => boolean)
     | 'reject'
     | null = null;
 
-  constructor(options: VirtualSerialOptions = {}) {
+  constructor(options: InMemorySerialTransportOptions = {}) {
     this.#latencyMs = options.latencyMs ?? 0;
     this.#autoGrant = options.autoGrantPermission ?? true;
     this.#chunkSize = options.chunkSize ?? 0;
@@ -277,32 +311,32 @@ export class VirtualSerialTransport implements SerialTransport {
   // ── Device management ──────────────────────────────────────────────────────
 
   /** All devices known to the transport (attached or not). */
-  get devices(): readonly VirtualDevice[] {
+  get devices(): readonly DeviceHandle[] {
     return this.#devices;
   }
 
   /**
-   * Register a {@link SerialDevice}. It starts attached but does not fire
+   * Register a {@link SimulatedDevice}. It starts attached but does not fire
    * "connect"; its identity (usbVendorId/usbProductId/serialNumber) is read from
    * the device, and `options` carries the transport-side knobs.
    */
   addDevice(
-    serialDevice: SerialDevice,
-    options: VirtualDeviceOptions = {},
-  ): VirtualDevice {
-    const device = new VirtualDevice(
+    simulatedDevice: SimulatedDevice,
+    options: DeviceOptions = {},
+  ): DeviceHandle {
+    const device = new DeviceHandle(
       this,
       this.#nextDeviceId++,
-      serialDevice,
+      simulatedDevice,
       options,
     );
-    serialDevice._bind(this.#hostFor(device));
+    simulatedDevice._bind(this.#hostFor(device));
     this.#devices.push(device);
     return device;
   }
 
-  /** The handle a hosted {@link SerialDevice} uses to talk back to the host. */
-  #hostFor(device: VirtualDevice): SerialDeviceHost {
+  /** The handle a hosted {@link SimulatedDevice} uses to talk back to the host. */
+  #hostFor(device: DeviceHandle): SimulatedDeviceHost {
     return {
       get deviceId() {
         return device.deviceId;
@@ -328,23 +362,23 @@ export class VirtualSerialTransport implements SerialTransport {
       const result = fn();
       if (result && typeof (result as Promise<void>).then === 'function') {
         (result as Promise<void>).catch((err: unknown) => {
-          console.error('SerialDevice hook rejected:', err);
+          console.error('SimulatedDevice hook rejected:', err);
         });
       }
     } catch (err) {
-      console.error('SerialDevice hook threw:', err);
+      console.error('SimulatedDevice hook threw:', err);
     }
   }
 
   /** Remove a device entirely; detaches it first if attached. */
-  removeDevice(device: VirtualDevice): void {
+  removeDevice(device: DeviceHandle): void {
     if (device.attached) this.detach(device);
     const i = this.#devices.indexOf(device);
     if (i >= 0) this.#devices.splice(i, 1);
   }
 
   /** (Re)attach a device, assigning it a fresh deviceId, and fire "connect". */
-  attach(device: VirtualDevice): void {
+  attach(device: DeviceHandle): void {
     device.deviceId = this.#nextDeviceId++;
     device.attached = true;
     this.#emit(this.#connectListeners, {
@@ -355,28 +389,29 @@ export class VirtualSerialTransport implements SerialTransport {
   }
 
   /** Detach a device and fire "disconnect"; any open port becomes closed. */
-  detach(device: VirtualDevice): void {
+  detach(device: DeviceHandle, lost = false): void {
     const {deviceId, usbVendorId, usbProductId} = device;
+    const wasOpen = device.isOpen;
     device.attached = false;
     device.isOpen = false;
     device.reading = false;
+    if (wasOpen) device._notifyClose();
     this.#emit(this.#disconnectListeners, {
       deviceId,
       usbVendorId,
       usbProductId,
+      lost,
     });
   }
 
   /** Simulate an unplug while open: error the stream first, then disconnect. */
-  loseDevice(device: VirtualDevice): void {
+  loseDevice(device: DeviceHandle): void {
     if (device.isOpen) this._error(device, 'Device disconnected');
-    this.detach(device);
+    this.detach(device, true);
   }
 
   /** Script the next showPortPicker() resolution (a device or a predicate). */
-  selectNextPort(
-    target: VirtualDevice | ((d: VirtualDevice) => boolean),
-  ): void {
+  selectNextPort(target: DeviceHandle | ((d: DeviceHandle) => boolean)): void {
     this.#pendingPick = target;
   }
 
@@ -385,10 +420,10 @@ export class VirtualSerialTransport implements SerialTransport {
     this.#pendingPick = 'reject';
   }
 
-  // ── Internal event helpers (called by VirtualDevice) ───────────────────────
+  // ── Internal event helpers (called by DeviceHandle) ──────────────────────────────
 
   /** @internal deliver inbound bytes to the host's readable stream. */
-  _deliver(device: VirtualDevice, data: number[]): void {
+  _deliver(device: DeviceHandle, data: number[]): void {
     if (!device.attached || !device.isOpen || !device.reading) return;
 
     if (device.overrunLimit != null) {
@@ -409,7 +444,7 @@ export class VirtualSerialTransport implements SerialTransport {
   }
 
   /** @internal raise a read error for a device's open port. */
-  _error(device: VirtualDevice, message: string, name?: string): void {
+  _error(device: DeviceHandle, message: string, name?: string): void {
     const event: ErrorEvent = {
       deviceId: device.deviceId,
       portNumber: device.portNumber,
@@ -420,7 +455,7 @@ export class VirtualSerialTransport implements SerialTransport {
   }
 
   /** Deliver `data` as one or more onData events, honouring `chunkSize`. */
-  #emitData(device: VirtualDevice, data: number[]): void {
+  #emitData(device: DeviceHandle, data: number[]): void {
     const emitOne = (slice: number[]) => {
       const event: DataEvent = {
         deviceId: device.deviceId,
@@ -461,7 +496,7 @@ export class VirtualSerialTransport implements SerialTransport {
       d => d.attached && this.#matchesFilters(d, filter),
     );
 
-    let chosen: VirtualDevice | undefined;
+    let chosen: DeviceHandle | undefined;
     if (typeof pick === 'function') {
       chosen = candidates.find(pick);
     } else if (pick) {
@@ -496,7 +531,8 @@ export class VirtualSerialTransport implements SerialTransport {
     device.isOpen = true;
     device.openOptions = {...DEFAULT_OPEN_OPTIONS, ...options};
     device._hwWritten = 0;
-    this.#invokeHook(() => device.serialDevice.onOpen(device.openOptions!));
+    this.#invokeHook(() => device.simulatedDevice.onOpen(device.openOptions!));
+    device._notifyOpen(device.openOptions);
     return this.#resolve();
   }
 
@@ -508,7 +544,8 @@ export class VirtualSerialTransport implements SerialTransport {
     if (device) {
       device.isOpen = false;
       device.reading = false;
-      this.#invokeHook(() => device.serialDevice.onClose());
+      this.#invokeHook(() => device.simulatedDevice.onClose());
+      device._notifyClose();
     }
     return this.#resolve();
   }
@@ -535,7 +572,9 @@ export class VirtualSerialTransport implements SerialTransport {
     const bytes = data.map(toByte);
     device.written.push(bytes);
     if (device.flowControl === 'RTS_CTS') device._hwWritten += bytes.length;
-    this.#invokeHook(() => device.serialDevice.onData(Uint8Array.from(bytes)));
+    this.#invokeHook(() =>
+      device.simulatedDevice.onData(Uint8Array.from(bytes)),
+    );
     return this.#resolve();
   }
 
@@ -723,7 +762,7 @@ export class VirtualSerialTransport implements SerialTransport {
         }
       }
       this.#invokeHook(() =>
-        device.serialDevice.onHostSignals({
+        device.simulatedDevice.onHostSignals({
           dataTerminalReady: device.output.dtr,
           requestToSend: device.output.rts,
           break: device.output.brk,
@@ -733,7 +772,7 @@ export class VirtualSerialTransport implements SerialTransport {
     return this.#resolve();
   }
 
-  #toPortId = (d: VirtualDevice): PortId => ({
+  #toPortId = (d: DeviceHandle): PortId => ({
     deviceId: d.deviceId,
     portNumber: d.portNumber,
     usbVendorId: d.usbVendorId,
@@ -742,7 +781,7 @@ export class VirtualSerialTransport implements SerialTransport {
   });
 
   #matchesFilters(
-    device: VirtualDevice,
+    device: DeviceHandle,
     filters: ReadonlyArray<PortFilter>,
   ): boolean {
     if (!filters || filters.length === 0) return true;
@@ -760,7 +799,7 @@ export class VirtualSerialTransport implements SerialTransport {
     });
   }
 
-  #find(deviceId: number, portNumber?: number): VirtualDevice | undefined {
+  #find(deviceId: number, portNumber?: number): DeviceHandle | undefined {
     return this.#devices.find(
       d =>
         d.attached &&