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

package/src/testing/index.ts

@@ -0,0 +1,90 @@
+/**
+ * Testing & on-device-demo entry point.
+ *
+ * Imported via the package subpath:
+ *
+ *   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 `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 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';
+// 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 {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 {
+  HostSignals,
+  SerialInputSignals,
+  SimulatedDeviceHost,
+  SimulatedDeviceIdentity,
+  SimulatedDeviceOpenOptions,
+} from './simulated-device';
+// Author a whole simulated peripheral by extending SimulatedDevice.
+export {
+  LineBufferedDevice,
+  LoopbackDevice,
+  SimulatedDevice,
+  SinkDevice,
+} from './simulated-device';
+// Runtime-agnostic suite runner: one suite, run in Jest + on-device + compare.
+export type {
+  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/simulated-device.ts

@@ -0,0 +1,193 @@
+/**
+ * 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 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 SimulatedDevice {
+ *   usbVendorId = 0x0403;
+ *   usbProductId = 0x6001;
+ *   #timer?: ReturnType<typeof setInterval>;
+ *   onOpen() {
+ *     this.#timer = setInterval(() => this.send(`${20 + Math.random()}C\r\n`), 1000);
+ *   }
+ *   onData(bytes) {                       // host wrote a command
+ *     if (String.fromCharCode(...bytes).trim() === 'ID?') this.send('ACME-TEMP\r\n');
+ *   }
+ *   onClose() { clearInterval(this.#timer); }
+ * }
+ * transport.addDevice(new Thermometer(), {hasPermission: true});
+ */
+import type {OpenOptions} from '../transport';
+
+/** The negotiated connection parameters (native parity code: 0 none/1 odd/2 even). */
+export type SimulatedDeviceOpenOptions = Required<OpenOptions>;
+
+/** Device-asserted input signals — what the host reads via getSignals(). */
+export type SerialInputSignals = {
+  dataCarrierDetect?: boolean;
+  clearToSend?: boolean;
+  ringIndicator?: boolean;
+  dataSetReady?: boolean;
+};
+
+/** Host-asserted output signals (DTR/RTS/break) the device observes. */
+export type HostSignals = {
+  dataTerminalReady: boolean;
+  requestToSend: boolean;
+  break: boolean;
+};
+
+/**
+ * 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 SimulatedDeviceHost {
+  readonly deviceId: number;
+  readonly portNumber: number;
+  readonly isOpen: boolean;
+  readonly openOptions: SimulatedDeviceOpenOptions | null;
+  send(bytes: number[]): void;
+  raiseError(message: string, name?: string): void;
+  setSignals(signals: SerialInputSignals): void;
+}
+
+/** Coerce a payload into a byte array (string → char codes, & 0xff). */
+export function toBytes(data: number[] | Uint8Array | string): number[] {
+  if (typeof data === 'string') {
+    return Array.from(data, c => c.charCodeAt(0) & 0xff);
+  }
+  if (data instanceof Uint8Array) return Array.from(data);
+  return data.map(n => n & 0xff);
+}
+
+/**
+ * Base class for a simulated serial peripheral. Override the `on*` hooks you
+ * care about (all default to no-ops and may be async) and use the `protected`
+ * helpers to drive the host.
+ */
+export abstract class SimulatedDevice {
+  /** USB Vendor ID this device reports for enumeration. */
+  abstract readonly usbVendorId: number;
+  /** USB Product ID this device reports for enumeration. */
+  abstract readonly usbProductId: number;
+  /** Optional USB serial number. */
+  readonly serialNumber?: string;
+
+  #host: SimulatedDeviceHost | null = null;
+
+  /** @internal Bind the transport host (called by InMemorySerialTransport). */
+  _bind(host: SimulatedDeviceHost): void {
+    this.#host = host;
+  }
+
+  /** Send bytes to the host (they appear on `port.readable`). */
+  protected send(data: number[] | Uint8Array | string): void {
+    this.#host?.send(toBytes(data));
+  }
+
+  /**
+   * Raise a typed read error on the host's readable stream. `name` is the W3C
+   * error type, e.g. "BreakError", "BufferOverrunError", "FramingError",
+   * "ParityError" (defaults to "NetworkError").
+   */
+  protected raiseError(message: string, name?: string): void {
+    this.#host?.raiseError(message, name);
+  }
+
+  /** Set device-asserted input signals (DCD/CTS/RI/DSR) the host can read. */
+  protected setSignals(signals: SerialInputSignals): void {
+    this.#host?.setSignals(signals);
+  }
+
+  /** The parameters the host opened the port with, or null when closed. */
+  protected get openOptions(): SimulatedDeviceOpenOptions | null {
+    return this.#host?.openOptions ?? null;
+  }
+
+  protected get deviceId(): number {
+    return this.#host?.deviceId ?? -1;
+  }
+
+  protected get portNumber(): number {
+    return this.#host?.portNumber ?? 0;
+  }
+
+  /** The host opened the port. */
+  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: HostSignals): void | Promise<void> {}
+  /** The host closed the port. */
+  onClose(): void | Promise<void> {}
+}
+
+/** 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 LoopbackDevice extends SimulatedDevice {
+  readonly usbVendorId: number;
+  readonly usbProductId: number;
+  readonly serialNumber?: string;
+
+  constructor(identity: SimulatedDeviceIdentity = {}) {
+    super();
+    this.usbVendorId = identity.usbVendorId ?? 0x0403;
+    this.usbProductId = identity.usbProductId ?? 0x6001;
+    this.serialNumber = identity.serialNumber;
+  }
+
+  onData(data: Uint8Array): void {
+    this.send(data);
+  }
+}
+
+/**
+ * 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 LineBufferedDevice extends SimulatedDevice {
+  #buffer = '';
+
+  /** Handle one line received from the host. */
+  abstract onLine(line: string): void | Promise<void>;
+
+  onData(data: Uint8Array): void {
+    for (let i = 0; i < data.length; i++) {
+      this.#buffer += String.fromCharCode(data[i]);
+    }
+    let nl = this.#buffer.indexOf('\n');
+    while (nl >= 0) {
+      const line = this.#buffer.slice(0, nl).replace(/\r$/, '');
+      this.#buffer = this.#buffer.slice(nl + 1);
+      void this.onLine(line);
+      nl = this.#buffer.indexOf('\n');
+    }
+  }
+}
+
+/** A device that accepts writes but never sends anything back. */
+export class SinkDevice extends SimulatedDevice {
+  readonly usbVendorId: number;
+  readonly usbProductId: number;
+  readonly serialNumber?: string;
+
+  constructor(identity: SimulatedDeviceIdentity = {}) {
+    super();
+    this.usbVendorId = identity.usbVendorId ?? 0x0403;
+    this.usbProductId = identity.usbProductId ?? 0x6001;
+    this.serialNumber = identity.serialNumber;
+  }
+}