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

package/src/testing/index.ts

@@ -3,40 +3,88 @@
  *
  * Imported via the package subpath:
  *
- *   import {VirtualSerialTransport, installSerialMock}
+ *   import {InMemorySerialTransport, installInMemorySerialTransport}
  *     from 'react-native-web-serial-api/testing';
  *
  * These are reusable building blocks for *consumers'* tests and demos — an
- * in-memory transport and an authorable `SerialDevice` peripheral model — so
+ * in-memory transport and an authorable `SimulatedDevice` peripheral model — so
  * they ship with the package. The library's own spec-compliance suite is NOT
  * here: it lives in `src/__tests__/conformance-suite.ts` (test-only, excluded
  * from the build and the published package). None of this is in the main bundle.
  */
 
 export type {SerialTransport} from '../transport';
-// The injection seam, re-exported here for convenience so a test or the
+// The transport override, re-exported here for convenience so a test or the
 // example's demo mode can flip the global transport from one import.
 export {getUsbSerial, resetUsbSerial, setUsbSerial} from '../UsbSerial';
-export type {InstallSerialMockOptions, SerialMockDevice} from './install';
+// One-call fixture: mount a device sim + drive both sides + await connect.
+export type {
+  DeviceFixtureOptions,
+  MountedDeviceFixture,
+  MountedDeviceFixtures,
+} from './device-fixture';
+export {createDeviceFixture} from './device-fixture';
+// Expose a device simulator over a WebSocket so a real app/emulator can connect
+// to it (same device suite in Jest and on-device). Lazy `ws`, Node-only.
+export type {
+  ExposedDevice,
+  ExposeSimulatedDeviceOptions,
+  WebSocketServerCtor,
+  WebSocketServerLike,
+} from './expose';
+export {exposeSimulatedDevice} from './expose';
+// Dependency-free assertion/stream helpers for writing serial tests.
+export type {ByteReader, RejectionExpectation} from './harness';
+export {
+  assert,
+  assertEqual,
+  assertRejects,
+  bytesEqual,
+  errorMessage,
+  readBytes,
+  withTimeout,
+} from './harness';
+export type {
+  DeviceOptions,
+  FailableOp,
+  InMemorySerialTransportOptions,
+} from './in-memory-serial-transport';
+export {
+  DeviceHandle,
+  InMemorySerialTransport,
+} from './in-memory-serial-transport';
+export type {
+  InstallInMemorySerialTransportOptions,
+  SimulatedTransportDevice,
+} from './install-in-memory-serial-transport';
 // Inject a mock device set into a running app (for on-device / emulator E2E).
-export {installSerialMock} from './install';
+export {installInMemorySerialTransport} from './install-in-memory-serial-transport';
+// The fluent host-side client (reader/writer/readBytes/readUntil/readLine/…).
+export type {ReadOptions, SerialClientOptions} from './serial-client';
+export {
+  createSerialClient,
+  SerialClient,
+} from './serial-client';
 export type {
-  DeviceIdentity,
-  SerialDeviceHost,
-  SerialDeviceOpenOptions,
-  SerialHostSignals,
+  HostSignals,
   SerialInputSignals,
-} from './serial-device';
-// Author a whole simulated peripheral by extending SerialDevice.
+  SimulatedDeviceHost,
+  SimulatedDeviceIdentity,
+  SimulatedDeviceOpenOptions,
+} from './simulated-device';
+// Author a whole simulated peripheral by extending SimulatedDevice.
 export {
-  EchoDevice,
-  LineDevice,
-  SerialDevice,
-  SilentDevice,
-} from './serial-device';
+  LineBufferedDevice,
+  LoopbackDevice,
+  SimulatedDevice,
+  SinkDevice,
+} from './simulated-device';
+// Runtime-agnostic suite runner: one suite, run in Jest + on-device + compare.
 export type {
-  FailableOp,
-  VirtualDeviceOptions,
-  VirtualSerialOptions,
-} from './virtual-serial';
-export {VirtualDevice, VirtualSerialTransport} from './virtual-serial';
+  RunTestSuiteOptions,
+  SerialTest,
+  SerialTestProgress,
+  SerialTestResult,
+  TestClient,
+} from './test-suite';
+export {compareTestResults, runTestSuite} from './test-suite';

package/src/testing/install-in-memory-serial-transport.ts

@@ -0,0 +1,65 @@
+/**
+ * installInMemorySerialTransport — point the library at a simulated device set in one call.
+ *
+ * Built for E2E: call it once at app startup, behind your own env/build flag, to
+ * make `navigator.serial` / this library's `serial` talk to simulated
+ * {@link SimulatedDevice}s instead of real USB hardware while a test driver
+ * (Maestro, Detox, …) exercises the app on a device/emulator.
+ *
+ * @example
+ * // index.js (debug/E2E build only)
+ * import {installInMemorySerialTransport, LoopbackDevice} from 'react-native-web-serial-api/testing';
+ * installInMemorySerialTransport({
+ *   enabled: process.env.RNWS_SERIAL_MOCK === '1',
+ *   devices: [new LoopbackDevice(), new MyThermometer()],
+ * });
+ */
+import {setUsbSerial} from '../UsbSerial';
+import type {
+  DeviceOptions,
+  InMemorySerialTransportOptions,
+} from './in-memory-serial-transport';
+import {InMemorySerialTransport} from './in-memory-serial-transport';
+import {SimulatedDevice} from './simulated-device';
+
+/** A device to register: a SimulatedDevice, optionally with transport options. */
+export type SimulatedTransportDevice =
+  | SimulatedDevice
+  | {device: SimulatedDevice; options?: DeviceOptions};
+
+export type InstallInMemorySerialTransportOptions = {
+  /** The simulated devices to expose. */
+  devices: SimulatedTransportDevice[];
+  /** When false, no mock is installed and `null` is returned. Defaults to true. */
+  enabled?: boolean;
+  /** Transport-level options (latency, chunkSize, …). */
+  transport?: InMemorySerialTransportOptions;
+};
+
+/**
+ * Build an {@link InMemorySerialTransport} from `devices` and install it globally
+ * via {@link setUsbSerial}. SimulatedDevices default to granted USB permission (so
+ * they show up immediately); pass the `{device, options}` form to override.
+ * Returns the transport (handy for driving devices in-test), or `null` when
+ * disabled.
+ */
+export function installInMemorySerialTransport(
+  options: InstallInMemorySerialTransportOptions,
+): InMemorySerialTransport | null {
+  if (options.enabled === false) return null;
+
+  const transport = new InMemorySerialTransport(options.transport);
+  for (const entry of options.devices) {
+    if (entry instanceof SimulatedDevice) {
+      transport.addDevice(entry, {hasPermission: true});
+    } else {
+      transport.addDevice(entry.device, {
+        hasPermission: true,
+        ...entry.options,
+      });
+    }
+  }
+
+  setUsbSerial(transport);
+  return transport;
+}

package/src/testing/serial-client.ts

@@ -0,0 +1,313 @@
+/**
+ * A fluent request/response client over a {@link SerialPort} — the host-side
+ * driver every serial test otherwise hand-rolls (reader + writer, a pending
+ * byte buffer, framed reads with timeouts). Works on ANY SerialPort: the
+ * in-memory {@link InMemorySerialTransport}, a real USB device, or a
+ * WebSocket-backed one — so the same test runs in Jest and on a device.
+ *
+ * @example
+ * const {client} = await mountDeviceFixture(new MyDevice());
+ * await client.open({baudRate: 115200});
+ * await client.write('PING\n');
+ * expect(await client.readLine()).toBe('PONG');
+ * await client.close();
+ */
+import type {SerialOptions, SerialPort} from '../WebSerial';
+import {toBytes} from './simulated-device';
+
+export type ReadOptions = {
+  /** Per-call timeout in ms (overrides the client default). */
+  timeout?: number;
+};
+
+export type SerialClientOptions = {
+  /** Default per-read timeout in ms. Default 2000. */
+  defaultTimeoutMs?: number;
+};
+
+function indexOfSubsequence(haystack: number[], needle: number[]): number {
+  if (needle.length === 0) return 0;
+  outer: for (let i = 0; i + needle.length <= haystack.length; i++) {
+    for (let j = 0; j < needle.length; j++) {
+      if (haystack[i + j] !== needle[j]) continue outer;
+    }
+    return i;
+  }
+  return -1;
+}
+
+export class SerialClient {
+  readonly #port: SerialPort;
+  readonly #defaultTimeout: number;
+
+  #reader: ReadableStreamDefaultReader<Uint8Array> | null = null;
+  #writer: WritableStreamDefaultWriter<Uint8Array> | null = null;
+  #open = false;
+  #done = false;
+  #closed = false;
+  /** Inbound bytes read by the pump but not yet consumed. */
+  readonly #pending: number[] = [];
+  /** Resolvers woken whenever #pending grows or the stream ends. */
+  #waiters: Array<() => void> = [];
+
+  constructor(port: SerialPort, options: SerialClientOptions = {}) {
+    this.#port = port;
+    this.#defaultTimeout = options.defaultTimeoutMs ?? 2000;
+  }
+
+  get port(): SerialPort {
+    return this.#port;
+  }
+
+  get isOpen(): boolean {
+    return this.#open;
+  }
+
+  /** True once the underlying stream has ended (device closed or lost). */
+  get ended(): boolean {
+    return this.#done;
+  }
+
+  /** Open the port (idempotent) and acquire reader + writer; start reading. */
+  async open(options: SerialOptions = {baudRate: 115200}): Promise<this> {
+    if (this.#open) return this;
+    await this.#port.open(options);
+    this.#reader = this.#port.readable!.getReader();
+    this.#writer = this.#port.writable!.getWriter();
+    this.#open = true;
+    this.#done = false;
+    this.#closed = false;
+    void this.#pump();
+    return this;
+  }
+
+  /** Background reader: drains the stream into #pending and wakes waiters. */
+  async #pump(): Promise<void> {
+    const reader = this.#reader;
+    /* istanbul ignore next */
+    if (!reader) return;
+    try {
+      while (!this.#closed) {
+        const {done, value} = await reader.read();
+        if (done) break;
+        /* istanbul ignore else — InMemorySerialTransport never emits empty chunks */
+        if (value && value.length > 0) {
+          for (let i = 0; i < value.length; i++) this.#pending.push(value[i]);
+          this.#wake();
+        }
+      }
+    } catch {
+      // read errored (e.g. device lost) — surface as end-of-stream to waiters
+    } finally {
+      this.#done = true;
+      this.#wake();
+    }
+  }
+
+  #wake(): void {
+    const waiters = this.#waiters;
+    this.#waiters = [];
+    for (const w of waiters) w();
+  }
+
+  /** Resolve on the next #pending change / stream end, or reject after `ms`. */
+  #waitForChange(ms: number): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#waiters = this.#waiters.filter(w => w !== waiter);
+        reject(new Error('read timeout'));
+      }, ms);
+      const waiter = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+      this.#waiters.push(waiter);
+    });
+  }
+
+  /**
+   * Block until `ready(buffer)` returns a non-negative count of bytes to
+   * consume, then splice and return them. Rejects with `label` on timeout.
+   */
+  async #consume(
+    ready: (buffer: number[]) => number | false,
+    timeoutMs: number,
+    label: () => string,
+  ): Promise<Uint8Array> {
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      const take = ready(this.#pending);
+      if (take !== false) {
+        return Uint8Array.from(this.#pending.splice(0, take));
+      }
+      if (this.#done) {
+        if (this.#pending.length > 0) {
+          // Return whatever is buffered rather than hang on a closed stream.
+          return Uint8Array.from(this.#pending.splice(0, this.#pending.length));
+        }
+        // The transport can surface end-of-stream before the final queued data
+        // event has been pumped into #pending. Give that last turn a chance to
+        // land before we conclude there is nothing buffered.
+        await new Promise(resolve => setTimeout(resolve, 0));
+        /* istanbul ignore next -- race-guard checks again after yielding */
+        if (this.#pending.length === 0) {
+          return Uint8Array.from([]);
+        }
+        /* istanbul ignore next -- race-guard re-enters the loop after yielding */
+        continue;
+      }
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) throw new Error(label());
+      try {
+        await this.#waitForChange(remaining);
+      } catch {
+        throw new Error(label());
+      }
+    }
+  }
+
+  /** Write bytes (string → char codes & 0xff). */
+  async write(data: number[] | Uint8Array | string): Promise<void> {
+    if (!this.#writer) throw new Error('SerialClient is not open.');
+    await this.#writer.write(Uint8Array.from(toBytes(data)));
+  }
+
+  /** Read exactly `n` bytes (fewer only if the stream ends first). */
+  readBytes(n: number, options: ReadOptions = {}): Promise<Uint8Array> {
+    const timeout = options.timeout ?? this.#defaultTimeout;
+    return this.#consume(
+      buf => (buf.length >= n ? n : false),
+      timeout,
+      () => `timed out reading ${n} bytes (got ${this.#pending.length})`,
+    );
+  }
+
+  /** Read up to and including `delimiter`; returns the slice (incl. delimiter). */
+  readUntil(
+    delimiter: number[] | Uint8Array | string,
+    options: ReadOptions = {},
+  ): Promise<Uint8Array> {
+    const needle = toBytes(delimiter);
+    const timeout = options.timeout ?? this.#defaultTimeout;
+    return this.#consume(
+      buf => {
+        const idx = indexOfSubsequence(buf, needle);
+        return idx < 0 ? false : idx + needle.length;
+      },
+      timeout,
+      () => `timed out reading until delimiter`,
+    );
+  }
+
+  /** Read one `\n`-terminated line as text (trailing CR/LF stripped). */
+  async readLine(options: ReadOptions = {}): Promise<string> {
+    const bytes = await this.readUntil('\n', options);
+    let end = bytes.length;
+    if (end > 0 && bytes[end - 1] === 0x0a) end--;
+    if (end > 0 && bytes[end - 1] === 0x0d) end--;
+    return String.fromCharCode(...bytes.subarray(0, end));
+  }
+
+  /**
+   * Frame a message: `predicate(buffer)` returns the number of leading bytes the
+   * next frame occupies (consumed and returned), or `false` to wait for more.
+   */
+  readMatching(
+    predicate: (buffer: Uint8Array) => number | false,
+    options: ReadOptions = {},
+  ): Promise<Uint8Array> {
+    const timeout = options.timeout ?? this.#defaultTimeout;
+    return this.#consume(
+      buf => predicate(Uint8Array.from(buf)),
+      timeout,
+      () => `timed out waiting for a frame`,
+    );
+  }
+
+  /**
+   * Resolve with the next chunk of buffered inbound bytes (one or more), or an
+   * empty array once the stream has ended. Rejects on timeout. Use this to layer
+   * your own framing/decoder (SLIP, COBS, length-prefix, …) on the byte stream;
+   * pair it with {@link ended} to stop when the device goes away.
+   */
+  readAvailable(options: ReadOptions = {}): Promise<Uint8Array> {
+    const timeout = options.timeout ?? this.#defaultTimeout;
+    return this.#consume(
+      buf => (buf.length > 0 ? buf.length : false),
+      timeout,
+      () => `timed out waiting for data`,
+    );
+  }
+
+  /** Assert no inbound bytes arrive for `ms`. Rejects if any do. */
+  async expectIdle(ms: number): Promise<void> {
+    if (this.#pending.length > 0) {
+      throw new Error(
+        `expected no inbound data but ${this.#pending.length} byte(s) were already buffered`,
+      );
+    }
+    try {
+      await this.#waitForChange(ms);
+    } catch {
+      return; // no change within the window — idle, as expected
+    }
+    if (this.#pending.length > 0) {
+      throw new Error(
+        `expected no inbound data for ${ms}ms but received ${this.#pending.length} byte(s)`,
+      );
+    }
+    // stream ended with no data — also idle
+  }
+
+  /** Drop any buffered-but-unread inbound bytes. */
+  drain(): void {
+    this.#pending.length = 0;
+  }
+
+  /** Release reader + writer locks and close the port. Safe to call twice. */
+  async close(): Promise<void> {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#wake();
+    if (this.#reader) {
+      try {
+        await this.#reader.cancel();
+      } catch {
+        // ignore
+      }
+      try {
+        this.#reader.releaseLock();
+      } catch {
+        // already released
+      }
+      this.#reader = null;
+    }
+    if (this.#writer) {
+      try {
+        await this.#writer.close();
+      } catch {
+        // ignore
+      }
+      try {
+        this.#writer.releaseLock();
+      } catch {
+        // already released
+      }
+      this.#writer = null;
+    }
+    this.#open = false;
+    try {
+      await this.#port.close();
+    } catch {
+      // already closed
+    }
+  }
+}
+
+/** Create a {@link SerialClient} for any SerialPort (virtual, real, or WS). */
+export function createSerialClient(
+  port: SerialPort,
+  options?: SerialClientOptions,
+): SerialClient {
+  return new SerialClient(port, options);
+}

package/src/testing/{serial-device.ts → simulated-device.ts}

@@ -1,15 +1,15 @@
 /**
- * SerialDevice — author a complete simulated serial peripheral.
+ * SimulatedDevice — author a complete simulated serial peripheral.
  *
  * Extend the class and override the lifecycle hooks to model a real device's
  * whole behaviour (firmware/protocol): react to `open()`, to bytes the host
  * writes, to control-signal changes, and stream data back over time. It is
- * hosted by a {@link VirtualSerialTransport} ({@link ./virtual-serial}) and is
+ * hosted by an {@link InMemorySerialTransport} ({@link ./virtual-serial}) and is
  * free of any `react-native` dependency, so the same device runs under Jest,
  * in a browser, and inside a React Native app on a device/emulator (for E2E).
  *
  * @example
- * class Thermometer extends SerialDevice {
+ * class Thermometer extends SimulatedDevice {
  *   usbVendorId = 0x0403;
  *   usbProductId = 0x6001;
  *   #timer?: ReturnType<typeof setInterval>;
@@ -26,7 +26,7 @@
 import type {OpenOptions} from '../transport';
 
 /** The negotiated connection parameters (native parity code: 0 none/1 odd/2 even). */
-export type SerialDeviceOpenOptions = Required<OpenOptions>;
+export type SimulatedDeviceOpenOptions = Required<OpenOptions>;
 
 /** Device-asserted input signals — what the host reads via getSignals(). */
 export type SerialInputSignals = {
@@ -37,22 +37,22 @@ export type SerialInputSignals = {
 };
 
 /** Host-asserted output signals (DTR/RTS/break) the device observes. */
-export type SerialHostSignals = {
+export type HostSignals = {
   dataTerminalReady: boolean;
   requestToSend: boolean;
   break: boolean;
 };
 
 /**
- * The handle a {@link SerialDevice} uses to talk back to the host. Provided by
- * the transport; you normally use the `protected` helpers on `SerialDevice`
+ * The handle a {@link SimulatedDevice} uses to talk back to the host. Provided by
+ * the transport; you normally use the `protected` helpers on `SimulatedDevice`
  * rather than this directly.
  */
-export interface SerialDeviceHost {
+export interface SimulatedDeviceHost {
   readonly deviceId: number;
   readonly portNumber: number;
   readonly isOpen: boolean;
-  readonly openOptions: SerialDeviceOpenOptions | null;
+  readonly openOptions: SimulatedDeviceOpenOptions | null;
   send(bytes: number[]): void;
   raiseError(message: string, name?: string): void;
   setSignals(signals: SerialInputSignals): void;
@@ -72,7 +72,7 @@ export function toBytes(data: number[] | Uint8Array | string): number[] {
  * care about (all default to no-ops and may be async) and use the `protected`
  * helpers to drive the host.
  */
-export abstract class SerialDevice {
+export abstract class SimulatedDevice {
   /** USB Vendor ID this device reports for enumeration. */
   abstract readonly usbVendorId: number;
   /** USB Product ID this device reports for enumeration. */
@@ -80,10 +80,10 @@ export abstract class SerialDevice {
   /** Optional USB serial number. */
   readonly serialNumber?: string;
 
-  #host: SerialDeviceHost | null = null;
+  #host: SimulatedDeviceHost | null = null;
 
-  /** @internal Bind the transport host (called by VirtualSerialTransport). */
-  _bind(host: SerialDeviceHost): void {
+  /** @internal Bind the transport host (called by InMemorySerialTransport). */
+  _bind(host: SimulatedDeviceHost): void {
     this.#host = host;
   }
 
@@ -107,7 +107,7 @@ export abstract class SerialDevice {
   }
 
   /** The parameters the host opened the port with, or null when closed. */
-  protected get openOptions(): SerialDeviceOpenOptions | null {
+  protected get openOptions(): SimulatedDeviceOpenOptions | null {
     return this.#host?.openOptions ?? null;
   }
 
@@ -120,29 +120,29 @@ export abstract class SerialDevice {
   }
 
   /** The host opened the port. */
-  onOpen(_options: SerialDeviceOpenOptions): void | Promise<void> {}
+  onOpen(_options: SimulatedDeviceOpenOptions): void | Promise<void> {}
   /** The host wrote bytes to the device. */
   onData(_data: Uint8Array): void | Promise<void> {}
   /** The host changed DTR/RTS/break. */
-  onHostSignals(_signals: SerialHostSignals): void | Promise<void> {}
+  onHostSignals(_signals: HostSignals): void | Promise<void> {}
   /** The host closed the port. */
   onClose(): void | Promise<void> {}
 }
 
-/** Optional USB identity for the built-in devices. */
-export type DeviceIdentity = {
+/** Optional USB identity for built-in devices. */
+export type SimulatedDeviceIdentity = {
   usbVendorId?: number;
   usbProductId?: number;
   serialNumber?: string;
 };
 
 /** A loopback device: every byte written is echoed straight back. */
-export class EchoDevice extends SerialDevice {
+export class LoopbackDevice extends SimulatedDevice {
   readonly usbVendorId: number;
   readonly usbProductId: number;
   readonly serialNumber?: string;
 
-  constructor(identity: DeviceIdentity = {}) {
+  constructor(identity: SimulatedDeviceIdentity = {}) {
     super();
     this.usbVendorId = identity.usbVendorId ?? 0x0403;
     this.usbProductId = identity.usbProductId ?? 0x6001;
@@ -158,7 +158,7 @@ export class EchoDevice extends SerialDevice {
  * Base for a line-oriented command/response device: buffers incoming bytes and
  * calls {@link onLine} for each `\n`-terminated line (trailing CR/LF stripped).
  */
-export abstract class LineDevice extends SerialDevice {
+export abstract class LineBufferedDevice extends SimulatedDevice {
   #buffer = '';
 
   /** Handle one line received from the host. */
@@ -179,12 +179,12 @@ export abstract class LineDevice extends SerialDevice {
 }
 
 /** A device that accepts writes but never sends anything back. */
-export class SilentDevice extends SerialDevice {
+export class SinkDevice extends SimulatedDevice {
   readonly usbVendorId: number;
   readonly usbProductId: number;
   readonly serialNumber?: string;
 
-  constructor(identity: DeviceIdentity = {}) {
+  constructor(identity: SimulatedDeviceIdentity = {}) {
     super();
     this.usbVendorId = identity.usbVendorId ?? 0x0403;
     this.usbProductId = identity.usbProductId ?? 0x6001;