@uniflowed/test 0.0.0-alpha.9 → 0.2.0

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

@@ -0,0 +1,334 @@
+// @flow
+//
+// The process `uf test --browser` fans work out to.
+//
+// `./worker.js` runs a test file. This runs a *browser* that runs a test file,
+// and from `uf`'s side the two are the same thing: a process started the same
+// way, given a request per line on stdin, answering with an event per line on
+// stdout, bounded by the same wall clock and replaced the same way when it
+// stops answering. `crates/uf_test/src/host.rs` does not branch on which of
+// the two it is talking to, and that is the whole design — the browser is
+// another host, not a second runner.
+//
+//   uf ──stdin──▶ this process ──HTTP──▶ a page in a real browser
+//      ◀─stdout──               ◀─HTTP──
+//
+// # Why there is a process in the middle at all
+//
+// A page cannot read a pipe. Somebody has to hold the browser's process
+// handle, serve it modules, and turn what it says into what `uf` reads, and
+// that somebody has to be a JavaScript host because resolving a bare specifier
+// and transforming Flow are already solved there. So the driver is Node, the
+// 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.
+//
+// # Browser control
+//
+// 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
+//
+// Loudly, by name, in three places. The browser is not there — refused in
+// Rust, before a process is started. The browser starts and never asks for
+// work — refused here, with whatever it wrote to stderr, because a browser
+// that will not open a page is not a suite that failed. The browser goes away
+// mid-run — the stream ends, and `uf` reports a host that died, which is the
+// path Node workers already take.
+
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+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 = {|
+  readonly file: string,
+  readonly filter?: string | null,
+  readonly timeoutMs?: number,
+  readonly generation?: number,
+|};
+
+/**
+ * How long a browser is given to open the page before the run is refused.
+ *
+ * Generous against a cold Chromium with a cold profile, which is about seven
+ * seconds on a laptop and much worse in a busy container, and deliberately
+ * *shorter than `uf_test`'s browser file budget* (`BROWSER_FILE_TIMEOUT`, two
+ * minutes).
+ * That order is the whole point: `uf` is already holding a stopwatch on the
+ * first file while this is happening, and whichever of the two fires first is
+ * what the report says. A browser that will not start should be reported as a
+ * browser that will not start, with its own output attached — not as a file
+ * that timed out, which is a sentence about tests that were never reached.
+ */
+const START_TIMEOUT_MS = 110_000;
+
+/**
+ * The switches a headless run needs, and what each is for.
+ *
+ * Kept short on purpose. Every flag here is a decision about the browser the
+ * tests are measured in, and a long list is a long list of ways this page
+ * differs from the application's — which is the difference browser mode exists
+ * to remove.
+ */
+function browserArguments(profile: string, url: string): Array<string> {
+  return [
+    // The modern headless, which is the same renderer as a windowed browser.
+    // The old one was a separate binary with its own layout quirks, and a
+    // layout answer from it would not have been an answer about Chrome.
+    "--headless=new",
+    // What makes the browser die when this process does, and the only reason
+    // this mode names a debugging switch at all.
+    //
+    // `uf` kills a worker that misses its deadline, and a killed process runs
+    // no exit handler — so without this, a timed-out file would leave a browser
+    // running with nobody to stop it, and a suite that leaks one browser per
+    // timeout eventually cannot run. Chrome treats the pipe as its lifeline:
+    // when the file descriptors close, for any reason, it shuts itself down.
+    //
+    // 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
+    // browser process running (measured on Chrome 148).
+    "--remote-debugging-pipe",
+    // A scratch profile per run: no extensions, no saved state, no policy from
+    // the developer's own browser leaking into what the suite measures.
+    `--user-data-dir=${profile}`,
+    // The scratch profile stores no credentials, so keep Chrome off desktop
+    // keyring backends that can hang behind a broken CI DBus session before
+    // the first page request.
+    "--password-store=basic",
+    "--no-first-run",
+    "--no-default-browser-check",
+    // Keep startup deterministic in CI. These cut services Chrome may start
+    // before the first page request: extensions, sync, updater probes, and
+    // background network clients such as GCM. None of them changes layout or
+    // module execution, which is what browser mode measures.
+    "--disable-background-networking",
+    "--disable-client-side-phishing-detection",
+    "--disable-component-update",
+    "--disable-default-apps",
+    "--disable-domain-reliability",
+    "--disable-extensions",
+    "--disable-sync",
+    "--disable-features=AutofillServerCommunication,BackgroundFetch,BackgroundSync,CertificateTransparencyComponentUpdater,DialMediaRouteProvider,MediaRouter,NotificationTriggers,OptimizationHints,PushMessaging,Translate",
+    "--metrics-recording-only",
+    // Nothing here paints, and a GPU process is one more thing to fail in a
+    // container.
+    "--disable-gpu",
+    // `/dev/shm` is 64 MB in most containers, which is where a renderer dies
+    // in CI and nowhere else.
+    "--disable-dev-shm-usage",
+    "--disable-background-timer-throttling",
+    "--disable-renderer-backgrounding",
+    url,
+  ];
+}
+
+/**
+ * Write one event, exactly as `./worker.js` does.
+ *
+ * The raw stream, taken before anything in this process could have replaced
+ * it. Nothing here captures `console`: the driver runs no test code, and the
+ * printing that has to be captured happens in the page.
+ */
+const emit = (line: string) => {
+  process.stdout.write(line);
+};
+
+function write(event: { readonly [string]: mixed }): void {
+  emit(`${JSON.stringify(event)}\n`);
+}
+
+/** Report that the run cannot happen, against the file that asked for it. */
+function refuse(message: string, generation: number): void {
+  write({ event: "file", status: "run-failed", message, generation });
+}
+
+async function main(): Promise<void> {
+  const root = process.env.UF_PROJECT_ROOT ?? process.cwd();
+  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.
+      // `inSourceTests` is the one that would be easy to forget and expensive
+      // to: without it `import.meta.uf.test` compiles to `void 0`, every
+      // in-source block is shaken out, and a browser run of a project that
+      // writes them reports fewer tests than the Node run of the same files —
+      // silently, and with a green summary.
+      const result = await service.transform(id, code, {
+        development: true,
+        sourceMap: true,
+        inSourceTests: inSourceTests(),
+      });
+      if (result == null) return null;
+      // The map is appended rather than served beside the module: a browser
+      // reads `sourceMappingURL` from the end of the file, and a data URL is
+      // one fewer route and one fewer round trip. What it buys is a stack
+      // frame in a failure that names the line the author wrote — the same
+      // thing `--enable-source-maps` buys a Node worker.
+      const map = result.map;
+      if (map == null) return result.code;
+      const encoded = Buffer.from(typeof map === "string" ? map : JSON.stringify(map)).toString(
+        "base64",
+      );
+      return `${result.code}\n//# sourceMappingURL=data:application/json;charset=utf-8;base64,${encoded}\n`;
+    },
+    warn: (message) => {
+      process.stderr.write(`[uf] ${message}\n`);
+    },
+  });
+
+  server.onEvent((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 === "") {
+    // Belt and braces: `uf` refuses before starting this process, so reaching
+    // here means somebody ran the driver by hand.
+    refuse(
+      "`@uniflowed/test/browser-worker.js` was started with no UF_BROWSER. It is not a command to run directly; `uf test --browser` finds a browser and names it here.",
+      0,
+    );
+    await server.close();
+    return;
+  }
+
+  const profile = mkdtempSync(path.join(tmpdir(), "uf-browser-"));
+  // Five descriptors, because `--remote-debugging-pipe` reads 3 and writes 4.
+  // The controller below exchanges null-delimited CDP messages on them.
+  const child = spawn(browser, browserArguments(profile, server.url), {
+    stdio: ["ignore", "pipe", "pipe", "pipe", "pipe"],
+  });
+  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,
+  // and that is when they are shown.
+  let noise = "";
+  const keep = (chunk: mixed) => {
+    if (noise.length < 8 * 1024) noise += String(chunk);
+  };
+  child.stdout?.on("data", keep);
+  child.stderr?.on("data", keep);
+
+  let started = false;
+  const startFailure = await new Promise<string | null>((resolve) => {
+    const deadline = setTimeout(() => {
+      resolve(`the browser did not open the page within ${String(START_TIMEOUT_MS / 1000)}s`);
+    }, START_TIMEOUT_MS);
+    // Polled rather than pushed: the page's first request *is* the signal, and
+    // the server already knows when it arrives. A `Page.loadEventFired` would
+    // be the protocol this mode does not speak.
+    const poll: IntervalID = setInterval(() => {
+      if (!server.connected()) return;
+      clearInterval(poll);
+      clearTimeout(deadline);
+      started = true;
+      resolve(null);
+    }, 25);
+    child.on("exit", (code: mixed) => {
+      if (started) return;
+      clearInterval(poll);
+      clearTimeout(deadline);
+      resolve(`the browser exited (${String(code)}) before opening the page`);
+    });
+    child.on("error", (error: Error) => {
+      clearInterval(poll);
+      clearTimeout(deadline);
+      resolve(`the browser could not be started: ${error.message}`);
+    });
+  });
+
+  const stop = () => {
+    child.kill("SIGKILL");
+    try {
+      rmSync(profile, { recursive: true, force: true });
+    } catch {
+      // A scratch profile that outlives the run is litter in the system
+      // temporary directory, not a reason to fail a suite.
+    }
+  };
+
+  if (startFailure != null) {
+    stop();
+    await server.close();
+    // The first file's request is what `uf` is waiting on, so the refusal is
+    // reported against it — every subsequent file gets the same message from a
+    // fresh driver, which is the same shape as a worker that cannot spawn.
+    const trailer = noise.trim() === "" ? "" : `\n${noise.trim()}`;
+    refuse(`\`${browser}\`: ${startFailure}.${trailer}`, 0);
+    // The stream ends here, which `uf` reads as a host that died. That is
+    // exactly what happened, and it is what makes `uf` start a fresh driver
+    // for the next file rather than send it to a browser that is not there.
+    return;
+  }
+
+  createInterface({ input: process.stdin }).on("line", (line) => {
+    if (line.trim() === "") return;
+    let request: Request;
+    try {
+      request = JSON.parse(line);
+    } catch (error) {
+      write({
+        event: "file",
+        status: "run-failed",
+        message: `malformed request: ${String(error)}`,
+        generation: 0,
+      });
+      return;
+    }
+    // Handed straight over. `uf` sends one file at a time and waits for its
+    // `file` event, and the page runs one file per load, so there is no queue
+    // to keep here — the two ends already agree on the shape.
+    server.offer({
+      file: request.file,
+      filter: request.filter ?? null,
+      timeoutMs: request.timeoutMs ?? 5000,
+      generation: request.generation ?? 0,
+    });
+  });
+
+  process.stdin.on("close", () => {
+    void server.close().then(() => {
+      stop();
+      service.close();
+      process.exit(0);
+    });
+  });
+}
+
+// A driver that throws has no file to blame, so it says so against the request
+// `uf` is waiting on and lets the stream end. Silence here would be a run that
+// waits for a deadline.
+main().catch((error: mixed) => {
+  const reason = error instanceof Error ? error.message : String(error);
+  refuse(`\`uf test --browser\` could not start: ${reason}`, 0);
+  process.exit(1);
+});

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,
+  };
+}