@uniflowed/test 0.0.0-alpha.9 → 0.1.0

package/internal/browser/node.js

@@ -0,0 +1,375 @@
+// @flow
+//
+// The `node:` builtins `@uniflowed/test` reaches for, as a browser can have
+// them.
+//
+// # Why a package the browser never runs needs a browser build
+//
+// A module with an in-source test block imports `@uniflowed/test` at its top
+// level, and that block is compiled away by `uf build` — `import.meta.uf.test`
+// becomes `void 0`, the bundler drops the branch, and the import goes with it
+// because the package declares `sideEffects: false`. But a bundler *resolves*
+// a graph before it shakes it, so the six builtins this package's edges import
+// were resolved on the way to being discarded: `node:fs` and `node:path` for
+// snapshot files, `node:module` and `node:url` for module mocking,
+// `node:async_hooks` and `node:util` for output capture. Each one printed
+//
+//     Module "node:fs" has been externalized for browser compatibility
+//
+// so a project with one three-line in-source test got six warnings about
+// modules `uf build` was in the middle of removing.
+//
+// `package.json`'s `browser` field maps all six here. Node ignores that field
+// and every bundler honours it, so nothing about running a test on a host
+// changes and the build is quiet.
+//
+// One file rather than six of four lines, because the question a reader has is
+// "what does a browser not have", and that is answered better in one place
+// than in six.
+//
+// # Why the shims work rather than only resolve
+//
+// Nothing here is reached by the build that made it necessary: the module that
+// imports it is removed. What makes the implementations below worth writing is
+// the case where the package *is* evaluated in a browser — a runner that ran a
+// test file in a real page, which `docs/roadmap.md` still lists as not done, or
+// an application that genuinely imports `@uniflowed/test` into client code.
+// A file that exists only to be resolved would be a file that fails the moment
+// somebody's build stops shaking it out, and that failure would arrive as a
+// missing export rather than as a sentence.
+//
+// # Two kinds of shim, and the difference is the point
+//
+// Some of these are **implementations**: `format`, `inspect`, `pathToFileURL`
+// and the path helpers do in a browser what they do in Node, closely enough
+// for the one caller each has. `AsyncLocalStorage` is an implementation with a
+// named limitation.
+//
+// The rest are **refusals**: the filesystem is not something a page has, and
+// `createRequire` cannot invent a synchronous module loader. Each one throws a
+// sentence naming what is not available and what to do instead. A shim that
+// answered plausibly — an `existsSync` that said `false`, say — would be worse
+// than no browser mode at all: `toMatchSnapshot` would read "no snapshot yet",
+// record one it could not write, and pass. That is the runner lying, which is
+// the failure `uf test` exists not to have.
+//
+// Each refusal names what is not available and what to do instead, so a
+// boundary is a sentence rather than a surprise in a stack trace.
+
+/** How a refusal is worded, so all of them read the same way. */
+function unavailable(what: string, instead: string): Error {
+  return new Error(
+    `${what} is not available in \`uf test --browser\`: a page has no ${what}. ${instead}`,
+  );
+}
+
+// ---------------------------------------------------------------------- //
+// node:fs — refused
+// ---------------------------------------------------------------------- //
+
+/** Snapshot files live on a disk the page cannot see. */
+export function existsSync(_path: mixed): empty {
+  throw unavailable(
+    "the filesystem",
+    "Snapshots (`toMatchSnapshot`) are written by the host that runs the file; assert with `toMatchInlineSnapshot`, which needs no file, or run the file on Node.",
+  );
+}
+
+/** @see existsSync */
+export function readFileSync(_path: mixed, _encoding?: mixed): empty {
+  return existsSync(_path);
+}
+
+/** @see existsSync */
+export function writeFileSync(_path: mixed, _contents: mixed): empty {
+  return existsSync(_path);
+}
+
+/** @see existsSync */
+export function mkdirSync(_path: mixed, _options?: mixed): empty {
+  return existsSync(_path);
+}
+
+// ---------------------------------------------------------------------- //
+// node:module — refused, with one door left open
+// ---------------------------------------------------------------------- //
+
+/**
+ * Modules the page has already imported, by the specifier they answer to.
+ *
+ * The one thing `createRequire` is used for that a browser *can* do. It is
+ * `@uniflowed/react-testing`'s `render`, which loads `react-dom/client` through
+ * `createRequire` rather than an import because `render` is synchronous and an
+ * import is not — a decision that is right on Node and impossible here.
+ *
+ * So the page's entry module imports `react-dom/client` itself, before any
+ * test file runs, and puts it here. `render` then finds it synchronously, and
+ * the import that made that possible happened at a moment when being
+ * asynchronous cost nothing.
+ */
+const provided: Map<string, mixed> = new Map();
+
+/**
+ * Register a module the page has already imported.
+ *
+ * Called by whatever brought this package into a page, never by a test.
+ */
+export function provideModule(specifier: string, module: mixed): void {
+  provided.set(specifier, module);
+}
+
+/**
+ * A `require` that answers for what the page brought with it and refuses the
+ * rest.
+ *
+ * Refusing loudly rather than returning `undefined`: a caller that gets
+ * `undefined` back fails later, somewhere else, with a message about a
+ * property of `undefined`.
+ */
+export function createRequire(_from: mixed): (specifier: string) => mixed {
+  return (specifier: string) => {
+    if (provided.has(specifier)) return provided.get(specifier);
+    throw unavailable(
+      `a synchronous \`require("${specifier}")\``,
+      "Import it from the test file instead; a browser resolves modules asynchronously and cannot be asked to do it in the middle of a call.",
+    );
+  };
+}
+
+// ---------------------------------------------------------------------- //
+// node:url — implemented
+// ---------------------------------------------------------------------- //
+
+/** A path as the `file:` URL Node would produce. */
+export function pathToFileURL(filePath: string): URL {
+  const withSlashes = filePath.replace(/\\/g, "/");
+  const absolute = withSlashes.startsWith("/") ? withSlashes : `/${withSlashes}`;
+  return new URL(`file://${absolute.split("/").map(encodeURIComponent).join("/")}`);
+}
+
+/** The path inside a `file:` URL. */
+export function fileURLToPath(url: string | URL): string {
+  const href = typeof url === "string" ? url : url.href;
+  if (!href.startsWith("file://")) {
+    throw new TypeError(`not a file URL: ${href}`);
+  }
+  return decodeURIComponent(href.slice("file://".length));
+}
+
+// ---------------------------------------------------------------------- //
+// node:util — implemented
+// ---------------------------------------------------------------------- //
+
+/**
+ * `util.inspect`, to the depth a test's `console.log` needs.
+ *
+ * Not Node's algorithm — no getters, no circular references marked, no colour.
+ * What it has to be is *stable* and *readable*, because its output is what a
+ * failing test's printing looks like in the terminal, and `JSON.stringify`
+ * with a replacer that names functions and symbols is both.
+ */
+export function inspect(value: mixed): string {
+  if (typeof value === "string") return `'${value}'`;
+  return renderValue(value, new Set());
+}
+
+function renderValue(value: mixed, seen: Set<mixed>): string {
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
+  if (typeof value === "string") return `'${value}'`;
+  if (typeof value === "bigint") return `${String(value)}n`;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (typeof value === "symbol") return String(value);
+  if (typeof value === "function") {
+    const name = (value as $FlowFixMe).name;
+    return name === "" ? "[Function (anonymous)]" : `[Function: ${String(name)}]`;
+  }
+  if (value instanceof Error) return `${value.name}: ${value.message}`;
+  if (typeof value !== "object") return String(value);
+  if (seen.has(value)) return "[Circular]";
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return `[ ${value.map((item: mixed) => renderValue(item, seen)).join(", ")} ]`;
+    }
+    const entries = Object.entries(value).map(
+      ([key, item]) => `${key}: ${renderValue(item, seen)}`,
+    );
+    return entries.length === 0 ? "{}" : `{ ${entries.join(", ")} }`;
+  } finally {
+    seen.delete(value);
+  }
+}
+
+/**
+ * `util.format`, with the `%s`/`%d`/`%i`/`%j`/`%o`/`%O`/`%%` substitutions
+ * `console.log` uses.
+ *
+ * Everything left over is appended, space separated, exactly as Node does —
+ * which is the behaviour `console.log("a", 1, { b: 2 })` depends on.
+ */
+export function format(first: mixed, ...rest: $ReadOnlyArray<mixed>): string {
+  const args = [...rest];
+  let out = "";
+  if (typeof first === "string") {
+    let at = 0;
+    while (at < first.length) {
+      const ch = first[at];
+      if (ch !== "%" || at + 1 >= first.length) {
+        out += ch;
+        at += 1;
+        continue;
+      }
+      const kind = first[at + 1];
+      if (kind === "%") {
+        out += "%";
+        at += 2;
+        continue;
+      }
+      if (!"sdifjoO".includes(kind) || args.length === 0) {
+        out += ch;
+        at += 1;
+        continue;
+      }
+      const value = args.shift();
+      if (kind === "s") out += typeof value === "string" ? value : renderValue(value, new Set());
+      else if (kind === "d" || kind === "f") out += String(Number(value));
+      else if (kind === "i") out += String(Math.trunc(Number(value)));
+      else if (kind === "j") out += safeJson(value);
+      else out += renderValue(value, new Set());
+      at += 2;
+    }
+  } else {
+    out = renderValue(first, new Set());
+  }
+  for (const value of args) {
+    out += ` ${typeof value === "string" ? value : renderValue(value, new Set())}`;
+  }
+  return out;
+}
+
+function safeJson(value: mixed): string {
+  try {
+    return JSON.stringify(value) ?? "undefined";
+  } catch {
+    return "[Circular]";
+  }
+}
+
+// ---------------------------------------------------------------------- //
+// node:async_hooks — implemented, with a limitation that is written down
+// ---------------------------------------------------------------------- //
+
+/**
+ * A single-value stand-in for Node's asynchronous storage.
+ *
+ * The real one follows a value through every continuation of the work that
+ * entered it; this one holds whichever `run` is on the stack. A browser has no
+ * asynchronous context tracking to build the real thing on — the platform
+ * proposal for it is not shipped anywhere — and the alternative to an
+ * approximation is that `@uniflowed/test`'s output capture cannot be imported
+ * at all.
+ *
+ * What it costs is bounded by what the store is used for here.
+ * `internal/output.js` reads it to attribute a `console.log` to the case that
+ * printed it, and cases run one at a time, so the answer is right for
+ * everything a case prints while it is running. It is wrong for a `setTimeout`
+ * a finished case left behind: the print is still reported, attributed to the
+ * file rather than to the case. On Node that same straggler is attributed to
+ * its case; here it is attributed one level up.
+ *
+ * That is the whole of the difference, and it is a difference in a label on a
+ * line of output — not in what passes.
+ */
+export class AsyncLocalStorage<T> {
+  #store: T | void = undefined;
+
+  /** Run `body` with `value` readable from `getStore`. */
+  run<R>(value: T, body: () => R): R {
+    const previous = this.#store;
+    this.#store = value;
+    try {
+      return body();
+    } finally {
+      this.#store = previous;
+    }
+  }
+
+  /** The value of the nearest enclosing `run`, or `undefined`. */
+  getStore(): T | void {
+    return this.#store;
+  }
+
+  /** Run `body` with no value readable. */
+  exit<R>(body: () => R): R {
+    const previous = this.#store;
+    this.#store = undefined;
+    try {
+      return body();
+    } finally {
+      this.#store = previous;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------- //
+// node:path — implemented, posix only
+// ---------------------------------------------------------------------- //
+
+/**
+ * The path operations `internal/snapshot.js` performs on a snapshot path.
+ *
+ * Posix only, which is not a limitation here: every path a page sees came from
+ * a URL, and a URL's separator is `/` on every platform.
+ */
+export const path: {
+  readonly join: (...parts: $ReadOnlyArray<string>) => string,
+  readonly dirname: (of: string) => string,
+  readonly basename: (of: string, extension?: string) => string,
+  readonly extname: (of: string) => string,
+  readonly resolve: (...parts: $ReadOnlyArray<string>) => string,
+  readonly sep: string,
+} = {
+  sep: "/",
+  join: (...parts) => normalize(parts.filter((part) => part !== "").join("/")),
+  dirname: (of) => {
+    const at = of.lastIndexOf("/");
+    if (at === -1) return ".";
+    return at === 0 ? "/" : of.slice(0, at);
+  },
+  basename: (of, extension) => {
+    const name = of.slice(of.lastIndexOf("/") + 1);
+    return extension != null && name.endsWith(extension)
+      ? name.slice(0, name.length - extension.length)
+      : name;
+  },
+  extname: (of) => {
+    const name = of.slice(of.lastIndexOf("/") + 1);
+    const at = name.lastIndexOf(".");
+    return at <= 0 ? "" : name.slice(at);
+  },
+  resolve: (...parts) => {
+    let out = "";
+    for (const part of parts) {
+      if (part.startsWith("/")) out = part;
+      else if (out === "") out = part;
+      else out = `${out}/${part}`;
+    }
+    return normalize(out.startsWith("/") ? out : `/${out}`);
+  },
+};
+
+/** `a//b/./c/../d` as `a/b/d`, keeping a leading slash. */
+function normalize(input: string): string {
+  const absolute = input.startsWith("/");
+  const out: Array<string> = [];
+  for (const part of input.split("/")) {
+    if (part === "" || part === ".") continue;
+    if (part === ".." && out.length > 0 && out[out.length - 1] !== "..") out.pop();
+    else out.push(part);
+  }
+  const joined = out.join("/");
+  return absolute ? `/${joined}` : joined === "" ? "." : joined;
+}
+
+export default path;

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/page.js

@@ -0,0 +1,258 @@
+// @flow
+//
+// Internal to `@uniflowed/test`: the worker, as it exists inside a page.
+//
+// `../../worker.js` and this module are the same program written for two
+// different hosts, and the half that matters is the same code in both:
+// `internal/run.js` walks the tree, `internal/registry.js` holds it,
+// `internal/expect.js` decides what passed. What differs is only how a file
+// arrives and how a result leaves.
+//
+//   worker.js                      page.js
+//   ─────────────────────────────  ──────────────────────────────────
+//   a request per line on stdin    a long-polled GET /uf-test/next
+//   an event per line on stdout    a POST /uf-test/events
+//   one process, many files        one page load, one file
+//   `restoreSharedState()`         a reload
+//
+// The last row is the one worth reading twice. A Node worker serves many files
+// out of one process, so everything two files could share has to be put back
+// between them by hand — the registry, the clock, the module stand-ins, the
+// document — and `internal/isolation.js` is that list, three issues long. A
+// page reloads instead. The realm is new, the document is new, the module
+// registry is new, and a `setInterval` the previous file abandoned is not
+// merely unstamped, it is gone. Browser mode gets stronger isolation than
+// Node mode for free, and it is the reload that buys it.
+//
+// # What this file does not do
+//
+// Snapshots. `toMatchSnapshot` writes a file, a page has no filesystem, and
+// `./node.js` refuses it in a sentence rather than answering "no snapshot yet"
+// and passing. `toMatchInlineSnapshot` needs no file and works here.
+//
+// Module mocking. `uft.mock` intercepts resolution, which on Node is
+// `node:module`'s synchronous hooks and in a page is nothing at all. Same
+// refusal, same reason.
+
+import * as output from "../output.js";
+import { run } from "../run.js";
+import { installInSourceTests } from "../../in-source.js";
+
+/** One file, as the server hands it over. */
+type PageRequest = {
+  readonly file?: string,
+  readonly filter?: string | null,
+  readonly timeoutMs?: number,
+  readonly generation?: number,
+  readonly done?: boolean,
+  ...
+};
+
+/** The generation every event written from this page load carries. */
+let serving = 0;
+
+/**
+ * Events waiting to be posted, and the post that will carry them.
+ *
+ * Batched rather than one request per event, and still streamed rather than
+ * held to the end: a `POST` is in flight or it is not, and everything that
+ * accumulates while one is in flight goes in the next. So `uf test` draws
+ * progress and `--bail` stops a long file early, without a request per
+ * assertion — a file with four hundred cases would otherwise spend more time
+ * in the loopback than in the tests.
+ */
+const queue: Array<{ readonly [string]: mixed }> = [];
+let flushing: Promise<void> | null = null;
+
+function write(event: { readonly [string]: mixed }): void {
+  queue.push({ ...event, generation: serving });
+  flush();
+}
+
+function flush(): Promise<void> {
+  const already = flushing;
+  if (already != null) return already;
+  if (queue.length === 0) return Promise.resolve();
+  const batch = queue.splice(0, queue.length);
+  const sent = fetch("/uf-test/events", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(batch),
+  })
+    .catch(() => {
+      // The run is over, or `uf` killed the driver on a deadline. Either way
+      // there is nobody to tell, and throwing here would replace a report with
+      // an unhandled rejection.
+    })
+    .then(() => {
+      flushing = null;
+      if (queue.length > 0) return flush();
+      return undefined;
+    });
+  flushing = sent;
+  return sent;
+}
+
+/**
+ * Take over `console`, so a test's printing is an event rather than a line in
+ * a console nobody is reading.
+ *
+ * The same `internal/output.js` the Node worker installs. It has no
+ * `process.stdout` to take here and does not need one — the protocol's channel
+ * is a separate HTTP request, not a shared stream — which is the one thing
+ * that module had to learn about a page.
+ */
+output.install((chunk) => {
+  write({ event: "output", stream: chunk.stream, test: chunk.test, text: chunk.text });
+});
+
+/** Run one file and report it, whatever happens to it. */
+async function runFile(request: PageRequest): Promise<void> {
+  const file = request.file;
+  if (typeof file !== "string") {
+    write({ event: "file", status: "run-failed", message: "a request with no file" });
+    return;
+  }
+  const started = performance.now();
+  const url = new URL(`/@fs${file.split("/").map(encodeURIComponent).join("/")}`, location.href)
+    .href;
+  output.startFile();
+  const uninstall = installInSourceTests(url);
+  try {
+    try {
+      await import(url);
+    } catch (thrown) {
+      const error = asError(thrown);
+      write({
+        event: "file",
+        status: "load-failed",
+        message: `${error.name}: ${error.message}`,
+        stack: error.stack ?? null,
+        durationMicros: micros(started),
+      });
+      return;
+    }
+    await run(
+      {
+        filter: request.filter ?? null,
+        timeoutMs: request.timeoutMs,
+        file,
+      },
+      (result) => {
+        write({
+          event: "test",
+          ...result.outcome,
+          name: result.name,
+          line: result.line,
+          column: result.column,
+          durationMicros: result.durationMicros,
+        });
+      },
+    );
+    write({ event: "file", status: "completed", durationMicros: micros(started) });
+  } catch (thrown) {
+    const error = asError(thrown);
+    write({
+      event: "file",
+      status: "run-failed",
+      message: `${error.name}: ${error.message}`,
+      stack: error.stack ?? null,
+      durationMicros: micros(started),
+    });
+  } finally {
+    uninstall();
+  }
+}
+
+function asError(thrown: mixed): Error {
+  return thrown instanceof Error ? thrown : new Error(String(thrown));
+}
+
+function micros(started: number): number {
+  return Math.round((performance.now() - started) * 1000);
+}
+
+/**
+ * The page's global object, as somewhere to hang a listener.
+ *
+ * `globalThis` is a namespace to the checker rather than an object, so
+ * `globalThis.addEventListener` is not an expression that can be written. The
+ * same one-line trust boundary `internal/output.js` draws around `console`,
+ * for the same reason and with the same amount of type in it.
+ */
+function page(): $FlowFixMe {
+  return globalThis;
+}
+
+/**
+ * Ask for a file, run it, and hand the page back for the next one.
+ *
+ * The reload is the isolation, so it is unconditional: a page that ran a file
+ * does not run a second one, whatever the first one left behind. `location`
+ * rather than a fresh `import` with a busted cache, because the cache is the
+ * smallest of the things two files would otherwise share.
+ */
+async function serve(): Promise<void> {
+  let request: PageRequest;
+  try {
+    request = await (await fetch("/uf-test/next")).json();
+  } catch {
+    // The driver has gone. Nothing to report it to.
+    return;
+  }
+  if (request.done === true) return;
+  serving = typeof request.generation === "number" ? request.generation : 0;
+  await runFile(request);
+  await flush();
+  location.reload();
+}
+
+/**
+ * An unhandled rejection ends the file, exactly as it does on a Node worker.
+ *
+ * A promise nobody awaited is the one failure a runner cannot see from inside
+ * `run.js`: the case has already been reported as passed by the time the
+ * rejection surfaces. Reporting it as a file failure is what keeps the run
+ * honest, and it is the same decision `worker.js` makes at the bottom of the
+ * file for the same reason.
+ *
+ * Then the page is *not* reloaded, so the run's own deadline is what ends this
+ * file. `uf` is holding a wall clock the page cannot argue with; a page that
+ * reloaded itself here would race that clock and could report the next file's
+ * events against this one's generation.
+ */
+page().addEventListener("unhandledrejection", (event: mixed) => {
+  const reason = event != null && typeof event === "object" ? event.reason : undefined;
+  const error = asError(reason);
+  write({
+    event: "file",
+    status: "run-failed",
+    message: `unhandled rejection: ${error.message}`,
+    stack: error.stack ?? null,
+  });
+  void flush();
+});
+
+/**
+ * A window error ends the file too.
+ *
+ * A page has one more way to fail than a process does: a script that throws
+ * during evaluation of something the test did not `await` — an image handler,
+ * a `requestAnimationFrame` callback, a listener a component attached — is
+ * reported to `window` and to nothing else. On Node the equivalent takes the
+ * process down and `uf` reports a worker that died; here nothing at all would
+ * happen, and the file would sit until its deadline.
+ */
+page().addEventListener("error", (event: mixed) => {
+  const thrown = event != null && typeof event === "object" ? event.error : undefined;
+  const error = asError(thrown ?? "an error with no value");
+  write({
+    event: "file",
+    status: "run-failed",
+    message: `${error.name}: ${error.message}`,
+    stack: error.stack ?? null,
+  });
+  void flush();
+});
+
+void serve();