@uniflowed/test 0.0.0-alpha.40 → 0.0.0-alpha.41

package/app-browser.js

@@ -0,0 +1,6 @@
+// @flow
+export function createTestApp(_options?: mixed): empty {
+  throw new Error(
+    "createTestApp runs in a Node test worker. Run this test with uf test, and use createBrowser() to check its RSC hydration in Chromium.",
+  );
+}

package/app.js

@@ -0,0 +1,175 @@
+// @flow
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+export type AppTestOptions = {|
+  readonly root: string | URL,
+  readonly binary?: string,
+  readonly env?: { readonly [string]: string },
+  readonly timeoutMs?: number,
+|};
+
+export type AppRequest = {|
+  readonly method?: string,
+  readonly headers?: { readonly [string]: string },
+  readonly body?: string,
+  readonly signal?: AbortSignal,
+|};
+
+export type TestApp = {|
+  /** The live URL, including after an environment-triggered restart. */
+  readonly origin: () => string,
+  readonly fetch: (pathname: string, options?: AppRequest) => Promise<Response>,
+  readonly render: (pathname: string, options?: AppRequest) => Promise<Response>,
+  /** The actual React Flight stream, with request headers and Suspense intact. */
+  readonly flight: (pathname: string, options?: AppRequest) => Promise<Response>,
+  readonly events: () => $ReadOnlyArray<{ readonly [string]: mixed }>,
+  readonly close: () => Promise<void>,
+|};
+
+/** Start the application's real web pipeline in an isolated process for `uf test`. */
+export async function createTestApp(options: AppTestOptions): Promise<TestApp> {
+  const root = path.resolve(
+    options.root instanceof URL ? fileURLToPath(options.root.href) : options.root,
+  );
+  const timeout = options.timeoutMs ?? 30000;
+  if (!Number.isFinite(timeout) || timeout <= 0)
+    throw new TypeError("test app timeout must be positive");
+  const child = spawn(
+    options.binary ?? process.env.UF_BINARY ?? "uf",
+    [
+      "--cwd",
+      root,
+      "dev",
+      "--json",
+      "--parent-pipe",
+      "--target",
+      "web",
+      "--host",
+      "127.0.0.1",
+      "--port",
+      "0",
+    ],
+    { env: { ...process.env, ...options.env }, stdio: ["pipe", "pipe", "pipe"] },
+  );
+  const events: Array<{ readonly [string]: mixed }> = [];
+  let transcript = "";
+  let origin = "";
+  let ended = false;
+  const exited = new Promise<void>((resolve) =>
+    // The CLI exits before its Vite driver's inherited streams close. Wait for
+    // those streams too, so close() includes server and diagnostic cleanup.
+    child.once("close", () => {
+      ended = true;
+      resolve();
+    }),
+  );
+  let closing = null;
+  const close = (): Promise<void> => {
+    if (closing != null) return closing;
+    closing = (async () => {
+      if (ended) return;
+      child.stdin?.end();
+      const timer = setTimeout(() => child.kill("SIGKILL"), 3000);
+      try {
+        await exited;
+      } finally {
+        clearTimeout(timer);
+      }
+    })();
+    return closing;
+  };
+  child.stderr?.on("data", (chunk) => {
+    transcript = (transcript + String(chunk)).slice(-16384);
+  });
+  const lines = createInterface({ input: child.stdout });
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error(`test app did not start within ${timeout}ms\n${transcript}`)),
+        timeout,
+      );
+      const fail = (error: mixed) => {
+        clearTimeout(timer);
+        reject(error);
+      };
+      child.once("error", (error) => {
+        ended = true;
+        fail(error);
+      });
+      child.once("exit", (code) =>
+        fail(new Error(`test app exited (${String(code)})\n${transcript}`)),
+      );
+      lines.on("line", (line) => {
+        let event;
+        try {
+          event = JSON.parse(line);
+        } catch {
+          transcript = (transcript + line + "\n").slice(-16384);
+          return;
+        }
+        events.push(event);
+        if (events.length > 200) events.shift();
+        if (event.event === "listening" && typeof event.local?.[0] === "string") {
+          origin = new URL(event.local[0]).origin;
+          clearTimeout(timer);
+          resolve();
+        } else if (event.event === "error") {
+          fail(new Error(`test app: ${String(event.message)}`));
+        }
+      });
+    });
+  } catch (error) {
+    await close();
+    throw error;
+  }
+  function address(pathname: string): URL {
+    if (ended || closing != null) throw new Error("test app is closed");
+    if (!pathname.startsWith("/") || pathname.startsWith("//") || pathname.includes("\\")) {
+      throw new TypeError("test app needs an absolute path on its own origin");
+    }
+    const url = new URL(pathname, origin);
+    if (url.origin !== origin) throw new TypeError("test app cannot fetch another origin");
+    return url;
+  }
+  const request = async (url: URL, init?: AppRequest): Promise<Response> => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    try {
+      return await fetch(url.href, {
+        ...init,
+        headers: { ...init?.headers },
+        signal:
+          init?.signal == null
+            ? controller.signal
+            : AbortSignal.any([init.signal, controller.signal]),
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+  return {
+    origin: () => origin,
+    fetch: async (pathname, init) => request(address(pathname), init),
+    render: async (pathname, init) => {
+      const headers = new Headers({ ...init?.headers });
+      headers.set("accept", "text/html");
+      return request(address(pathname), { ...init, headers: Object.fromEntries(headers) });
+    },
+    flight: async (pathname, init) => {
+      const url = address(pathname);
+      url.pathname = `${url.pathname.replace(/\/$/, "")}/__uf.flight`;
+      const response = await request(url, init);
+      if (!(response.headers.get("content-type") ?? "").includes("text/x-component")) {
+        throw new Error(
+          `test app returned ${response.status} without a Flight stream; enable RSC for this route`,
+        );
+      }
+      return response;
+    },
+    events: () => [...events],
+    close,
+  };
+}

package/browser-worker.js

@@ -22,22 +22,13 @@
 // browser is the host under test, and the split is named in `docs/hosts.md`
 // rather than left for a reader to infer from a stack trace.
 //
-// # What this depends on, exactly
+// # Browser control
 //
-// One browser binary, already installed, found or named by
-// `crates/uf_test/src/browser.rs` and handed over in `UF_BROWSER`. Not
-// downloaded, not vendored, not version-pinned, and not a driver library:
-// there is no Playwright, no Puppeteer and no DevTools protocol here. The
-// browser is started with a URL and a scratch profile and is otherwise left
-// alone; everything uf needs to know comes back over HTTP from the page's own
-// code.
-//
-// That is a deliberate ceiling as much as a deliberate floor. **uf cannot
-// drive this browser** — it cannot click, navigate, screenshot, throttle a
-// network or read a console it was not handed. Those are the other half of
-// `docs/roadmap.md`'s "Playwright-compatible browser automation" and they want
-// a protocol; this half only wants a page, and buying the protocol to get the
-// page would have made a test runner own a browser automation library.
+// Chromium is selected by `UF_BROWSER` or the CLI's browser discovery. Tests
+// use `@uniflowed/test/browser` to create isolated pages, send trusted input,
+// navigate and compare screenshots. The controller speaks CDP over a private
+// pipe; the harness page relays bounded commands through its authenticated
+// loopback endpoint. Closing the worker's pipe also terminates Chromium.
 //
 // # How this fails
 //
@@ -57,6 +48,7 @@ import path from "node:path";
 import { inSourceTests, sharedService } from "@uniflowed/host/transform";
 
 import { create } from "./internal/browser/server.js";
+import { connectPipe } from "./internal/browser/cdp.js";
 
 /** What `uf` sends for one file. */
 type Request = {|
@@ -104,11 +96,8 @@ function browserArguments(profile: string, url: string): Array<string> {
     // timeout eventually cannot run. Chrome treats the pipe as its lifeline:
     // when the file descriptors close, for any reason, it shuts itself down.
     //
-    // Not a protocol. uf opens the two descriptors and never writes a byte to
-    // them; the page reports over HTTP, as everything else here does. The pipe
-    // is also why this is not `--remote-debugging-port`, which would open a
-    // port on the machine that anything could speak to — a pipe is held by this
-    // process alone.
+    // The same private pipe carries CDP commands for pages created by tests.
+    // It exposes no debugging port to other local browser origins.
     //
     // The tab closing is not enough on its own, which is what this replaces: a
     // page that calls `window.close()` frees the renderers and leaves the
@@ -173,8 +162,13 @@ async function main(): Promise<void> {
   const browser = process.env.UF_BROWSER;
   const service = sharedService(root);
 
+  let controller = null;
   const server = await create({
     root,
+    browserCommand: async (id, method, args) => {
+      if (controller == null) throw new Error("browser driver is not ready");
+      return controller.command(id, method, args);
+    },
     transform: async (id, code) => {
       // The same three the Node loader passes (`packages/host/internal/
       // node-hooks.js`), so a module means the same thing on both hosts.
@@ -207,7 +201,12 @@ async function main(): Promise<void> {
   });
 
   server.onEvent((event) => {
-    write(event);
+    if (event.event === "file" && controller != null) {
+      void controller.closePages().then(
+        () => write(event),
+        (error) => refuse(String(error), Number(event.generation ?? 0)),
+      );
+    } else write(event);
   });
 
   if (browser == null || browser === "") {
@@ -223,15 +222,11 @@ async function main(): Promise<void> {
 
   const profile = mkdtempSync(path.join(tmpdir(), "uf-browser-"));
   // Five descriptors, because `--remote-debugging-pipe` reads 3 and writes 4.
-  // They are opened and never used; see the flag's note for what that buys.
+  // The controller below exchanges null-delimited CDP messages on them.
   const child = spawn(browser, browserArguments(profile, server.url), {
     stdio: ["ignore", "pipe", "pipe", "pipe", "pipe"],
   });
-  // The DevTools pipe is a lifeline, not a protocol this driver speaks. Chrome
-  // can still write target bookkeeping to fd 4 before the page asks for work;
-  // drain it so a full pipe cannot block startup before the first HTTP request.
-  const devtoolsOutput = child.stdio[4];
-  devtoolsOutput?.on("data", () => {});
+  controller = connectPipe(child, { root });
   // Kept, not printed. A Chromium writes a dozen lines about GPU probing and
   // Vulkan on a healthy start, and forwarding those to a passing run's report
   // would be noise; they are the whole of the evidence when it does not start,

package/browser.js

@@ -0,0 +1,59 @@
+// @flow
+import { createTransport } from "./internal/browser/transport.js";
+
+export type Viewport = {|
+  readonly width: number,
+  readonly height: number,
+  readonly deviceScaleFactor?: number,
+|};
+export type ScreenshotResult = {|
+  readonly baseline: string,
+  readonly updated: boolean,
+  readonly differentPixels: number,
+|};
+export type BrowserOptions = {|
+  readonly executable?: string,
+  readonly timeoutMs?: number,
+|};
+export type TestPage = {|
+  readonly visit: (url: string) => Promise<void>,
+  readonly setContent: (html: string) => Promise<void>,
+  readonly waitFor: (selector: string) => Promise<void>,
+  readonly text: (selector: string) => Promise<string | null>,
+  readonly value: (selector: string) => Promise<string | null>,
+  readonly url: () => Promise<string>,
+  readonly click: (selector: string) => Promise<void>,
+  readonly fill: (selector: string, text: string) => Promise<void>,
+  readonly press: (key: string) => Promise<void>,
+  readonly tap: (selector: string) => Promise<void>,
+  readonly viewport: (viewport: Viewport) => Promise<void>,
+  readonly screenshot: (
+    name: string,
+    options?: {| readonly threshold?: number, readonly baselines?: string |},
+  ) => Promise<ScreenshotResult>,
+  readonly events: () => Promise<$ReadOnlyArray<{ readonly [string]: mixed }>>,
+  readonly close: () => Promise<void>,
+|};
+
+/** An isolated Chromium page; the test harness stays alive across navigations. */
+export async function createBrowser(options?: BrowserOptions): Promise<TestPage> {
+  const transport = await createTransport(options ?? {});
+  const call = (method: string, args: $ReadOnlyArray<mixed> = []) =>
+    transport.command(transport.id, method, args);
+  return {
+    visit: (url) => call("visit", [url]),
+    setContent: (html) => call("setContent", [html]),
+    waitFor: (selector) => call("waitFor", [selector]),
+    text: (selector) => call("text", [selector]),
+    value: (selector) => call("value", [selector]),
+    url: () => call("url"),
+    click: (selector) => call("click", [selector]),
+    fill: (selector, text) => call("fill", [selector, text]),
+    press: (key) => call("press", [key]),
+    tap: (selector) => call("tap", [selector]),
+    viewport: (viewport) => call("viewport", [viewport]),
+    screenshot: (name, options) => call("screenshot", [name, options]),
+    events: () => call("events"),
+    close: transport.close,
+  };
+}

package/internal/browser/cdp.js

@@ -0,0 +1,364 @@
+// @flow
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { compareScreenshot } from "./screenshots.js";
+
+// CDP replies are JSON selected by the command name. Keep that untyped wire
+// boundary here; the application-facing page API has concrete Flow types.
+type WireValue = $FlowFixMe;
+export type ControlOptions = {|
+  readonly root?: string,
+  readonly baselines?: string,
+  readonly threshold?: number,
+  readonly executable?: string,
+  readonly timeoutMs?: number,
+|};
+export type BrowserTransport = {|
+  readonly id: string,
+  readonly command: (
+    id: string | null,
+    method: string,
+    args?: $ReadOnlyArray<WireValue>,
+  ) => Promise<WireValue>,
+  readonly close: () => Promise<void>,
+|};
+type Pending = {|
+  timer: TimeoutID,
+  resolve: (value: WireValue) => void,
+  reject: (error: Error) => void,
+|};
+
+/** CDP over the private pipe: closing the test worker also closes Chromium. */
+export function connectPipe(child: $FlowFixMe, options: ControlOptions = {}) {
+  let sequence = 0;
+  let buffered = "";
+  let closed = false;
+  const pending: Map<number, Pending> = new Map();
+  const pages: Map<string, string> = new Map();
+  const events: Map<string, Array<WireValue>> = new Map();
+  const loaded: Map<string, Set<string>> = new Map();
+  const output = child.stdio[4];
+  output.setEncoding("utf8");
+  output.on("data", (chunk) => {
+    buffered += chunk;
+    for (let end; (end = buffered.indexOf("\0")) !== -1; ) {
+      const raw = buffered.slice(0, end);
+      buffered = buffered.slice(end + 1);
+      if (!raw) continue;
+      const message = JSON.parse(raw);
+      const task = pending.get(message.id);
+      if (task) {
+        pending.delete(message.id);
+        clearTimeout(task.timer);
+        if (message.error) task.reject(new Error(message.error.message));
+        else task.resolve(message.result);
+      } else if (message.sessionId && events.has(message.sessionId)) {
+        if (message.method === "Page.lifecycleEvent" && message.params.name === "load")
+          loaded.get(message.sessionId)?.add(message.params.loaderId);
+        if (["Runtime.exceptionThrown", "Runtime.consoleAPICalled"].includes(message.method)) {
+          const history = events.get(message.sessionId);
+          if (history == null) continue;
+          history.push({ method: message.method, ...message.params });
+          if (history.length > 100) history.shift();
+        }
+      }
+    }
+  });
+  const disconnect = () => {
+    closed = true;
+    for (const task of pending.values()) {
+      clearTimeout(task.timer);
+      task.reject(new Error("test browser closed"));
+    }
+    pending.clear();
+  };
+  child.once("exit", disconnect);
+  child.once("error", disconnect);
+  child.stdio[3].on("error", disconnect);
+  function send(
+    method: string,
+    params: { readonly [string]: mixed } = {},
+    sessionId?: string,
+  ): Promise<WireValue> {
+    if (closed) return Promise.reject(new Error("test browser closed"));
+    const id = ++sequence;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(new Error(`CDP timed out: ${method}`));
+      }, options.timeoutMs ?? 15000);
+      pending.set(id, { resolve, reject, timer });
+      child.stdio[3].write(JSON.stringify({ id, method, params, sessionId }) + "\0");
+    });
+  }
+  async function evaluate(sessionId: string, expression: string): Promise<WireValue> {
+    const result = await send(
+      "Runtime.evaluate",
+      { expression, returnByValue: true, awaitPromise: true },
+      sessionId,
+    );
+    if (result.exceptionDetails)
+      throw new Error(
+        result.exceptionDetails.exception?.description ?? result.exceptionDetails.text,
+      );
+    return result.result.value;
+  }
+  async function until(
+    session: string,
+    expression: string,
+    description: string,
+  ): Promise<WireValue> {
+    const end = Date.now() + (options.timeoutMs ?? 15000);
+    while (Date.now() < end) {
+      try {
+        const result = await evaluate(session, expression);
+        if (result) return result;
+      } catch (error) {
+        if (!/context|navigat/i.test(error.message)) throw error;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    throw new Error(`test browser timed out waiting for ${description}`);
+  }
+  async function point(session: string, selector: string): Promise<{| x: number, y: number |}> {
+    return until(
+      session,
+      `(() => {
+      const element = document.querySelector(${JSON.stringify(selector)});
+      if (!element || element.disabled) return null;
+      element.scrollIntoView({block:"center", inline:"center", behavior:"instant"});
+      const box = element.getBoundingClientRect();
+      if (!box.width || !box.height || getComputedStyle(element).visibility !== "visible") return null;
+      const x = box.x + box.width / 2, y = box.y + box.height / 2;
+      const top = document.elementFromPoint(x, y);
+      return top && (top === element || element.contains(top)) ? {x,y} : null;
+    })()`,
+      `actionable ${selector}`,
+    );
+  }
+  async function createPage(): Promise<string> {
+    const { targetId } = await send("Target.createTarget", { url: "about:blank" });
+    const { sessionId } = await send("Target.attachToTarget", { targetId, flatten: true });
+    pages.set(targetId, sessionId);
+    events.set(sessionId, []);
+    loaded.set(sessionId, new Set());
+    await send("Page.enable", {}, sessionId);
+    await send("Page.setLifecycleEventsEnabled", { enabled: true }, sessionId);
+    await send("Runtime.enable", {}, sessionId);
+    return targetId;
+  }
+  async function command(
+    id: string | null,
+    method: string,
+    args: $ReadOnlyArray<WireValue> = [],
+  ): Promise<WireValue> {
+    if (method === "create") return createPage();
+    if (id == null) throw new Error("unknown test page");
+    const session = pages.get(id);
+    if (!session) throw new Error("unknown or closed test page");
+    const [first, second] = args;
+    switch (method) {
+      case "visit": {
+        const url = new URL(first);
+        if (!["http:", "https:", "about:"].includes(url.protocol))
+          throw new Error("test page visit supports HTTP(S) URLs and about:blank");
+        const result = await send("Page.navigate", { url: url.href }, session);
+        if (result.errorText) throw new Error(result.errorText);
+        if (result.loaderId) {
+          const deadline = Date.now() + (options.timeoutMs ?? 15000);
+          while (loaded.get(session)?.has(result.loaderId) !== true) {
+            if (closed || Date.now() >= deadline)
+              throw new Error("test browser timed out waiting for document load");
+            await new Promise((resolve) => setTimeout(resolve, 25));
+          }
+        }
+        await until(session, "document.readyState === 'complete'", "document load");
+        return;
+      }
+      case "setContent": {
+        const { frameTree } = await send("Page.getFrameTree", {}, session);
+        await send(
+          "Page.setDocumentContent",
+          { frameId: frameTree.frame.id, html: first },
+          session,
+        );
+        return;
+      }
+      case "waitFor":
+        await until(session, `!!document.querySelector(${JSON.stringify(first)})`, first);
+        return;
+      case "text":
+        return evaluate(
+          session,
+          `document.querySelector(${JSON.stringify(first)})?.textContent ?? null`,
+        );
+      case "value":
+        return evaluate(session, `document.querySelector(${JSON.stringify(first)})?.value ?? null`);
+      case "url":
+        return evaluate(session, "location.href");
+      case "events":
+        return [...(events.get(session) ?? [])];
+      case "viewport": {
+        const { width, height, deviceScaleFactor = 1 } = first;
+        if (
+          ![width, height, deviceScaleFactor].every(
+            (value) => Number.isFinite(value) && value > 0,
+          ) ||
+          width > 8192 ||
+          height > 8192 ||
+          deviceScaleFactor > 4
+        )
+          throw new Error("invalid test viewport");
+        await send(
+          "Emulation.setDeviceMetricsOverride",
+          { width, height, deviceScaleFactor, mobile: false },
+          session,
+        );
+        return;
+      }
+      case "click": {
+        const position = await point(session, first);
+        await send(
+          "Input.dispatchMouseEvent",
+          { type: "mousePressed", ...position, button: "left", clickCount: 1 },
+          session,
+        );
+        await send(
+          "Input.dispatchMouseEvent",
+          { type: "mouseReleased", ...position, button: "left", clickCount: 1 },
+          session,
+        );
+        return;
+      }
+      case "fill": {
+        await command(id, "click", [first]);
+        await evaluate(
+          session,
+          `(() => {const input = document.querySelector(${JSON.stringify(first)}); input.focus(); if (!input.matches('input,textarea')) throw new Error('fill needs an input or textarea'); input.select();})()`,
+        );
+        await send("Input.insertText", { text: second }, session);
+        return;
+      }
+      case "press": {
+        const keys = {
+          Enter: 13,
+          Tab: 9,
+          Escape: 27,
+          Backspace: 8,
+          ArrowLeft: 37,
+          ArrowUp: 38,
+          ArrowRight: 39,
+          ArrowDown: 40,
+          " ": 32,
+        };
+        if (!(first in keys)) throw new Error(`unsupported test key ${first}`);
+        const params = {
+          key: first,
+          windowsVirtualKeyCode: keys[first],
+          ...(first === "Enter" ? { text: "\r" } : first === " " ? { text: " " } : {}),
+        };
+        await send("Input.dispatchKeyEvent", { type: "keyDown", ...params }, session);
+        await send(
+          "Input.dispatchKeyEvent",
+          { type: "keyUp", key: first, windowsVirtualKeyCode: keys[first] },
+          session,
+        );
+        return;
+      }
+      case "tap": {
+        const position = await point(session, first);
+        await send("Emulation.setTouchEmulationEnabled", { enabled: true }, session);
+        try {
+          await send(
+            "Input.dispatchTouchEvent",
+            { type: "touchStart", touchPoints: [{ ...position, id: 1 }] },
+            session,
+          );
+          await send("Input.dispatchTouchEvent", { type: "touchEnd", touchPoints: [] }, session);
+        } finally {
+          await send("Emulation.setTouchEmulationEnabled", { enabled: false }, session);
+        }
+        return;
+      }
+      case "screenshot": {
+        await evaluate(
+          session,
+          "document.fonts.ready.then(() => new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r))))",
+        );
+        const { data } = await send(
+          "Page.captureScreenshot",
+          { format: "png", captureBeyondViewport: false },
+          session,
+        );
+        return compareScreenshot(data, first, {
+          root: options.root,
+          threshold: second?.threshold ?? options.threshold,
+          baselines: second?.baselines ?? options.baselines,
+        });
+      }
+      case "close":
+        await send("Target.closeTarget", { targetId: id });
+        pages.delete(id);
+        events.delete(session);
+        loaded.delete(session);
+        return;
+      default:
+        throw new Error(`unknown test browser command ${method}`);
+    }
+  }
+  return {
+    command,
+    closePages: async () => {
+      for (const id of [...pages.keys()]) await command(id, "close");
+    },
+  };
+}
+
+export async function launchBrowser(options: ControlOptions = {}): Promise<BrowserTransport> {
+  const executable = options.executable ?? process.env.UF_BROWSER;
+  if (!executable) throw new Error("Set UF_BROWSER to a Chromium executable for createBrowser()");
+  const profile = mkdtempSync(path.join(tmpdir(), "uf-test-cdp-"));
+  const child = spawn(
+    executable,
+    [
+      "--headless=new",
+      "--remote-debugging-pipe",
+      `--user-data-dir=${profile}`,
+      "--no-first-run",
+      "--no-default-browser-check",
+      "--disable-dev-shm-usage",
+      "--disable-background-networking",
+      "--password-store=basic",
+      "about:blank",
+    ],
+    { stdio: ["ignore", "ignore", "pipe", "pipe", "pipe"] },
+  );
+  let stderr = "";
+  child.stderr.on("data", (chunk) => {
+    stderr = (stderr + chunk).slice(-8192);
+  });
+  const controller = connectPipe(child, options);
+  const exited = new Promise((resolve) => {
+    child.once("exit", resolve);
+    child.once("error", resolve);
+  });
+  let closing: Promise<void> | void;
+  const close = (): Promise<void> => {
+    if (closing != null) return closing;
+    const done = (async (): Promise<void> => {
+      child.kill("SIGKILL");
+      await exited;
+      rmSync(profile, { recursive: true, force: true, maxRetries: 3 });
+    })();
+    closing = done;
+    return done;
+  };
+  try {
+    return { id: await controller.command(null, "create"), command: controller.command, close };
+  } catch (error) {
+    await close();
+    throw new Error(`${error.message}\n${stderr}`);
+  }
+}

package/internal/browser/page-transport.js

@@ -0,0 +1,36 @@
+// @flow
+import type { BrowserTransport, ControlOptions } from "./cdp.js";
+
+export async function createTransport(options: ControlOptions): Promise<BrowserTransport> {
+  if (options.executable != null)
+    throw new Error("uf test --browser selects its own UF_BROWSER executable");
+  const token = (globalThis as $FlowFixMe)[Symbol.for("uf.test.browser.token")];
+  if (typeof token !== "string")
+    throw new Error("createBrowser needs uf test --browser or a Node test worker");
+  async function command(
+    id: string | null,
+    method: string,
+    args: $ReadOnlyArray<mixed> = [],
+  ): Promise<$FlowFixMe> {
+    const response = await fetch("/uf-test/browser", {
+      method: "POST",
+      headers: { "content-type": "application/json", "uf-test-browser": token },
+      body: JSON.stringify({ id, method, args }),
+    });
+    const result = await response.json();
+    if (!response.ok || result.error)
+      throw new Error(result.error ?? `browser command failed (${response.status})`);
+    return result.value;
+  }
+  const id = await command(null, "create");
+  let closed = false;
+  return {
+    id,
+    command,
+    close: async () => {
+      if (closed) return;
+      closed = true;
+      await command(id, "close");
+    },
+  };
+}

package/internal/browser/screenshots.js

@@ -0,0 +1,102 @@
+// @flow
+import { readFile, writeFile, mkdir, realpath, lstat } from "node:fs/promises";
+import path from "node:path";
+import { PNG } from "pngjs";
+import pixelmatch from "pixelmatch";
+
+export type ScreenshotOptions = {|
+  readonly root?: string,
+  readonly baselines?: string,
+  readonly threshold?: number,
+|};
+
+/** Baselines stay under the project's configured directory, including through symlinks. */
+export async function compareScreenshot(
+  data: string,
+  name: string,
+  options: ScreenshotOptions = {},
+) {
+  if (
+    typeof name !== "string" ||
+    !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,119}$/.test(name) ||
+    name.includes("..") ||
+    /\.(actual|diff)$/.test(name)
+  )
+    throw new Error("screenshot name must be a simple file name without traversal");
+  const config = JSON.parse(process.env.UF_VRT_CONFIG ?? "{}");
+  const root = await realpath(options.root ?? process.env.UF_PROJECT_ROOT ?? process.cwd());
+  const directory = path.resolve(root, options.baselines ?? config.baselines ?? "__uf_vrt__");
+  if (!directory.startsWith(root + path.sep))
+    throw new Error("vrt.baselines must stay inside the test project");
+  // Check each existing ancestor before creating anything through it.
+  let ancestor = root;
+  for (const segment of path.relative(root, directory).split(path.sep)) {
+    ancestor = path.join(ancestor, segment);
+    try {
+      if ((await lstat(ancestor)).isSymbolicLink())
+        throw new Error("vrt.baselines cannot traverse a symlink");
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  await mkdir(directory, { recursive: true });
+  const baseline = path.join(directory, `${name}.png`);
+  try {
+    if ((await lstat(baseline)).isSymbolicLink())
+      throw new Error("screenshot baseline cannot be a symlink");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  const bytes = Buffer.from(data, "base64");
+  const actual = PNG.sync.read(bytes);
+  const threshold = options.threshold ?? config.threshold ?? 0;
+  if (!Number.isInteger(threshold) || threshold < 0)
+    throw new Error("vrt.threshold is the maximum number of different pixels");
+  if (process.env.UF_UPDATE_SNAPSHOTS === "1") {
+    await writeFile(baseline, bytes);
+    return { baseline, updated: true, differentPixels: 0 };
+  }
+  let expected;
+  try {
+    expected = PNG.sync.read(await readFile(baseline));
+  } catch (error) {
+    if (error.code === "ENOENT")
+      throw new Error(`missing screenshot baseline ${baseline}; record it with uf test -u`);
+    throw error;
+  }
+  const width = Math.max(actual.width, expected.width),
+    height = Math.max(actual.height, expected.height);
+  const diff = new PNG({ width, height });
+  const sameSize = actual.width === expected.width && actual.height === expected.height;
+  let differentPixels;
+  if (sameSize)
+    differentPixels = pixelmatch(actual.data, expected.data, diff.data, width, height, {
+      threshold: 0.1,
+      includeAA: true,
+    });
+  else {
+    differentPixels = width * height;
+    for (let i = 0; i < diff.data.length; i += 4) {
+      diff.data[i] = 255;
+      diff.data[i + 3] = 255;
+    }
+  }
+  if (!sameSize || differentPixels > threshold) {
+    const actualFile = path.join(directory, `${name}.actual.png`);
+    const diffFile = path.join(directory, `${name}.diff.png`);
+    for (const file of [actualFile, diffFile]) {
+      try {
+        if ((await lstat(file)).isSymbolicLink())
+          throw new Error("screenshot output cannot be a symlink");
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+    await writeFile(actualFile, bytes);
+    await writeFile(diffFile, PNG.sync.write(diff));
+    throw new Error(
+      `screenshot ${name}: ${differentPixels} pixels differ (allowed ${threshold})${sameSize ? "" : "; dimensions changed"}; diff: ${diffFile}`,
+    );
+  }
+  return { baseline, updated: false, differentPixels };
+}

package/internal/browser/server.js

@@ -51,6 +51,7 @@
 // worth not having at all.
 
 import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
 import { createRequire } from "node:module";
 import { readFileSync, readdirSync, realpathSync } from "node:fs";
 import path from "node:path";
@@ -122,6 +123,11 @@ export type PageRequest = {|
 
 /** How `create` is configured. */
 export type ServerOptions = {|
+  readonly browserCommand?: (
+    id: mixed,
+    method: string,
+    args: $ReadOnlyArray<mixed>,
+  ) => Promise<mixed>,
   /** The project root; every served file must be under this or a package. */
   readonly root: string,
   /** Transforms a Flow module, or answers `null` when it is not uf's. */
@@ -139,6 +145,7 @@ export type ServerOptions = {|
  */
 export async function create(options: ServerOptions): Promise<ModuleServer> {
   const root = realpathSync(options.root);
+  const browserToken = randomUUID();
   const packages = crawlPackages(root);
   const map = importMap(packages);
   const roots = [root, ...packages.map((entry) => entry.directory)];
@@ -180,7 +187,7 @@ export async function create(options: ServerOptions): Promise<ModuleServer> {
     const at = url.indexOf("?");
     const route = at === -1 ? url : url.slice(0, at);
     if (route === "/" || route === PAGE_PATH) {
-      reply(outgoing, 200, "text/html; charset=utf-8", harnessHtml(map));
+      reply(outgoing, 200, "text/html; charset=utf-8", harnessHtml(map, browserToken));
       return;
     }
     if (route === "/uf-test/next") {
@@ -198,6 +205,46 @@ export async function create(options: ServerOptions): Promise<ModuleServer> {
       });
       return;
     }
+    if (route === "/uf-test/browser") {
+      const origin = `http://127.0.0.1:${String(port)}`;
+      if (
+        incoming.method !== "POST" ||
+        incoming.headers.origin !== origin ||
+        incoming.headers.host !== `127.0.0.1:${String(port)}` ||
+        incoming.headers["uf-test-browser"] !== browserToken
+      ) {
+        reply(
+          outgoing,
+          403,
+          "application/json",
+          JSON.stringify({ error: "invalid test browser request" }),
+        );
+        return;
+      }
+      readBody(incoming, (body) => {
+        void (async () => {
+          try {
+            const { id, method, args } = JSON.parse(body);
+            if (
+              typeof method !== "string" ||
+              !Array.isArray(args) ||
+              options.browserCommand == null
+            )
+              throw new Error("invalid browser command");
+            const value = await options.browserCommand(id, method, args);
+            reply(outgoing, 200, "application/json", JSON.stringify({ value }));
+          } catch (error) {
+            reply(
+              outgoing,
+              400,
+              "application/json",
+              JSON.stringify({ error: error instanceof Error ? error.message : String(error) }),
+            );
+          }
+        })();
+      });
+      return;
+    }
     if (route === "/uf-test/events") {
       readBody(incoming, (body) => {
         for (const event of parseEvents(body, options.warn)) {
@@ -324,6 +371,8 @@ async function serveFile(
       `${absolute} is outside this project and the packages it depends on, so the browser is not being handed it`,
     );
   }
+  if (/\.html$/.test(real))
+    return { body: readFileSync(real, "utf8"), type: "text/html; charset=utf-8" };
   if (!/\.(?:js|jsx|mjs|cjs)$/.test(real)) {
     // A JSON import, a stylesheet, an asset. Not this change: a page can have
     // them and `uf test --browser` has no opinion about what they should mean
@@ -582,13 +631,14 @@ export function moduleUrl(file: string): string {
  * differently — a layout answer from a quirks-mode page would be a wrong
  * answer wearing a real browser's authority.
  */
-function harnessHtml(map: string): string {
+function harnessHtml(map: string, browserToken: string): string {
   const page = moduleUrl(fileURLToPath(new URL("./page.js", import.meta.url).href));
   return [
     "<!doctype html>",
     '<html lang="en">',
     '<meta charset="utf-8">',
     "<title>uf test</title>",
+    `<script>globalThis[Symbol.for("uf.test.browser.token")]=${JSON.stringify(browserToken)}</script>`,
     `<script type="importmap">${map}</script>`,
     `<script type="module" src="${page}"></script>`,
     "",
@@ -835,7 +885,9 @@ function browserField(entry: Package): { [string]: string } {
     // an empty module is a silence, and silence is what the whole `browser`
     // shim in this package exists not to be. Nothing uf ships uses it.
     if (typeof target !== "string") continue;
-    substitutions[key] = target.startsWith(".") ? join(entry, target) : target;
+    substitutions[key.startsWith(".") ? join(entry, key) : key] = target.startsWith(".")
+      ? join(entry, target)
+      : target;
   }
   return substitutions;
 }

package/internal/browser/transport.js

@@ -0,0 +1,2 @@
+// @flow
+export { launchBrowser as createTransport } from "./cdp.js";

package/internal/native-globals.js

@@ -0,0 +1,14 @@
+// @flow
+// The facade returns the outer uf worker's registry, not another test runner.
+const environment: $FlowFixMe = globalThis;
+const api = environment.__UF_NATIVE_TEST_API__;
+export const test = api.test;
+export const it = api.it;
+export const describe = api.describe;
+export const beforeAll = api.beforeAll;
+export const afterAll = api.afterAll;
+export const beforeEach = api.beforeEach;
+export const afterEach = api.afterEach;
+export const expect = api.expect;
+export const fn = api.fn;
+export const spyOn = api.spyOn;

package/internal/native-host.js

@@ -0,0 +1,97 @@
+// @flow
+// Jest's module environment executes RN's own mocks. uf still owns discovery,
+// scheduling, hooks, timeouts, isolation and the result protocol.
+
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as tests from "../index.js";
+
+// Optional, application-owned environment modules cross one dynamic boundary.
+type EnvironmentModule = $FlowFixMe;
+
+export async function loadNativeFile(file: string): Promise<() => Promise<void>> {
+  const rootDir = process.cwd();
+  const require = createRequire(path.join(rootDir, "package.json"));
+  const load = (name: string): EnvironmentModule => {
+    try {
+      return require(name);
+    } catch (cause) {
+      throw new Error(
+        `uf test (react-native): install ${name} in the application; the native environment could not load it`,
+        { cause },
+      );
+    }
+  };
+  const Runtime = load("jest-runtime").default;
+  const { readConfig } = load("jest-config");
+  const { createScriptTransformer } = load("@jest/transform");
+  const { jestExpect } = load("@jest/expect");
+  const { projectConfig: config, globalConfig } = await readConfig(
+    {
+      config: JSON.stringify({
+        rootDir,
+        preset: "@react-native/jest-preset",
+        cacheDirectory: path.join(rootDir, ".uf", "native-test-cache"),
+        moduleNameMapper: {
+          "^@uniflowed/test$": fileURLToPath(new URL("./native-globals.js", import.meta.url).href),
+        },
+        transform: {
+          "^.+\\.[jt]sx?$": require.resolve("@uniflowed/react-native/test-transformer.cjs"),
+        },
+        transformIgnorePatterns: [
+          "node_modules/(?!((jest-)?react-native|@react-native(-community)?|@react-navigation|@uniflowed|react-native-screens|react-native-safe-area-context)/)",
+        ],
+      }),
+    },
+    rootDir,
+  );
+  const context = await Runtime.createContext(config, {
+    console,
+    maxWorkers: 1,
+    watch: false,
+    watchman: false,
+  });
+  const Environment = load(config.testEnvironment);
+  const environment = new (Environment.TestEnvironment ?? Environment)(
+    { projectConfig: config, globalConfig },
+    { console, testPath: file, docblockPragmas: {} },
+  );
+  await environment.setup();
+  let runtime: EnvironmentModule = null;
+  let closed = false;
+  const close = async () => {
+    if (closed) return;
+    closed = true;
+    try {
+      runtime?.leaveTestCode();
+      runtime?.teardown();
+    } finally {
+      await environment.teardown();
+    }
+  };
+  try {
+    const transformer = await createScriptTransformer(config, new Map());
+    runtime = new Runtime(
+      config,
+      environment,
+      context.resolver,
+      transformer,
+      new Map(),
+      { collectCoverage: false, collectCoverageFrom: [], coverageProvider: "v8" },
+      file,
+      globalConfig,
+    );
+    const api = { ...tests, expect: jestExpect };
+    for (const [key, value] of Object.entries(api)) environment.global[key] = value;
+    environment.global.__UF_NATIVE_TEST_API__ = api;
+    runtime.setGlobalsForRuntime(api);
+    runtime.enterTestCode();
+    for (const setup of config.setupFiles) runtime.requireModule(setup);
+    runtime.requireModule(file);
+    return close;
+  } catch (error) {
+    await close();
+    throw error;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/test",
-  "version": "0.0.0-alpha.40",
+  "version": "0.0.0-alpha.41",
   "description": "The test API and worker for `uf test`: describe/it, a full matcher set, and the process uf fans test files out to.",
   "type": "module",
   "license": "MIT",
@@ -18,7 +18,12 @@
     "./in-source": "./in-source.js",
     "./worker": "./worker.js",
     "./browser-worker": "./browser-worker.js",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./app": {
+      "browser": "./app-browser.js",
+      "default": "./app.js"
+    },
+    "./browser": "./browser.js"
   },
   "files": [
     "browser-worker.js",
@@ -27,10 +32,15 @@
     "index.js",
     "internal",
     "worker.js",
+    "app.js",
+    "browser.js",
+    "app-browser.js",
     "!*.test.js"
   ],
   "dependencies": {
-    "@uniflowed/host": "0.0.0-alpha.40"
+    "@uniflowed/host": "0.0.0-alpha.41",
+    "pixelmatch": "^7.1.0",
+    "pngjs": "^7.0.0"
   },
   "peerDependencies": {
     "axe-core": ">=4"
@@ -46,6 +56,7 @@
     "node:module": "./internal/browser/node.js",
     "node:path": "./internal/browser/node.js",
     "node:url": "./internal/browser/node.js",
-    "node:util": "./internal/browser/node.js"
+    "node:util": "./internal/browser/node.js",
+    "./internal/browser/transport.js": "./internal/browser/page-transport.js"
   }
 }

package/worker.js

@@ -218,8 +218,14 @@ async function runImportedFile(
   url: string,
   started: number,
 ): Promise<void> {
+  let closeNative: (() => Promise<void>) | null = null;
   try {
-    await import(`${url}?uf-run=${generation}`);
+    if (process.env.UF_TEST_TARGET === "react-native") {
+      const { loadNativeFile } = await import("./internal/native-host.js");
+      closeNative = await loadNativeFile(request.file);
+    } else {
+      await import(`${url}?uf-run=${generation}`);
+    }
   } catch (thrown) {
     const error = thrown instanceof Error ? thrown : new Error(String(thrown));
     write({
@@ -256,12 +262,18 @@ async function runImportedFile(
     // with forty snapshots would otherwise rewrite its snapshot file forty
     // times, and a crash halfway through would leave a partial one.
     writeChangedSnapshots();
+    await closeNative?.();
     write({
       event: "file",
       status: "completed",
       durationMicros: Math.round((performance.now() - started) * 1000),
     });
   } catch (thrown) {
+    try {
+      await closeNative?.();
+    } catch {
+      // Preserve the original run or teardown failure.
+    }
     const error = thrown instanceof Error ? thrown : new Error(String(thrown));
     write({
       event: "file",