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

package/TESTING.md

@@ -1,150 +1,173 @@
 # Testing
 
-This library is designed to be testable **without USB hardware** — both in a
-test runner (Jest, Vitest, …) and live on a device, an emulator, or in the
-browser. One idea makes that possible: every path to the hardware goes through a
-single interface, [`SerialTransport`](src/transport.ts), and you can swap in a
-pure-JavaScript implementation.
+This library is designed to be testable without USB hardware. The same code can run in Jest, on a real Android device, in the browser, or in an emulator.
 
-```
- Serial / SerialPort ──depends on──► SerialTransport
-                                          ▲           ▲
-                          UsbSerialModule │           │ VirtualSerialTransport
-                          (real, native)              (in-memory, no native deps)
-```
+The key idea is simple: all hardware access goes through a single transport interface, [`SerialTransport`](src/transport.ts), and you can swap in a pure JavaScript transport when you do not want to talk to real hardware.
 
-Because `VirtualSerialTransport` has **no `react-native` dependency**, the same
-code runs under Node/Jest, on a real Android device, and on the web.
+## At a glance
 
----
+- `new Serial(transport)` for isolated unit tests
+- `setUsbSerial(transport)` for redirecting the singleton `serial`
+- `InMemorySerialTransport` for loopback and simulated devices
+- `SimulatedDevice` for authoring a full peripheral model
+- `SerialClient` for host-side protocol tests
+- `runTestSuite()` for reusable test suites that work in Jest and on real hardware
+- `exposeSimulatedDevice()` for WebSocket-based E2E and emulator testing
 
-## The transport seam
+## Transport layer
 
-`Serial` resolves its transport in three ways, in order of precedence:
+`Serial` resolves its transport in three ways, in order:
 
-1. **Constructor injection** — `new Serial(transport)` (best for isolated tests).
-2. **Global override** — `setUsbSerial(transport)` affects the singleton `serial`
-   and any `new Serial()` created without an explicit transport.
-3. **Default** — the real `UsbSerialModule` backed by the native TurboModule.
+| Priority | How to use it | Best for |
+| --- | --- | --- |
+| 1 | `new Serial(transport)` | Isolated tests and explicit control |
+| 2 | `setUsbSerial(transport)` | Redirecting the singleton `serial` |
+| 3 | Default native transport | Real Android hardware |
 
 ```ts
 import {Serial, setUsbSerial, resetUsbSerial} from 'react-native-web-serial-api';
-import {VirtualSerialTransport} from 'react-native-web-serial-api/testing';
+import {InMemorySerialTransport} from 'react-native-web-serial-api/testing';
 
-// (1) explicit — recommended in unit tests
-const transport = new VirtualSerialTransport();
+// Best for unit tests: the transport is explicit.
+const transport = new InMemorySerialTransport();
 const serial = new Serial(transport);
 
-// (2) global — redirects the singleton `serial` too. Call it before the first
-// getPorts()/requestPort()/addEventListener(). resetUsbSerial() restores default.
+// Best when you want the singleton `serial` to use a virtual transport too.
 setUsbSerial(transport);
+
+// Restore the native default after the test.
+resetUsbSerial();
 ```
 
-The testing utilities live in the **`react-native-web-serial-api/testing`**
-subpath, so they stay out of your production bundle.
+The testing helpers live under the `react-native-web-serial-api/testing` subpath, so they stay out of your production bundle.
+
+## Which test style should I use?
 
----
+| Use case | Start with | Why |
+| --- | --- | --- |
+| Quick byte-level smoke test | `InMemorySerialTransport` + `LoopbackDevice` | Fast and deterministic |
+| Stateful peripheral simulation | `SimulatedDevice` | Lets you model a real device protocol |
+| Host-side protocol tests | `SerialClient` | Removes reader/writer boilerplate |
+| Reusable suite against virtual and real devices | `runTestSuite()` | Same cases, different runtimes |
+| App/emulator/browser talking to a simulated device | `exposeSimulatedDevice()` | WebSocket bridge with the same simulator |
 
-## VirtualSerialTransport
+## Fast in-memory test
 
-An in-memory transport backing one or more simulated devices. You register a
-[`SerialDevice`](#simulating-a-whole-device-serialdevice) and the transport
-reads its USB identity; `options` carries the transport-side knobs.
+`InMemorySerialTransport` is the core test transport. It can host one or more simulated devices and it does not depend on `react-native`, which is why the same code works in Jest and in browser-style environments.
 
 ```ts
-import {VirtualSerialTransport, EchoDevice} from 'react-native-web-serial-api/testing';
+import {InMemorySerialTransport, LoopbackDevice} from 'react-native-web-serial-api/testing';
 
-const transport = new VirtualSerialTransport({
-  latencyMs: 0,            // 0 = resolve on a microtask (deterministic for Jest)
+const transport = new InMemorySerialTransport({
+  latencyMs: 0, // 0 = resolve on a microtask, which is nice for Jest
   autoGrantPermission: true,
 });
 
 const device = transport.addDevice(
-  new EchoDevice({usbVendorId: 0x0403, usbProductId: 0x6001, serialNumber: 'DEMO-1'}),
+  new LoopbackDevice({
+    usbVendorId: 0x0403,
+    usbProductId: 0x6001,
+    serialNumber: 'DEMO-1',
+  }),
   {
-    hasPermission: true,   // false → hidden from getPorts() until requestPort()
-    loopbackSignals: true, // DTR→DSR+DCD, RTS→CTS, so getSignals reflects setSignals
+    hasPermission: true,
+    loopbackSignals: true,
   },
 );
 ```
 
-`EchoDevice` (loopback) and `SilentDevice` (accepts writes, sends nothing) are
-built in; for anything richer, write a `SerialDevice` (next section).
+`LoopbackDevice` echoes bytes back to the host. `SinkDevice` accepts writes and produces no output.
 
-### Driving a device from a test/UI
+### Driving a device from a test
 
 ```ts
-device.push([0x01, 0x02]);        // inbound bytes as if the device sent them
-device.emitError('cable fault');  // raise a read error on the readable stream
-device.attach();                  // (re)attach → fires "connect" (new deviceId)
-device.detach();                  // detach → fires "disconnect"
-device.loseDevice();              // unplug while open: errors the stream, disconnects
-device.failNext('open');          // make the next open()/write()/… reject once
-device.written;                   // number[][] — everything the host wrote
+device.push([0x01, 0x02]);       // device sends bytes to the host
+device.emitError('cable fault'); // readable stream error
+device.attach();                 // attach again and fire connect
+device.detach();                 // detach and fire disconnect
+device.loseDevice();             // unplug while open
+device.failNext('open');         // make the next open() reject once
+device.written;                  // everything the host wrote
 ```
 
-`transport.selectNextPort(device)` / `transport.rejectNextPortPicker()` script
-what the next `requestPort()` returns.
+You can also script the next permission prompt:
 
----
+```ts
+transport.selectNextPort(device);
+transport.rejectNextPortPicker();
+```
 
-## Simulating a whole device (`SerialDevice`)
+## Host-side protocol test
 
-To model a *whole* peripheral — a stateful protocol that greets on open, streams
-over time, reacts to control signals, and raises typed errors — extend
-**`SerialDevice`** and override the lifecycle hooks:
+For a more realistic peripheral, extend `SimulatedDevice` and override lifecycle hooks.
 
 ```ts
-import {SerialDevice, VirtualSerialTransport} from 'react-native-web-serial-api/testing';
 import {Serial} from 'react-native-web-serial-api';
+import {InMemorySerialTransport, SimulatedDevice} from 'react-native-web-serial-api/testing';
 
-class Thermometer extends SerialDevice {
+class Thermometer extends SimulatedDevice {
   usbVendorId = 0x0403;
   usbProductId = 0x6001;
   #timer?: ReturnType<typeof setInterval>;
 
-  onOpen() {                          // host opened the port
+  onOpen() {
     this.send('READY\r\n');
     this.#timer = setInterval(() => this.send(`temp=${20 + Math.random()}C\r\n`), 1000);
   }
-  onData(bytes: Uint8Array) {         // host wrote to the device
-    if (String.fromCharCode(...bytes).trim() === 'ID?') this.send('ACME-TEMP\r\n');
+
+  onData(bytes: Uint8Array) {
+    if (String.fromCharCode(...bytes).trim() === 'ID?') {
+      this.send('ACME-TEMP\r\n');
+    }
+  }
+
+  onHostSignals() {
+    // DTR/RTS/break changed
+  }
+
+  onClose() {
+    clearInterval(this.#timer);
   }
-  onHostSignals(s) { /* DTR/RTS/break changed */ }
-  onClose() { clearInterval(this.#timer); }
 }
 
-const transport = new VirtualSerialTransport();
+const transport = new InMemorySerialTransport();
 transport.addDevice(new Thermometer(), {hasPermission: true});
 const serial = new Serial(transport);
 ```
 
-Hooks: `onOpen(options)`, `onData(data)`, `onHostSignals(signals)`, `onClose()`
-(all optional, may be async). Helpers: `this.send(bytes|string)`,
-`this.raiseError(message, name?)` (e.g. `'BreakError'`),
-`this.setSignals({dataCarrierDetect, clearToSend, ringIndicator, dataSetReady})`,
-`this.openOptions`. **`EchoDevice`** (loopback), **`SilentDevice`**, and
-**`LineDevice`** (buffers to `\n`, calls `onLine(line)`) are built in.
-`addDevice(device, options?)` reads the device's
-`usbVendorId`/`usbProductId`/`serialNumber`; `options` carries the transport
-knobs (`hasPermission`, `portNumber`, …).
+Available hooks:
+
+- `onOpen(options)`
+- `onData(data)`
+- `onHostSignals(signals)`
+- `onClose()`
 
----
+Helpers on `SimulatedDevice`:
 
-## Writing unit tests (Jest)
+- `this.send(bytesOrString)`
+- `this.raiseError(message, name?)`
+- `this.setSignals({dataCarrierDetect, clearToSend, ringIndicator, dataSetReady})`
+- `this.openOptions`
 
-No native mocks required — inject the transport and exercise the real
-`Serial`/`SerialPort` logic and streams:
+## Writing unit tests
+
+Inject the transport and exercise the real `Serial` / `SerialPort` logic.
 
 ```ts
 import {Serial} from 'react-native-web-serial-api';
-import {VirtualSerialTransport} from 'react-native-web-serial-api/testing';
+import {
+  InMemorySerialTransport,
+  LoopbackDevice,
+} from 'react-native-web-serial-api/testing';
 
 it('echoes bytes through the streams', async () => {
-  const transport = new VirtualSerialTransport();
-  transport.addDevice({usbVendorId: 0x0403, usbProductId: 0x6001, hasPermission: true});
-  const serial = new Serial(transport);
+  const transport = new InMemorySerialTransport();
+  transport.addDevice(
+    new LoopbackDevice({usbVendorId: 0x0403, usbProductId: 0x6001}),
+    {hasPermission: true},
+  );
 
+  const serial = new Serial(transport);
   const [port] = await serial.getPorts();
   await port.open({baudRate: 115200});
 
@@ -155,141 +178,360 @@ it('echoes bytes through the streams', async () => {
 });
 ```
 
-See [`src/__tests__/`](src/__tests__) for the library's own suites. Note: the
-seam imports `react-native`, so a Jest setup needs the RN preset — see this
-repo's [`jest.config.js`](jest.config.js).
+The library tests themselves live under [`src/__tests__/`](src/__tests__). Because the transport layer imports `react-native`, Jest needs the React Native preset. See [`jest.config.js`](jest.config.js).
+
+## Testing as the host: `SerialClient`
+
+`SerialClient` is a timeout-aware wrapper around any `SerialPort`. It removes the boilerplate of managing `ReadableStream` readers and `WritableStream` writers in test code.
+
+```ts
+import {SerialClient} from 'react-native-web-serial-api/testing';
+
+const client = new SerialClient(port);
+await client.open({baudRate: 115200});
+
+await client.write([0x01, 0x02, 0x03]);
+
+const echo = await client.readBytes(3);
+const frame = await client.readUntil([0xC0]);
+const line = await client.readLine();
+const chunk = await client.readAvailable();
+
+await client.expectIdle(100);
+await client.close();
+```
+
+All read methods accept `{timeout?: number}` and default to 5 seconds.
+
+### Building a protocol client
+
+`readAvailable()` is useful when you want to feed a framing decoder.
+
+```ts
+import {SerialClient} from 'react-native-web-serial-api/testing';
+import {SlipDecoder} from './slip';
+
+class MyProtocolClient {
+  #client: SerialClient;
+  #pending: MyMessage[] = [];
+
+  static async open(port: SerialPort, baudRate = 115200) {
+    const client = new MyProtocolClient(new SerialClient(port));
+    await client.#client.open({baudRate});
+    return client;
+  }
+
+  private constructor(client: SerialClient) {
+    this.#client = client;
+  }
+
+  async recv(timeoutMs = 5000): Promise<MyMessage> {
+    if (this.#pending.length) return this.#pending.shift()!;
+
+    const decoder = new SlipDecoder();
+    while (!this.#client.ended) {
+      const chunk = await this.#client.readAvailable({timeout: timeoutMs});
+      for (const frame of decoder.feed(chunk)) {
+        this.#pending.push(parseHci(frame));
+      }
+      if (this.#pending.length) return this.#pending.shift()!;
+    }
+
+    throw new Error('port closed before message arrived');
+  }
+
+  async close() {
+    await this.#client.close();
+  }
+}
+```
+
+## One-call fixture: `createDeviceFixture`
 
----
+`createDeviceFixture()` wires up a `SimulatedDevice` and returns the handles you usually need in a test.
 
-## The conformance suite (one suite, two runtimes)
+```ts
+import {createDeviceFixture} from 'react-native-web-serial-api/testing';
+import {WMBusGateway} from './devices/wmbus/WMBusGateway';
+import {WMBusMeter} from './devices/wmbus/WMBusMeter';
+
+const ADDRESS = {
+  manufacturerId: 0x1234,
+  deviceId: 0x56789abc,
+  version: 0x01,
+  type: 0x07,
+};
+
+const {client, simulatedDevice, whenOpened, whenClosed} =
+  await createDeviceFixture(new WMBusGateway('iU891A-XL'));
+
+const opened = whenOpened();
+await client.open({baudRate: 115200});
+await opened;
+
+const meter = new WMBusMeter({address: ADDRESS, payloadTemplate: [0x01]});
+simulatedDevice.addMeter(meter);
+meter.sendTelegram();
+const frame = await client.readAvailable();
+
+await whenClosed();
+await client.close();
+```
 
-[`src/__tests__/conformance-suite.ts`](src/__tests__/conformance-suite.ts) exports
-`serialConformanceTests` — self-contained cases (each builds its own
-`Serial` + `VirtualSerialTransport`) with built-in assertions and **no
-test-runner dependency**. It is **test-only code**: it is excluded from the
-build and from the published npm package (it imports the shipped testing
-utilities, not the other way round), so it adds nothing to consumers' bundles.
-The very same array runs:
+Multiple devices at once:
 
-- **under Jest** — [`src/__tests__/conformance.test.ts`](src/__tests__/conformance.test.ts):
-  ```ts
-  import {serialConformanceTests} from './conformance-suite';
-  for (const t of serialConformanceTests) it(t.name, () => t.run());
-  ```
-- **on a device** — via `runSerialConformance()`, which returns a structured
-  pass/fail result per test (it never throws). The example app's Self-Test
-  screen imports it directly from the test folder (a dev-only import — see
-  [`example/src/screens/SelfTestScreen.tsx`](example/src/screens/SelfTestScreen.tsx)).
+```ts
+const {ports, transport} = await createDeviceFixture([
+  new WMBusGateway('iU891A-XL'),
+  new NmeaGpsDevice(),
+]);
+```
+
+If you pass `opts.installGlobally = true`, `createDeviceFixture()` calls `setUsbSerial(transport)` so the singleton `serial` also uses the virtual transport. Remember to call `resetUsbSerial()` in teardown.
+
+## Lifecycle awaiting: `whenOpened` / `whenClosed`
+
+`whenOpened()` and `whenClosed()` are available on both `createDeviceFixture()` and the lower-level `DeviceHandle`.
+
+```ts
+const device = transport.addDevice(new MyDevice(), {hasPermission: true});
+
+const opts = await device.whenOpened(); // resolves on the next open
+await device.whenClosed();             // resolves on the next close
+```
+
+Each call returns a fresh promise for the next transition, so you can use them in reconnect loops.
+
+## Fault injection
+
+`DeviceHandle` includes helpers for protocol and lifecycle failures.
+
+```ts
+device.push([0x01, 0x02]);
+device.emitError('cable fault');
+
+device.failNext('open');
+device.failNext('write');
+device.failNext('startReading');
+device.overrunAfter(16);
+
+device.loseDevice();
+device.detach();
+device.attach();
+
+device.written;
+device.isOpen;
+```
+
+These are useful for asserting protocol-level behavior:
+
+```ts
+device.failNext('write');
+await expect(client.write([1, 2])).rejects.toThrow();
+expect(device.written).toHaveLength(0);
+```
+
+## Writing a test suite: `runTestSuite` + `compareTestResults`
+
+`runTestSuite()` lets you define a list of named serial tests and run them against different ports.
+
+```ts
+import {runTestSuite, compareTestResults, type SerialTest}
+  from 'react-native-web-serial-api/testing';
+
+const suite: SerialTest[] = [
+  {
+    name: 'echoes 4 bytes',
+    async run(client) {
+      await client.write([1, 2, 3, 4]);
+      const echo = await client.readBytes(4);
+      if (!echo.every((b, i) => b === [1, 2, 3, 4][i])) {
+        throw new Error(`echo mismatch: got ${Array.from(echo)}`);
+      }
+    },
+  },
+];
+
+const {port} = await createDeviceFixture(new LoopbackDevice());
+const ref = await runTestSuite(suite, port, {open: {baudRate: 115200}});
+const real = await runTestSuite(suite, realPort, {open: {baudRate: 115200}});
+const agreed = compareTestResults(ref, real);
+```
+
+Options:
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `open` | `{baudRate: 9600}` | Forwarded to `port.open()` |
+| `shared` | `true` | Reuse one client for all tests |
+| `client` | - | Custom protocol client factory |
+| `progress` | - | Live `onStart` / `onResult` callbacks |
+
+### Custom protocol client
+
+```ts
+import {runTestSuite, type TestClient}
+  from 'react-native-web-serial-api/testing';
+import {HciHost} from './HciHost';
+
+const results = await runTestSuite(hciSuite, port, {
+  open: {baudRate: 115200},
+  client: {
+    connect: (p) => HciHost.open(p),
+    disconnect: (host) => host.close(),
+  } satisfies TestClient<HciHost>,
+});
+```
+
+## WebSocket E2E: `exposeSimulatedDevice`
+
+`exposeSimulatedDevice()` runs a simulator behind a WebSocket server so a real app, emulator, or browser can connect to it.
+
+```ts
+import {createDeviceFixture, runTestSuite} from 'react-native-web-serial-api/testing';
+
+const {port} = await createDeviceFixture(new WMBusGateway('iU891A-XL'));
+const results = await runTestSuite(wmbusSuite, port, {open: {baudRate: 115200}});
+```
+
+```ts
+import {exposeSimulatedDevice} from 'react-native-web-serial-api/testing';
+import {WebSocketServer} from 'ws'; // optional dependency
+
+const ex = exposeSimulatedDevice(new WMBusGateway('iU891A-XL'), {
+  port: 8090,
+  WebSocketServer,
+  // host: '0.0.0.0', // use this for a physical device or emulator
+});
+
+await ex.whenOpened();
+await ex.close();
+```
+
+`ExposedDevice` gives you:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `url` | `string` | URL for `WebSocketSerialTransport` |
+| `simulatedDevice` | `D` | The concrete simulator |
+| `device` | `DeviceHandle` | Low-level device handle |
+| `whenOpened()` | `Promise<SimulatedDeviceOpenOptions>` | Resolves when the app opens the port |
+| `whenClosed()` | `Promise<void>` | Resolves when the app closes the port |
+| `close()` | `Promise<void>` | Stops the WebSocket server |
+
+`ws` is loaded lazily, so importing from `react-native-web-serial-api/testing` is safe in React Native. The dependency is only needed when `exposeSimulatedDevice()` is called in Node.
+
+## Fake-timer gotcha
+
+`InMemorySerialTransport` delivers data via `queueMicrotask()` at the default `latencyMs: 0`. If your suite uses `jest.useFakeTimers()`, microtasks still run, but `SerialClient` read timeouts use `setTimeout`, so fake timers will stall reads unless you advance them.
+
+```ts
+beforeAll(() => {
+  jest.useFakeTimers({
+    doNotFake: ['queueMicrotask'],
+  });
+});
+
+it('streams data periodically', async () => {
+  // start the device timer...
+  jest.advanceTimersByTime(5000);
+  const line = await client.readLine();
+});
+```
+
+If your suite does not use periodic timers, real timers are usually simpler.
+
+## The conformance suite
+
+[`src/__tests__/conformance-suite.ts`](src/__tests__/conformance-suite.ts) exports `serialConformanceTests`, a set of self-contained cases that each build their own `Serial` and `InMemorySerialTransport`.
+
+The suite is test-only code. It is excluded from the build and from the published package, and the same cases can run in both Jest and on-device.
+
+```ts
+import {serialConformanceTests} from './conformance-suite';
+
+for (const test of serialConformanceTests) {
+  it(test.name, () => test.run());
+}
+```
+
+The same suite can also run through `runSerialConformance()`, which returns structured pass/fail results for use in the example app's Self Test screen.
 
 ```ts
 import {runSerialConformance, runRealDeviceSmokeTest} from './conformance-suite';
 
-const results = await runSerialConformance();           // virtual, full suite
-const smoke = await runRealDeviceSmokeTest(serial);     // small, safe, real device
+const results = await runSerialConformance();
+const smoke = await runRealDeviceSmokeTest(serial);
 ```
 
----
-
-## WPT spec compliance
-
-The `WPT …` cases **at the end of the conformance suite**
-([`src/__tests__/conformance-suite.ts`](src/__tests__/conformance-suite.ts)) are ports of the
-**official Web Platform Tests** for the Web Serial API (vendored in
-`tmp/serial/`), so the spec's own test logic runs against our polyfill via the
-virtual loopback device — proof of W3C compliance, not just our own assertions.
-They live in the conformance suite rather than a separate Jest-only file, so the
-same spec tests run **under Jest *and* on-device** (Self Test screen), not just
-in a browser. They cover loopback read/write (small + large, repeated),
-`readable.cancel()` discarding buffered data, hardware flow-control
-back-pressure, typed `BreakError`/`BufferOverrunError`, large PRNG-stream
-integrity, disconnect during a pending read/write, and the interface (IDL) shape.
-
-Porting the spec faithfully originally surfaced five real gaps in the polyfill
-(typed `BreakError`/`BufferOverrunError` on the readable; disconnect rejecting
-the pending read/write with `NetworkError`; the `disconnect` event `target`; and
-a leaked subscription on `readable.cancel()`). All are now **fixed** in
-`WebSerial.ts`, and these cases pass as regression guards. The browser-security
-WPT files (permission prompts, secure-context, `requestPort()` user-gesture
-gating) don't apply to a React Native polyfill and are intentionally not ported;
-the PRNG-stream length is scaled down from the upstream 10 MB so the on-device
-Self Test stays fast.
-
----
+### Web Platform Tests
 
-## On-device testing (example app)
+The `WPT ...` cases at the end of the conformance suite are ports of the official Web Platform Tests for the Web Serial API. They run against the virtual loopback device so the spec logic is exercised under Jest and on-device.
+
+These cases cover things like:
 
-The [example app](example) ships two ways to test on real hardware (or none):
+- loopback read/write
+- `readable.cancel()` behavior
+- hardware flow-control back-pressure
+- typed read errors such as `BreakError` and `BufferOverrunError`
+- disconnect handling during pending operations
+- the IDL shape of the interface
 
-- **Self Test screen** (overflow menu → *Self test…*) runs the conformance suite
-  in-app and shows pass/fail, plus a *Run on connected device* smoke test. This
-  works on Android, web, and in an emulator with **no device attached**.
-- **Virtual device (demo)** toggle (overflow menu) injects a
-  `VirtualSerialTransport` (an FTDI `EchoDevice` + a CP210x `SensorDevice`, both
-  authored as `SerialDevice`s — see [example/src/devices/](example/src/devices))
-  so the whole Devices → Connect → Terminal flow runs hardware-free.
+The browser-specific WPT cases around permission prompts and secure-context gating are intentionally not ported because they do not map to a React Native runtime.
+
+## On-device testing (example app)
 
-> **Platform note:** demo mode redirects the app's live serial, which only works
-> on Android (where `serial` is this library's polyfill). On web `serial` is the
-> browser's native `navigator.serial`, which the library cannot inject into — but
-> the Self-Test screen still works everywhere because it builds its own
-> `new Serial(virtualTransport)`.
+The [example app](example) includes two ways to test without hardware:
 
----
+- **Self Test** screen: runs the conformance suite in-app and shows pass/fail
+- **Virtual device (demo)** mode: injects an `InMemorySerialTransport` with simulated devices so the Devices -> Connect -> Terminal flow works without hardware
+
+> Demo mode redirects the app's live serial transport, which only works on Android. On web, `serial` is the browser's native `navigator.serial`, so the library cannot override it. The Self Test screen still works everywhere because it creates its own `new Serial(new InMemorySerialTransport())`.
 
 ## E2E in the emulator
 
-The same `SerialDevice` mocks let you run **UI E2E tests** against an app with no
-USB hardware. Install the mock once at startup behind your own flag:
+You can also run UI E2E tests against an app with no USB hardware by installing the mock transport at startup behind your own flag.
 
 ```ts
-// index.js — debug/E2E build only
-import {installSerialMock, EchoDevice} from 'react-native-web-serial-api/testing';
+import {
+  LoopbackDevice,
+  installInMemorySerialTransport,
+} from 'react-native-web-serial-api/testing';
 import {MyThermometer} from './devices/MyThermometer';
 
-installSerialMock({
-  enabled: process.env.RNWS_SERIAL_MOCK === '1',   // your own gate
-  devices: [new EchoDevice(), new MyThermometer()],
+installInMemorySerialTransport({
+  enabled: process.env.RNWS_SERIAL_MOCK === '1',
+  devices: [new LoopbackDevice(), new MyThermometer()],
 });
 ```
 
-`installSerialMock` builds a `VirtualSerialTransport` and calls `setUsbSerial`, so
-`navigator.serial` now talks to your simulated devices.
+`installInMemorySerialTransport()` builds an `InMemorySerialTransport` and calls `setUsbSerial()`, so `navigator.serial` now talks to your simulated devices.
 
-The example app ships a **Maestro** suite ([example/.maestro/](example/.maestro))
-that drives the real UI against the in-app mock (via the demo toggle):
+The example app ships Maestro tests in [`example/.maestro/`](example/.maestro):
 
 ```sh
-# start an Android emulator, then:
-npm --prefix example run android   # build + install the debug app (Metro)
-npm --prefix example run e2e       # maestro test .maestro
+npm --prefix example run android
+npm --prefix example run e2e
 
-# from the repo root: run host Jest first, then emulator E2E
+# or run host Jest first, then emulator E2E
 npm run test:host+emulator
 ```
 
-- `demo-echo.yaml` — enable demo mode → connect to the FTDI echo device → send a
-  line in the Terminal → assert it round-trips.
-- `self-test.yaml` — open *Self test* → run the conformance suite → assert green.
-
-This isn't wired into GitHub CI (it needs an emulator); run it locally or in an
-emulator-equipped job. [Detox](https://wix.github.io/Detox/) works the same way —
-the mock is what makes either runner hardware-free.
-
----
+- `demo-echo.yaml` enables demo mode, connects to the echo device, sends a line, and checks that it round-trips.
+- `self-test.yaml` opens Self Test, runs the conformance suite, and asserts success.
 
 ## Running the tests
 
 ```sh
-npm test            # library unit + conformance suite
-npm run test:watch  # watch mode
+npm test
+npm run test:watch
 npm run typecheck
 npm run lint
 
-npm test --prefix example   # example app tests
+npm test --prefix example
 ```
 
-CI runs all of the above plus a build check on every push/PR — see
-[`.github/workflows/ci.yml`](.github/workflows/ci.yml).
+CI runs these checks plus a build step on every push or pull request.
 
 ## Coverage
 
@@ -297,5 +539,4 @@ CI runs all of the above plus a build check on every push/PR — see
 npm run test:coverage
 ```
 
-Prints a per-file table + summary and writes a browsable HTML report to
-`coverage/lcov-report/index.html` (config in [`jest.config.js`](jest.config.js)).
+This prints a summary and writes an HTML report to `coverage/lcov-report/index.html`.