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

package/src/testing/test-suite.ts

@@ -0,0 +1,186 @@
+/**
+ * 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 {errorMessage} from './harness';
+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;
+};
+
+function defaultClientFactory(open?: SerialOptions): TestClient<SerialClient> {
+  return {
+    async connect(port) {
+      const client = new SerialClient(port);
+      await client.open(open);
+      return client;
+    },
+    disconnect: client => client.close(),
+  };
+}
+
+/**
+ * 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 async function runTestSuite<C = SerialClient>(
+  tests: SerialTest<C>[],
+  port: SerialPort,
+  options: RunTestSuiteOptions<C> = {},
+): Promise<SerialTestResult[]> {
+  const factory = (options.client ??
+    defaultClientFactory(options.open)) as TestClient<C>;
+  const shared = options.shared ?? true;
+  const progress = options.progress;
+  const results: SerialTestResult[] = [];
+
+  let sharedClient: C | null = null;
+  if (shared) {
+    try {
+      sharedClient = await factory.connect(port);
+    } catch (e) {
+      const result: SerialTestResult = {
+        name: 'open serial port',
+        passed: false,
+        error: errorMessage(e),
+        durationMs: 0,
+      };
+      progress?.onResult?.(result);
+      return [result];
+    }
+  }
+
+  const total = tests.length;
+  try {
+    for (let i = 0; i < total; i++) {
+      const test = tests[i];
+      progress?.onStart?.(test.name, i, total);
+      const start = Date.now();
+      let perTest: C | null = null;
+      let result: SerialTestResult;
+      try {
+        if (!shared) perTest = await factory.connect(port);
+        const client = shared ? (sharedClient as C) : (perTest as C);
+        await test.run(client);
+        result = {
+          name: test.name,
+          passed: true,
+          durationMs: Date.now() - start,
+        };
+      } catch (e) {
+        result = {
+          name: test.name,
+          passed: false,
+          error: errorMessage(e),
+          durationMs: Date.now() - start,
+        };
+      } finally {
+        if (perTest) await factory.disconnect(perTest).catch(() => {});
+      }
+      results.push(result);
+      progress?.onResult?.(result);
+    }
+  } finally {
+    if (sharedClient) await factory.disconnect(sharedClient).catch(() => {});
+  }
+  return results;
+}
+
+/**
+ * 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 function compareTestResults(
+  reference: SerialTestResult[],
+  candidate: SerialTestResult[],
+): SerialTestResult[] {
+  const candidateByName = new Map(candidate.map(r => [r.name, r]));
+
+  const candidateOnly = candidate
+    .filter(r => !reference.some(s => s.name === r.name))
+    .map(r => ({
+      name: `candidate: ${r.name}`,
+      passed: false,
+      error: r.error ?? 'candidate produced an unexpected result',
+      durationMs: r.durationMs,
+    }));
+
+  const compared = reference.map(s => {
+    const r = candidateByName.get(s.name);
+    const identical = !!r && r.passed === s.passed;
+    return {
+      name: s.name,
+      passed: identical,
+      error: identical
+        ? undefined
+        : `reference ${s.passed ? 'passed' : 'failed'}, candidate ${
+            r ? (r.passed ? 'passed' : 'failed') : 'did not respond'
+          }${r?.error ? `: ${r.error}` : ''}`,
+      durationMs: r?.durationMs ?? 0,
+    };
+  });
+
+  return [...candidateOnly, ...compared];
+}

package/src/transport.ts

@@ -0,0 +1,200 @@
+/**
+ * Hardware-transport abstraction for the Web Serial polyfill.
+ *
+ * `SerialTransport` is the single interface that the `Serial`/`SerialPort`
+ * classes depend on to talk to "the device". The production implementation
+ * (`UsbSerialModule`, backed by the `NativeUsbSerial` TurboModule — see
+ * {@link ./UsbSerial}) and the in-memory test/dev double
+ * (`InMemorySerialTransport` — see {@link ./testing/in-memory-serial-transport}) both
+ * implement it.
+ *
+ * This module is intentionally free of any `react-native` import. That is what
+ * lets the virtual transport — and therefore the conformance suite built on top
+ * of it — run unchanged under Node/Jest, in a browser, and on a device.
+ */
+
+// UsbSerialPort.ControlLine enum
+export type ControlLine = 'RTS' | 'CTS' | 'DTR' | 'DSR' | 'CD' | 'RI';
+
+// UsbSerialPort.FlowControl enum
+export type FlowControl =
+  | 'NONE'
+  | 'RTS_CTS'
+  | 'DTR_DSR'
+  | 'XON_XOFF'
+  | 'XON_XOFF_INLINE';
+
+export type PortFilter = {
+  usbVendorId?: number;
+  usbProductId?: number;
+};
+
+export type PortPickerLabels = {
+  titleSelectPort?: string;
+  titleNoPortsAvailable?: string;
+  messageNoPortsAvailable?: string;
+};
+
+export type PortId = {
+  deviceId: number;
+  portNumber: number;
+  usbVendorId: number;
+  usbProductId: number;
+  /**
+   * Whether the app currently holds Android USB permission to access this
+   * device (via the system attach dialog or a prior permission request).
+   */
+  hasPermission: boolean;
+};
+
+export type DataEvent = {
+  deviceId: number;
+  portNumber: number;
+  data: number[];
+};
+
+export type ErrorEvent = {
+  deviceId: number;
+  portNumber: number;
+  error: string;
+  /**
+   * Optional spec error name (e.g. "BreakError", "BufferOverrunError",
+   * "FramingError", "ParityError") for a typed read error. When present the
+   * polyfill surfaces a DOMException of that name on the readable stream
+   * (otherwise it defaults to "NetworkError"); the WPT-derived spec tests in
+   * src/__tests__/conformance-suite.ts exercise this (BreakError,
+   * BufferOverrunError).
+   */
+  errorName?: string;
+};
+
+export type ConnectEvent = {
+  deviceId: number;
+  usbVendorId: number;
+  usbProductId: number;
+};
+
+export const Parity = {
+  NONE: 0,
+  ODD: 1,
+  EVEN: 2,
+  MARK: 3,
+  SPACE: 4,
+} as const;
+
+export const DataBits = {
+  FIVE: 5,
+  SIX: 6,
+  SEVEN: 7,
+  EIGHT: 8,
+} as const;
+
+export const StopBits = {
+  ONE: 1,
+  ONE_FIVE: 3,
+  TWO: 2,
+} as const;
+
+export type OpenOptions = {
+  baudRate: number;
+  dataBits?: number;
+  stopBits?: number;
+  parity?: number;
+};
+
+export const DEFAULT_OPEN_OPTIONS: Required<Omit<OpenOptions, 'baudRate'>> = {
+  dataBits: DataBits.EIGHT,
+  stopBits: StopBits.ONE,
+  parity: Parity.NONE,
+};
+
+/** Handle returned by the `on*` subscription methods. */
+export type Subscription = {remove: () => void};
+
+/**
+ * The contract every serial transport must satisfy. It mirrors the JS-friendly
+ * surface of `UsbSerialModule` exactly, so `UsbSerialModule implements
+ * SerialTransport` is a faithful 1:1 and any conforming double (e.g.
+ * `InMemorySerialTransport`) is a drop-in replacement.
+ *
+ * Ports are addressed by the pair `(deviceId, portNumber)`. Inbound bytes,
+ * read errors and device attach/detach arrive through the `on*` subscriptions.
+ */
+export interface SerialTransport {
+  // Discovery & permission
+  findAllDrivers(): Promise<ReadonlyArray<PortId>>;
+  showPortPicker(
+    filter: ReadonlyArray<PortFilter>,
+    labels?: PortPickerLabels,
+  ): Promise<PortId>;
+  requestPermission(deviceId: number): Promise<boolean>;
+
+  // Lifecycle
+  open(
+    deviceId: number,
+    portNumber: number,
+    options: OpenOptions,
+  ): Promise<void>;
+  close(deviceId: number, portNumber: number): Promise<void>;
+  isOpen(deviceId: number, portNumber: number): boolean;
+
+  // I/O
+  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>;
+
+  // Parameters
+  setParameters(
+    deviceId: number,
+    portNumber: number,
+    options: OpenOptions,
+  ): Promise<void>;
+
+  // Control signals
+  setDTR(deviceId: number, portNumber: number, value: boolean): Promise<void>;
+  setRTS(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>;
+  getDSR(deviceId: number, portNumber: number): Promise<boolean>;
+  getRI(deviceId: number, portNumber: number): Promise<boolean>;
+  getControlLines(deviceId: number, portNumber: number): Promise<ControlLine[]>;
+  getSupportedControlLines(
+    deviceId: number,
+    portNumber: number,
+  ): Promise<ControlLine[]>;
+
+  // Flow control
+  setFlowControl(
+    deviceId: number,
+    portNumber: number,
+    flowControl: FlowControl,
+  ): Promise<void>;
+  getFlowControl(deviceId: number, portNumber: number): Promise<FlowControl>;
+  getSupportedFlowControl(
+    deviceId: number,
+    portNumber: number,
+  ): Promise<FlowControl[]>;
+
+  // Misc
+  setBreak(deviceId: number, portNumber: number, value: boolean): Promise<void>;
+  purgeHwBuffers(
+    deviceId: number,
+    portNumber: number,
+    purgeWriteBuffers: boolean,
+    purgeReadBuffers: boolean,
+  ): Promise<void>;
+  getSerial(deviceId: number, portNumber: number): Promise<string>;
+
+  // Event subscriptions
+  onData(listener: (event: DataEvent) => void): Subscription;
+  onError(listener: (event: ErrorEvent) => void): Subscription;
+  onConnect(listener: (event: ConnectEvent) => void): Subscription;
+  onDisconnect(listener: (event: ConnectEvent) => void): Subscription;
+}