react-native-web-serial-api 0.0.3 → 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;
+}