@react-native-harness/bridge 1.5.0 → 1.7.0

package/src/image-snapshot.ts

@@ -3,11 +3,16 @@ import { ssim } from 'ssim.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { PNG } from 'pngjs';
-import type { FileReference, ImageSnapshotOptions } from './shared.js';
+import type {
+  FileReference,
+  ImageSnapshotOptions,
+  SnapshotUpdateState,
+} from './shared.js';
 
 type PixelmatchOptions = Parameters<typeof pixelmatch>[5];
 
 const SNAPSHOT_DIR_NAME = '__image_snapshots__';
+const DIFF_OUTPUT_DIR_NAME = '__diff_output__';
 const DEFAULT_OPTIONS_FOR_PIXELMATCH: PixelmatchOptions = {
   threshold: 0.1,
   includeAA: false,
@@ -49,7 +54,8 @@ export const matchImageSnapshot = async (
   screenshot: FileReference,
   testFilePath: string,
   options: ImageSnapshotOptions,
-  platformName: string
+  platformName: string,
+  updateSnapshot: SnapshotUpdateState
 ) => {
   const pixelmatchOptions = {
     ...DEFAULT_OPTIONS_FOR_PIXELMATCH,
@@ -69,14 +75,28 @@ export const matchImageSnapshot = async (
   const testDir = path.dirname(testFilePath);
   const snapshotsDir = path.join(testDir, SNAPSHOT_DIR_NAME, platformName);
 
-  const snapshotName = `${options.name}.png`;
-  const snapshotPath = path.join(snapshotsDir, snapshotName);
+  const snapshotPath = path.join(snapshotsDir, `${options.name}.png`);
+  // Failure artifacts live in their own folder so they can never overwrite
+  // a baseline of another snapshot (e.g. one named `<name>-diff`).
+  const diffOutputDir = path.join(snapshotsDir, DIFF_OUTPUT_DIR_NAME);
+  const failureImagePath = (image: 'actual' | 'diff'): string =>
+    path.join(diffOutputDir, `${options.name}-${image}.png`);
+  const actualPath = failureImagePath('actual');
 
   await fs.mkdir(snapshotsDir, { recursive: true });
 
   try {
     await fs.access(snapshotPath);
   } catch {
+    if (updateSnapshot === 'none') {
+      await fs.mkdir(diffOutputDir, { recursive: true });
+      await fs.writeFile(actualPath, receivedBuffer);
+      return {
+        pass: false,
+        message: `New snapshot was not written: ${snapshotPath} does not exist, and missing snapshots are not written in CI mode. Received image saved at ${actualPath}; commit it as ${snapshotPath}, or run without CI mode (--ci=false) on a machine with this device and commit the snapshot it writes.`,
+      };
+    }
+
     // First time - create snapshot
     await fs.writeFile(snapshotPath, receivedBuffer);
     return {
@@ -95,9 +115,12 @@ export const matchImageSnapshot = async (
   const diff = new PNG({ width, height });
 
   if (img1.width !== img2.width || img1.height !== img2.height) {
+    await fs.mkdir(diffOutputDir, { recursive: true });
+    await fs.writeFile(actualPath, receivedBuffer);
+
     return {
       pass: false,
-      message: `Images have different dimensions. Received image width: ${img1.width}, height: ${img1.height}. Snapshot image width: ${img2.width}, height: ${img2.height}.`,
+      message: `Images have different dimensions. Received image width: ${img1.width}, height: ${img1.height}. Snapshot image width: ${img2.width}, height: ${img2.height}. Actual image saved at ${actualPath}.`,
     };
   }
 
@@ -152,12 +175,11 @@ export const matchImageSnapshot = async (
 
   // Save diff and actual images when test fails
   if (!pass) {
-    const diffFileName = `${snapshotName.replace('.png', '')}-diff.png`;
-    const diffPath = path.join(snapshotsDir, diffFileName);
+    await fs.mkdir(diffOutputDir, { recursive: true });
+
+    const diffPath = failureImagePath('diff');
     await fs.writeFile(diffPath, PNG.sync.write(diff));
 
-    const actualFileName = `${snapshotName.replace('.png', '')}-actual.png`;
-    const actualPath = path.join(snapshotsDir, actualFileName);
     await fs.writeFile(actualPath, receivedBuffer);
 
     message += ` Diff saved at ${diffPath}. Actual image saved at ${actualPath}.`;

package/src/index.ts

@@ -1,3 +1 @@
 export * from './shared.js';
-export * from './binary-transfer.js';
-export * from './transport.js';

package/src/js-block-budget-policy.ts

@@ -0,0 +1,90 @@
+import type { JsBlockBudget } from './js-watchdog.js';
+import type { BridgeEvents } from './shared.js';
+
+export type JsBlockBudgetPolicyOptions = {
+  /** Budget outside any test, hook or file load. */
+  idleMs: number;
+  /** Budget while a setup file or test file loads (module code and `describe` bodies). */
+  fileLoadMs: number;
+  /** Added to a test's or hook's own timeout. */
+  graceMs: number;
+};
+
+export const IDLE_BUDGET_LABEL = 'between test phases';
+
+export const getIdleBudget = (
+  options: JsBlockBudgetPolicyOptions,
+): JsBlockBudget => ({ ms: options.idleMs, label: IDLE_BUDGET_LABEL });
+
+export type JsBlockBudgetPolicy = {
+  /**
+   * Returns the block budget that applies from this event on, or `null` for
+   * events that do not change it.
+   */
+  getBudgetForEvent: (event: BridgeEvents) => JsBlockBudget | null;
+};
+
+/**
+ * Maps runner events to block budgets. Budgets come from timeouts the user
+ * already configures, so long work within them never fails a run:
+ *
+ * - loading a setup file or test file: `fileLoadMs`
+ * - a test, including its `beforeEach`/`afterEach` hooks: its timeout + grace
+ * - a suite's `beforeAll`/`afterAll` hooks: the hook timeout + grace, from
+ *   `suite-started` until `suite-finished`, outside the suite's tests
+ * - anything else: `idleMs`
+ */
+export const createJsBlockBudgetPolicy = (
+  options: JsBlockBudgetPolicyOptions,
+): JsBlockBudgetPolicy => {
+  const idle = getIdleBudget(options);
+  // Hook budgets of the suites currently running, innermost last.
+  const suites: JsBlockBudget[] = [];
+  const outsideTests = () => suites[suites.length - 1] ?? idle;
+
+  return {
+    getBudgetForEvent: (event) => {
+      switch (event.type) {
+        case 'setup-file-bundling-finished':
+          return {
+            ms: options.fileLoadMs,
+            label: `loading setup file ${event.file}`,
+          };
+        case 'collection-started':
+          return { ms: options.fileLoadMs, label: `loading ${event.file}` };
+        case 'setup-file-bundling-failed':
+        case 'collection-finished':
+        case 'file-started':
+        case 'file-finished':
+          suites.length = 0;
+          return idle;
+        case 'suite-started':
+          suites.push(
+            event.timeout === undefined
+              ? outsideTests()
+              : {
+                  ms: event.timeout + options.graceMs,
+                  label: `beforeAll/afterAll hooks of suite "${event.name}" (${event.timeout}ms timeout + ${options.graceMs}ms grace)`,
+                },
+          );
+          return outsideTests();
+        case 'suite-finished':
+          suites.pop();
+          return outsideTests();
+        case 'test-started':
+          if (event.timeout === undefined) {
+            return null;
+          }
+
+          return {
+            ms: event.timeout + options.graceMs,
+            label: `test "${event.fullName}" (${event.timeout}ms timeout + ${options.graceMs}ms grace)`,
+          };
+        case 'test-finished':
+          return outsideTests();
+        default:
+          return null;
+      }
+    },
+  };
+};

package/src/js-watchdog.ts

@@ -0,0 +1,78 @@
+/**
+ * The longest the app's JS thread may go without answering a `js-probe`, and
+ * a label naming what it is busy with, used in the failure message.
+ */
+export type JsBlockBudget = {
+  ms: number;
+  label: string;
+};
+
+export type JsWatchdog = {
+  notifyProbeAck: (id: number) => void;
+  /**
+   * Replaces the current budget. The new budget covers silence from the
+   * later of the last acknowledged probe and the change itself: a block that
+   * fitted the previous budget is never judged against a smaller one.
+   */
+  setBlockBudget: (budget: JsBlockBudget) => void;
+  dispose: () => void;
+};
+
+export const DEFAULT_JS_PROBE_INTERVAL_MS = 1_000;
+
+/**
+ * Checks that the app's JS thread keeps getting a turn to run. The server
+ * sends `js-probe` messages, which only JS can answer, and fails once the
+ * thread has been silent for longer than the current block budget.
+ */
+export const createJsWatchdog = (options: {
+  sendProbe: (id: number) => void;
+  onUnresponsive: (budget: JsBlockBudget) => void;
+  initialBudget: JsBlockBudget;
+  probeIntervalMs?: number;
+}): JsWatchdog => {
+  let budget = options.initialBudget;
+  let lastAckAt = Date.now();
+  let budgetSetAt = lastAckAt;
+  let nextProbeId = 1;
+  let pendingProbeId: number | null = null;
+  let disposed = false;
+
+  const dispose = () => {
+    if (disposed) {
+      return;
+    }
+
+    disposed = true;
+    clearInterval(interval);
+  };
+
+  const interval = setInterval(() => {
+    if (Date.now() - Math.max(lastAckAt, budgetSetAt) > budget.ms) {
+      dispose();
+      options.onUnresponsive(budget);
+      return;
+    }
+
+    if (pendingProbeId === null) {
+      pendingProbeId = nextProbeId++;
+      options.sendProbe(pendingProbeId);
+    }
+  }, options.probeIntervalMs ?? DEFAULT_JS_PROBE_INTERVAL_MS);
+
+  return {
+    notifyProbeAck: (id) => {
+      if (id !== pendingProbeId) {
+        return;
+      }
+
+      pendingProbeId = null;
+      lastAckAt = Date.now();
+    },
+    setBlockBudget: (next) => {
+      budget = next;
+      budgetSetAt = Date.now();
+    },
+    dispose,
+  };
+};

package/src/link/README.md

@@ -0,0 +1,43 @@
+# Link
+
+A copy of the link from [simlock](https://github.com/callstackincubator/simlock)
+(`src/link/`, commit `b730ef37536b51ebdb37d076e7592954c32d0904`), plus the
+standard `WebSocket` transport from simlock's browser link check.
+
+The link wraps one WebSocket and carries two kinds of traffic:
+
+- **Text messages** (`write` / `onData`): the bridge's JSON RPC, events, and
+  heartbeat ping/pong. They go in the priority lane, so they are never stuck
+  behind a large transfer.
+- **Byte channels** (`openChannel` / `acceptChannel`): raw bytes as
+  `ReadableStream` / `WritableStream`, in 64 KiB frames with per-channel credit.
+  The bridge uses them for screenshots (`../binary.ts`).
+
+See simlock's `src/link/AGENTS.md` for the wire format, limits and rules.
+
+## Harness changes
+
+Keep the files close to upstream so they are easy to sync. Changes are marked
+with `harness:` comments:
+
+- `ports.ts` holds the port types the link imports from simlock's `src/ports`,
+  plus `globalClock`.
+- `streams.ts` uses the global WHATWG streams when present and the
+  `web-streams-polyfill` ponyfill otherwise (React Native). It never installs
+  globals.
+- `envelope.ts` encodes channel ids as ASCII instead of using
+  `TextEncoder`/`TextDecoder`.
+- `standard-websocket.ts` treats a missing `bufferedAmount` as `0`, since React
+  Native's `WebSocket` never sets it.
+- `__tests__/` holds upstream's link tests. The in-memory pair and `FakeClock`
+  come from simlock's ports, and the WebSocket pair uses `ws` with
+  `StandardWebSocketConnection` on both ends.
+
+## React Native notes
+
+- React Native's `WebSocket` base64-encodes binary frames on the way to the
+  native module. The protocol is binary, but stock React Native still pays for
+  that encoding inside the socket.
+- With no `bufferedAmount`, the link cannot see the socket's send buffer, so
+  only per-channel credit (4 MiB) limits how much is in flight.
+- There is no `crypto.randomUUID`, so the client passes `generateId`.