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

package/lib/typescript/src/testing/in-memory-serial-transport.d.ts

@@ -0,0 +1,216 @@
+/**
+ * InMemorySerialTransport — an in-memory {@link SerialTransport} for tests and
+ * on-device demos.
+ *
+ * It implements the exact same interface the production `UsbSerialModule` does,
+ * but talks to simulated devices instead of real USB hardware. Because it has
+ * **no `react-native` dependency**, the same instance drives:
+ *
+ *   - Jest/Node unit tests and the conformance suite,
+ *   - the example app's "virtual device" mode on a real Android device, and
+ *   - the example app running in a browser (react-native-web).
+ *
+ * Inject it via `new Serial(transport)` or globally with `setUsbSerial(transport)`.
+ *
+ * @example
+ * 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});
+ * // writes to port.writable now come back on port.readable (echo)
+ */
+import type { ConnectEvent, ControlLine, DataEvent, ErrorEvent, FlowControl, OpenOptions, PortFilter, PortId, PortPickerLabels, SerialTransport, Subscription } from '../transport';
+import type { SimulatedDevice } from './simulated-device';
+/** 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. */
+    portNumber?: number;
+    /** Override the device's serialNumber for enumeration. */
+    serialNumber?: string;
+    /**
+     * Cross-wire output signals onto inputs the way a null-modem/loopback plug
+     * would (DTR→DSR+DCD, RTS→CTS) so getSignals() reflects setSignals().
+     * Defaults to true.
+     */
+    loopbackSignals?: boolean;
+    /**
+     * When the port is opened with hardware (RTS/CTS) flow control, the device
+     * de-asserts CTS once this many bytes have been written without the receiver
+     * draining — modelling a full receive buffer. Defaults to 256.
+     */
+    flowControlThreshold?: number;
+};
+export type InMemorySerialTransportOptions = {
+    /** Devices to register on construction (same as calling addDevice). */
+    devices?: SimulatedDevice[];
+    /**
+     * Delay (ms) applied to async operations and to inbound data delivery.
+     * 0 (default) resolves on a microtask — deterministic for Jest. A small
+     * positive value makes streaming feel realistic on a device.
+     */
+    latencyMs?: number;
+    /**
+     * Whether showPortPicker() grants USB permission to the chosen device,
+     * mirroring the real Android picker. Defaults to true.
+     */
+    autoGrantPermission?: boolean;
+    /**
+     * If set, inbound data larger than this is delivered as several `onData`
+     * events of at most this many bytes — modelling how a real serial port hands
+     * data up in chunks. 0/undefined delivers each write's reply in one event.
+     */
+    chunkSize?: number;
+};
+/** Operations whose next invocation can be made to fail (error injection). */
+export type FailableOp = 'open' | 'close' | 'write' | 'startReading' | 'stopReading' | 'setSignals' | 'getSignals';
+type OutputSignals = {
+    dtr: boolean;
+    rts: boolean;
+    brk: boolean;
+};
+type InputSignals = {
+    dcd: boolean;
+    cts: boolean;
+    ri: boolean;
+    dsr: boolean;
+};
+/**
+ * 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 declare class DeviceHandle {
+    #private;
+    readonly usbVendorId: number;
+    readonly usbProductId: number;
+    readonly portNumber: number;
+    serialNumber: string;
+    /** Reassigned on every (re)attach, mirroring Android's behaviour. */
+    deviceId: number;
+    attached: boolean;
+    hasPermission: boolean;
+    isOpen: boolean;
+    reading: boolean;
+    /** The hosted behaviour. */
+    readonly simulatedDevice: SimulatedDevice;
+    loopbackSignals: boolean;
+    flowControl: FlowControl;
+    flowControlThreshold: number;
+    openOptions: Required<OpenOptions> | null;
+    /**
+     * When non-null, the device delivers at most this many bytes before raising a
+     * `BufferOverrunError` — models a fixed-size receive buffer overflowing.
+     */
+    overrunLimit: number | null;
+    _rxDelivered: number;
+    _overran: boolean;
+    _hwWritten: number;
+    readonly output: OutputSignals;
+    readonly input: InputSignals;
+    /** Every byte frame the host has written to this device, in order. */
+    readonly written: number[][];
+    constructor(transport: InMemorySerialTransport, deviceId: number, device: SimulatedDevice, options: DeviceOptions);
+    /** Push inbound bytes to the host as if the device sent them unprompted. */
+    push(bytes: number[] | Uint8Array): void;
+    /**
+     * Raise a read error on the host's readable stream. `name` is the W3C error
+     * type (e.g. "BreakError", "BufferOverrunError"); the current polyfill ignores
+     * it and surfaces "NetworkError" regardless (a documented spec gap).
+     */
+    emitError(message: string, name?: string): void;
+    /**
+     * Make the device deliver at most `bytes` bytes and then raise a
+     * `BufferOverrunError`, modelling a receive buffer of that size overflowing.
+     */
+    overrunAfter(bytes: number): this;
+    /** Make the next call to `op` reject once (error injection). */
+    failNext(op: FailableOp): this;
+    /** @internal consume a queued failure for `op`. */
+    _consumeFail(op: FailableOp): boolean;
+    /** Directly set device-asserted input signals (DCD/CTS/RI/DSR). */
+    setInputSignals(signals: Partial<InputSignals>): void;
+    /** Physically attach (or re-attach) this device — fires "connect". */
+    attach(): void;
+    /** Physically detach this device — fires "disconnect". */
+    detach(): void;
+    /** Simulate an unplug while open: errors the open stream, then disconnects. */
+    loseDevice(): 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>>;
+    /** Resolve when the host closes this port (immediately if not open). */
+    whenClosed(): Promise<void>;
+    /** @internal The transport calls this right after the port opens. */
+    _notifyOpen(options: Required<OpenOptions>): void;
+    /** @internal The transport calls this right after the port closes/detaches. */
+    _notifyClose(): void;
+}
+type Listener<E> = (event: E) => void;
+/**
+ * In-memory transport backing one or more {@link DeviceHandle}s.
+ */
+export declare class InMemorySerialTransport implements SerialTransport {
+    #private;
+    constructor(options?: InMemorySerialTransportOptions);
+    /** All devices known to the transport (attached or not). */
+    get devices(): readonly DeviceHandle[];
+    /**
+     * 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(simulatedDevice: SimulatedDevice, options?: DeviceOptions): DeviceHandle;
+    /** Remove a device entirely; detaches it first if attached. */
+    removeDevice(device: DeviceHandle): void;
+    /** (Re)attach a device, assigning it a fresh deviceId, and fire "connect". */
+    attach(device: DeviceHandle): void;
+    /** Detach a device and fire "disconnect"; any open port becomes closed. */
+    detach(device: DeviceHandle, lost?: boolean): void;
+    /** Simulate an unplug while open: error the stream first, then disconnect. */
+    loseDevice(device: DeviceHandle): void;
+    /** Script the next showPortPicker() resolution (a device or a predicate). */
+    selectNextPort(target: DeviceHandle | ((d: DeviceHandle) => boolean)): void;
+    /** Make the next showPortPicker() reject (user cancelled / no port). */
+    rejectNextPortPicker(): void;
+    /** @internal deliver inbound bytes to the host's readable stream. */
+    _deliver(device: DeviceHandle, data: number[]): void;
+    /** @internal raise a read error for a device's open port. */
+    _error(device: DeviceHandle, message: string, name?: string): void;
+    findAllDrivers(): Promise<ReadonlyArray<PortId>>;
+    showPortPicker(filter: ReadonlyArray<PortFilter>, _labels?: PortPickerLabels): Promise<PortId>;
+    requestPermission(deviceId: number): Promise<boolean>;
+    open(deviceId: number, portNumber: number, options: OpenOptions): Promise<void>;
+    close(deviceId: number, portNumber: number): Promise<void>;
+    isOpen(deviceId: number, portNumber: number): boolean;
+    write(deviceId: number, portNumber: number, data: number[], _timeout?: number): Promise<void>;
+    startReading(deviceId: number, portNumber: number): Promise<void>;
+    stopReading(deviceId: number, portNumber: number): Promise<void>;
+    setParameters(deviceId: number, portNumber: number, options: OpenOptions): Promise<void>;
+    setDTR(deviceId: number, portNumber: number, value: boolean): Promise<void>;
+    setRTS(deviceId: number, portNumber: number, value: boolean): Promise<void>;
+    setBreak(deviceId: number, portNumber: number, value: boolean): Promise<void>;
+    getDTR(deviceId: number, portNumber: number): Promise<boolean>;
+    getRTS(deviceId: number, portNumber: number): Promise<boolean>;
+    getCD(deviceId: number, portNumber: number): Promise<boolean>;
+    getCTS(deviceId: number, portNumber: number): Promise<boolean>;
+    getRI(deviceId: number, portNumber: number): Promise<boolean>;
+    getDSR(deviceId: number, portNumber: number): Promise<boolean>;
+    getControlLines(deviceId: number, portNumber: number): Promise<ControlLine[]>;
+    getSupportedControlLines(_deviceId: number, _portNumber: number): Promise<ControlLine[]>;
+    setFlowControl(deviceId: number, portNumber: number, flowControl: FlowControl): Promise<void>;
+    getFlowControl(deviceId: number, portNumber: number): Promise<FlowControl>;
+    getSupportedFlowControl(_deviceId: number, _portNumber: number): Promise<FlowControl[]>;
+    purgeHwBuffers(_deviceId: number, _portNumber: number, _purgeWriteBuffers: boolean, _purgeReadBuffers: boolean): Promise<void>;
+    getSerial(deviceId: number, portNumber: number): Promise<string>;
+    onData(listener: Listener<DataEvent>): Subscription;
+    onError(listener: Listener<ErrorEvent>): Subscription;
+    onConnect(listener: Listener<ConnectEvent>): Subscription;
+    onDisconnect(listener: Listener<ConnectEvent>): Subscription;
+}
+export {};
+//# sourceMappingURL=in-memory-serial-transport.d.ts.map

package/lib/typescript/src/testing/in-memory-serial-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-serial-transport.d.ts","sourceRoot":"","sources":["../../../../src/testing/in-memory-serial-transport.ts"],"names":[],"mappings":"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"}

package/lib/typescript/src/testing/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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';
+export { getUsbSerial, resetUsbSerial, setUsbSerial } from '../UsbSerial';
+export type { DeviceFixtureOptions, MountedDeviceFixture, MountedDeviceFixtures, } from './device-fixture';
+export { createDeviceFixture } from './device-fixture';
+export type { ExposedDevice, ExposeSimulatedDeviceOptions, WebSocketServerCtor, WebSocketServerLike, } from './expose';
+export { exposeSimulatedDevice } from './expose';
+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';
+export { installInMemorySerialTransport } from './install-in-memory-serial-transport';
+export type { ReadOptions, SerialClientOptions } from './serial-client';
+export { createSerialClient, SerialClient, } from './serial-client';
+export type { HostSignals, SerialInputSignals, SimulatedDeviceHost, SimulatedDeviceIdentity, SimulatedDeviceOpenOptions, } from './simulated-device';
+export { LineBufferedDevice, LoopbackDevice, SimulatedDevice, SinkDevice, } from './simulated-device';
+export type { RunTestSuiteOptions, SerialTest, SerialTestProgress, SerialTestResult, TestClient, } from './test-suite';
+export { compareTestResults, runTestSuite } from './test-suite';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,YAAY,EAAC,eAAe,EAAC,MAAM,cAAc,CAAC;AAGlD,OAAO,EAAC,YAAY,EAAE,cAAc,EAAE,YAAY,EAAC,MAAM,cAAc,CAAC;AAExE,YAAY,EACV,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAC,mBAAmB,EAAC,MAAM,kBAAkB,CAAC;AAGrD,YAAY,EACV,aAAa,EACb,4BAA4B,EAC5B,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAC,qBAAqB,EAAC,MAAM,UAAU,CAAC;AAE/C,YAAY,EAAC,UAAU,EAAE,oBAAoB,EAAC,MAAM,WAAW,CAAC;AAChE,OAAO,EACL,MAAM,EACN,WAAW,EACX,aAAa,EACb,UAAU,EACV,YAAY,EACZ,SAAS,EACT,WAAW,GACZ,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,aAAa,EACb,UAAU,EACV,8BAA8B,GAC/B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,YAAY,EACZ,uBAAuB,GACxB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EACV,qCAAqC,EACrC,wBAAwB,GACzB,MAAM,sCAAsC,CAAC;AAE9C,OAAO,EAAC,8BAA8B,EAAC,MAAM,sCAAsC,CAAC;AAEpF,YAAY,EAAC,WAAW,EAAE,mBAAmB,EAAC,MAAM,iBAAiB,CAAC;AACtE,OAAO,EACL,kBAAkB,EAClB,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,UAAU,GACX,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACV,mBAAmB,EACnB,UAAU,EACV,kBAAkB,EAClB,gBAAgB,EAChB,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,OAAO,EAAC,kBAAkB,EAAE,YAAY,EAAC,MAAM,cAAc,CAAC"}

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

@@ -0,0 +1,25 @@
+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 declare function installInMemorySerialTransport(options: InstallInMemorySerialTransportOptions): InMemorySerialTransport | null;
+//# sourceMappingURL=install-in-memory-serial-transport.d.ts.map

package/lib/typescript/src/testing/install-in-memory-serial-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-in-memory-serial-transport.d.ts","sourceRoot":"","sources":["../../../../src/testing/install-in-memory-serial-transport.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EACV,aAAa,EACb,8BAA8B,EAC/B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAC,uBAAuB,EAAC,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAC,eAAe,EAAC,MAAM,oBAAoB,CAAC;AAEnD,kFAAkF;AAClF,MAAM,MAAM,wBAAwB,GAChC,eAAe,GACf;IAAC,MAAM,EAAE,eAAe,CAAC;IAAC,OAAO,CAAC,EAAE,aAAa,CAAA;CAAC,CAAC;AAEvD,MAAM,MAAM,qCAAqC,GAAG;IAClD,uCAAuC;IACvC,OAAO,EAAE,wBAAwB,EAAE,CAAC;IACpC,iFAAiF;IACjF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uDAAuD;IACvD,SAAS,CAAC,EAAE,8BAA8B,CAAC;CAC5C,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,qCAAqC,GAC7C,uBAAuB,GAAG,IAAI,CAiBhC"}

package/lib/typescript/src/testing/serial-client.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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';
+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;
+};
+export declare class SerialClient {
+    #private;
+    constructor(port: SerialPort, options?: SerialClientOptions);
+    get port(): SerialPort;
+    get isOpen(): boolean;
+    /** True once the underlying stream has ended (device closed or lost). */
+    get ended(): boolean;
+    /** Open the port (idempotent) and acquire reader + writer; start reading. */
+    open(options?: SerialOptions): Promise<this>;
+    /** Write bytes (string → char codes & 0xff). */
+    write(data: number[] | Uint8Array | string): Promise<void>;
+    /** Read exactly `n` bytes (fewer only if the stream ends first). */
+    readBytes(n: number, options?: ReadOptions): Promise<Uint8Array>;
+    /** Read up to and including `delimiter`; returns the slice (incl. delimiter). */
+    readUntil(delimiter: number[] | Uint8Array | string, options?: ReadOptions): Promise<Uint8Array>;
+    /** Read one `\n`-terminated line as text (trailing CR/LF stripped). */
+    readLine(options?: ReadOptions): Promise<string>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /** Assert no inbound bytes arrive for `ms`. Rejects if any do. */
+    expectIdle(ms: number): Promise<void>;
+    /** Drop any buffered-but-unread inbound bytes. */
+    drain(): void;
+    /** Release reader + writer locks and close the port. Safe to call twice. */
+    close(): Promise<void>;
+}
+/** Create a {@link SerialClient} for any SerialPort (virtual, real, or WS). */
+export declare function createSerialClient(port: SerialPort, options?: SerialClientOptions): SerialClient;
+//# sourceMappingURL=serial-client.d.ts.map

package/lib/typescript/src/testing/serial-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serial-client.d.ts","sourceRoot":"","sources":["../../../../src/testing/serial-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAC,aAAa,EAAE,UAAU,EAAC,MAAM,cAAc,CAAC;AAG5D,MAAM,MAAM,WAAW,GAAG;IACxB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,oDAAoD;IACpD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAaF,qBAAa,YAAY;;gBAcX,IAAI,EAAE,UAAU,EAAE,OAAO,GAAE,mBAAwB;IAK/D,IAAI,IAAI,IAAI,UAAU,CAErB;IAED,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,yEAAyE;IACzE,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,6EAA6E;IACvE,IAAI,CAAC,OAAO,GAAE,aAAkC,GAAG,OAAO,CAAC,IAAI,CAAC;IAiGtE,gDAAgD;IAC1C,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhE,oEAAoE;IACpE,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IASpE,iFAAiF;IACjF,SAAS,CACP,SAAS,EAAE,MAAM,EAAE,GAAG,UAAU,GAAG,MAAM,EACzC,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC;IAatB,uEAAuE;IACjE,QAAQ,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;IAQ1D;;;OAGG;IACH,YAAY,CACV,SAAS,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,GAAG,KAAK,EACjD,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC;IAStB;;;;;OAKG;IACH,aAAa,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAS7D,kEAAkE;IAC5D,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB3C,kDAAkD;IAClD,KAAK,IAAI,IAAI;IAIb,4EAA4E;IACtE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAqC7B;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,UAAU,EAChB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,YAAY,CAEd"}

package/lib/typescript/src/testing/simulated-device.d.ts

@@ -0,0 +1,127 @@
+/**
+ * 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 declare function toBytes(data: number[] | Uint8Array | string): number[];
+/**
+ * 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 declare abstract class SimulatedDevice {
+    #private;
+    /** 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;
+    /** @internal Bind the transport host (called by InMemorySerialTransport). */
+    _bind(host: SimulatedDeviceHost): void;
+    /** Send bytes to the host (they appear on `port.readable`). */
+    protected send(data: number[] | Uint8Array | string): void;
+    /**
+     * 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;
+    /** Set device-asserted input signals (DCD/CTS/RI/DSR) the host can read. */
+    protected setSignals(signals: SerialInputSignals): void;
+    /** The parameters the host opened the port with, or null when closed. */
+    protected get openOptions(): SimulatedDeviceOpenOptions | null;
+    protected get deviceId(): number;
+    protected get portNumber(): number;
+    /** 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 declare class LoopbackDevice extends SimulatedDevice {
+    readonly usbVendorId: number;
+    readonly usbProductId: number;
+    readonly serialNumber?: string;
+    constructor(identity?: SimulatedDeviceIdentity);
+    onData(data: Uint8Array): void;
+}
+/**
+ * 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 declare abstract class LineBufferedDevice extends SimulatedDevice {
+    #private;
+    /** Handle one line received from the host. */
+    abstract onLine(line: string): void | Promise<void>;
+    onData(data: Uint8Array): void;
+}
+/** A device that accepts writes but never sends anything back. */
+export declare class SinkDevice extends SimulatedDevice {
+    readonly usbVendorId: number;
+    readonly usbProductId: number;
+    readonly serialNumber?: string;
+    constructor(identity?: SimulatedDeviceIdentity);
+}
+//# sourceMappingURL=simulated-device.d.ts.map

package/lib/typescript/src/testing/simulated-device.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulated-device.d.ts","sourceRoot":"","sources":["../../../../src/testing/simulated-device.ts"],"names":[],"mappings":"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"}

package/lib/typescript/src/testing/test-suite.d.ts

@@ -0,0 +1,75 @@
+/**
+ * A runtime-agnostic suite runner for serial device tests. Write a set of
+ * `SerialTest`s once and run them anywhere a {@link SerialPort} exists:
+ *
+ *   - in Jest against a {@link DeviceHandle} simulator (in-memory),
+ *   - on a device / emulator over a real or WebSocket-backed port, and
+ *   - against BOTH, then {@link compareTestResults} to prove the device matches
+ *     the simulator case-for-case.
+ *
+ * Each test receives an opened, host-side {@link SerialClient}; by default one
+ * client is shared across the whole suite (open once, close at the end), which
+ * matches how a request/response protocol session behaves. Pass `shared: false`
+ * to open and close a fresh client per test. The runner never throws — it
+ * collects a {@link SerialTestResult} per case — so it is safe to drive an
+ * on-device Self-Test screen.
+ *
+ * @example One suite, two transports, compared
+ * const sim = await runTestSuite(myTests, await virtualPort());
+ * const dev = await runTestSuite(myTests, realPort);
+ * const rows = compareTestResults(sim, dev); // a row passes when both agree
+ */
+import type { SerialOptions, SerialPort } from '../WebSerial';
+import { SerialClient } from './serial-client';
+export type SerialTestResult = {
+    name: string;
+    passed: boolean;
+    error?: string;
+    durationMs: number;
+};
+/** One test case. `run` receives an already-opened client (typically per the
+ * suite's {@link TestClient}; `SerialClient` by default). */
+export type SerialTest<C = SerialClient> = {
+    name: string;
+    run(client: C): Promise<void>;
+};
+/** Progress hooks so a UI can render results live as each test completes. */
+export type SerialTestProgress = {
+    /** Called just before a test starts running. */
+    onStart?: (name: string, index: number, total: number) => void;
+    /** Called after each test completes (pass or fail). */
+    onResult?: (result: SerialTestResult) => void;
+};
+/**
+ * How to build (and tear down) the per-suite client from a port. Provide this to
+ * run a higher-level protocol client (e.g. an HCI / NMEA framer built on a
+ * {@link SerialClient}) instead of the raw client. `connect` must also open the
+ * port; `disconnect` must release it (a `SerialClient.close()` does both).
+ */
+export type TestClient<C> = {
+    connect(port: SerialPort): Promise<C>;
+    disconnect(client: C): Promise<void>;
+};
+export type RunTestSuiteOptions<C = SerialClient> = {
+    /** `SerialOptions` for the default client's `open()`. Default {baudRate: 115200}. */
+    open?: SerialOptions;
+    /** Open/close a fresh client per test instead of sharing one. Default false. */
+    shared?: boolean;
+    /** Build a protocol client over the port (defaults to an opened SerialClient). */
+    client?: TestClient<C>;
+    progress?: SerialTestProgress;
+};
+/**
+ * Run `tests` against an already-acquired `port`, collecting one result per
+ * case. With the default (shared) client the port is opened once and closed at
+ * the end; with `shared: false` each test gets a fresh open/close. Never throws.
+ */
+export declare function runTestSuite<C = SerialClient>(tests: SerialTest<C>[], port: SerialPort, options?: RunTestSuiteOptions<C>): Promise<SerialTestResult[]>;
+/**
+ * Compare two runs of the same suite case-by-case. A row passes when both runs
+ * agree (both passed or both failed), so the `candidate` is judged equivalent to
+ * the `reference` rather than judged on its own. Cases the candidate produced
+ * that the reference never ran are surfaced as failing `candidate: …` rows.
+ */
+export declare function compareTestResults(reference: SerialTestResult[], candidate: SerialTestResult[]): SerialTestResult[];
+//# sourceMappingURL=test-suite.d.ts.map

package/lib/typescript/src/testing/test-suite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-suite.d.ts","sourceRoot":"","sources":["../../../../src/testing/test-suite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAC,aAAa,EAAE,UAAU,EAAC,MAAM,cAAc,CAAC;AAE5D,OAAO,EAAC,YAAY,EAAC,MAAM,iBAAiB,CAAC;AAE7C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;6DAC6D;AAC7D,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,YAAY,IAAI;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,kBAAkB,GAAG;IAC/B,gDAAgD;IAChD,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/D,uDAAuD;IACvD,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAC/C,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI;IAC1B,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACtC,UAAU,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,mBAAmB,CAAC,CAAC,GAAG,YAAY,IAAI;IAClD,qFAAqF;IACrF,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,gFAAgF;IAChF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kFAAkF;IAClF,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IACvB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B,CAAC;AAaF;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,CAAC,GAAG,YAAY,EACjD,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,EACtB,IAAI,EAAE,UAAU,EAChB,OAAO,GAAE,mBAAmB,CAAC,CAAC,CAAM,GACnC,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAyD7B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,SAAS,EAAE,gBAAgB,EAAE,GAC5B,gBAAgB,EAAE,CA4BpB"}