npm - @reporters/web - Versions diffs - 1.1.0 - Mend

@reporters/web 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,62 @@
+![tests](https://github.com/MoLow/reporters/actions/workflows/test.yaml/badge.svg?branch=main) [![codecov](https://codecov.io/gh/MoLow/reporters/branch/main/graph/badge.svg?token=0LFVC8SCQV)](https://codecov.io/gh/MoLow/reporters)
+# Web Reporter
+Read your `node:test` run in the browser — a rich, interactive tree with live
+updates, search, and inline failure diffs.
+`@reporters/web` streams the run as an **NDJSON** event log, and ships a React
+**viewer** that renders it: pass/fail counts and progress at a glance, the full
+suite tree with per-test durations, ANSI-colored error output, and failing
+tests auto-expanded with their assertion diff and stack trace.
+[![the @reporters/web viewer showing a run with an expanded failure](https://raw.githubusercontent.com/MoLow/reporters/5393ed7b104f42d90bb930ad89854d8fdff6785b/packages/web/assets/viewer.png)](https://molow.github.io/reporters/?src=https://raw.githubusercontent.com/MoLow/reporters/5393ed7b104f42d90bb930ad89854d8fdff6785b/packages/web/assets/demo-run.ndjson)
+**[▶ Open the live demo](https://molow.github.io/reporters/?src=https://raw.githubusercontent.com/MoLow/reporters/5393ed7b104f42d90bb930ad89854d8fdff6785b/packages/web/assets/demo-run.ndjson)** — the screenshot above, in the hosted viewer.
+## Usage
+```bash
+node --test-reporter=@reporters/web --test-reporter-destination=run.ndjson --test
+```
+On a dev machine that command does everything: it writes the NDJSON log **and**
+opens a live-updating browser view of the run.
+## Viewing a run
+The NDJSON is rendered by the tree viewer, reached three ways:
+- **Standalone** — on a dev machine, when given a file destination, the reporter
+  also starts a local server for the viewer and opens your browser to a
+  live-updating view (it polls the growing NDJSON over HTTP Range — no
+  `file://`/CORS limits). It never opens in CI. Force it on/off with the `open`
+  option (2nd reporter arg) or `REPORTERS_OPEN=1|0`.
+- **Through [`@reporters/mux`](https://github.com/MoLow/reporters/tree/main/packages/mux)**
+  with the `httpServer()` sink — the reporter stays a pure emitter and the sink
+  serves the viewer + growing NDJSON over HTTP Range, opening your browser:
+  ```js
+  // mux.config.js
+  import { httpServer } from '@reporters/web/sink';
+  export default {
+    // pass `options: { open: false }` on the route if it shouldn't open a browser
+    local: [{ reporter: '@reporters/web', sink: httpServer() }],
+  };
+  ```
+- **Hosted viewer** — host the NDJSON anywhere (a gist, an S3 bucket, a CI
+  artifact, a raw GitHub URL) and open:
+  ```
+  https://molow.github.io/reporters/?src=<url-to-your-run.ndjson>
+  ```
+  The viewer polls the file as it grows using HTTP Range, so this works for
+  runs that are still in progress — share the link and teammates watch the same
+  run live.
+Built on the shared [`@reporters/tree-core`](https://github.com/MoLow/reporters/tree/main/packages/tree-core)
+model (also used by [`@reporters/live`](https://github.com/MoLow/reporters/tree/main/packages/live)) —
+the same run state, rendered in the browser instead of the terminal.

package/dist/chunk-MZ7XNO2N.js ADDED Viewed

@@ -0,0 +1,60 @@
+// src/server.ts
+import { createServer } from "http";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+function viewerPage() {
+  try {
+    return readFileSync(fileURLToPath(new URL("./viewer/index.html", import.meta.url)), "utf8");
+  } catch {
+    return '<!doctype html><meta charset="utf-8"><p>viewer bundle missing \u2014 run the package build</p>';
+  }
+}
+function startViewerServer(host = "127.0.0.1") {
+  const page = viewerPage();
+  let buffer = Buffer.alloc(0);
+  return new Promise((resolve) => {
+    const server = createServer((req, res) => {
+      const path = req.url.split("?")[0];
+      if (path === "/run.ndjson") {
+        const range = /^bytes=(\d+)-/.exec(req.headers.range ?? "");
+        if (range) {
+          const startByte = Number(range[1]);
+          if (startByte >= buffer.length) {
+            res.writeHead(416).end();
+            return;
+          }
+          res.writeHead(206, {
+            "content-type": "application/x-ndjson",
+            "accept-ranges": "bytes",
+            "content-range": `bytes ${startByte}-${buffer.length - 1}/${buffer.length}`
+          });
+          res.end(buffer.subarray(startByte));
+          return;
+        }
+        res.writeHead(200, { "content-type": "application/x-ndjson", "accept-ranges": "bytes" });
+        res.end(buffer);
+        return;
+      }
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      res.end(page);
+    });
+    server.listen(0, host, () => {
+      const { port } = server.address();
+      resolve({
+        url: `http://${host}:${port}/?src=/run.ndjson`,
+        push(chunk) {
+          buffer = Buffer.concat([buffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
+        },
+        close() {
+          return new Promise((res) => {
+            server.close(() => res());
+          });
+        }
+      });
+    });
+  });
+}
+export {
+  startViewerServer
+};

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,51 @@
+type DiagnosticLevel = 'info' | 'warn' | 'error';
+/** The fields of a `node:test` reporter event that the store consumes. */
+interface TestEventData {
+    name?: string;
+    nesting?: number;
+    file?: string;
+    testId?: number;
+    parentId?: number;
+    line?: number;
+    column?: number;
+    tags?: string[];
+    todo?: boolean | string;
+    skip?: boolean | string;
+    message?: string;
+    level?: DiagnosticLevel;
+    count?: number;
+    type?: 'suite' | 'test';
+    details?: {
+        duration_ms?: number;
+        error?: unknown;
+        type?: string;
+        passed?: boolean;
+    };
+    counts?: Record<string, number>;
+    duration_ms?: number;
+    success?: boolean;
+}
+interface TestEvent {
+    type: string;
+    data: TestEventData;
+}
+interface WebOptions {
+    /** Serve a live browser view of the run and open it. Defaults to detecting an
+     *  interactive terminal (a TTY, not CI); `REPORTERS_OPEN=1|0` also overrides. */
+    open?: boolean;
+}
+/**
+ * A `node:test` reporter that emits the run as a raw NDJSON event log — one
+ * JSON-safe wire line per event — to whatever `--test-reporter-destination`
+ * points at.
+ *
+ * Run standalone on a dev machine it also serves a live browser view and opens
+ * it, the same way it behaves through `@reporters/mux`'s `httpServer()` sink.
+ * Control this with the `open` option or `REPORTERS_OPEN=1|0`; it never opens
+ * in CI by default. Through mux the reporter is a pure emitter and the sink owns
+ * viewing.
+ */
+declare function web(source: AsyncIterable<TestEvent>, options?: WebOptions): AsyncGenerator<string>;
+export { type WebOptions, web as default };

package/dist/index.js ADDED Viewed

@@ -0,0 +1,121 @@
+import {
+  startViewerServer
+} from "./chunk-MZ7XNO2N.js";
+// ../tree-core/src/wire.ts
+function flattenError(raw) {
+  if (raw == null) return void 0;
+  const err = raw;
+  return {
+    message: err.message ?? String(err),
+    stack: err.stack,
+    name: err.name,
+    cause: err.cause instanceof Error ? flattenError(err.cause) : err.cause
+  };
+}
+function toWireEvent(event) {
+  const d = event.data ?? {};
+  const data = {};
+  if (d.name != null) data.name = d.name;
+  if (d.nesting != null) data.nesting = d.nesting;
+  if (d.file != null) data.file = d.file;
+  if (d.testId != null) data.testId = d.testId;
+  if (d.parentId != null) data.parentId = d.parentId;
+  if (d.line != null) data.line = d.line;
+  if (d.column != null) data.column = d.column;
+  if (d.tags != null) data.tags = d.tags;
+  if (d.todo != null) data.todo = d.todo;
+  if (d.skip != null) data.skip = d.skip;
+  if (d.message != null) data.message = d.message;
+  if (d.level != null) data.level = d.level;
+  if (d.count != null) data.count = d.count;
+  if (d.type != null) data.type = d.type;
+  if (d.counts != null) data.counts = d.counts;
+  if (d.duration_ms != null) data.duration_ms = d.duration_ms;
+  if (d.success != null) data.success = d.success;
+  if (d.details != null) {
+    data.details = {
+      duration_ms: d.details.duration_ms,
+      type: d.details.type,
+      passed: d.details.passed,
+      error: flattenError(d.details.error)
+    };
+  }
+  return { type: event.type, data };
+}
+function serializeWireLine(event) {
+  return `${JSON.stringify(toWireEvent(event))}
+`;
+}
+// ../tree-core/src/format.ts
+var SECOND = 1e3;
+var MINUTE = 60 * SECOND;
+var HOUR = 60 * MINUTE;
+// src/open.ts
+import { spawn } from "child_process";
+function soleFileDestination(execArgv = process.execArgv) {
+  const flag = "--test-reporter-destination";
+  const dests = [];
+  for (let i = 0; i < execArgv.length; i += 1) {
+    if (execArgv[i] === flag && execArgv[i + 1]) dests.push(execArgv[i + 1]);
+    else if (execArgv[i].startsWith(`${flag}=`)) dests.push(execArgv[i].slice(flag.length + 1));
+  }
+  const files = dests.filter((d) => d && d !== "stdout" && d !== "stderr");
+  return files.length === 1 ? files[0] : void 0;
+}
+function isCI(env = process.env) {
+  return Boolean(env.CI || env.CONTINUOUS_INTEGRATION || env.GITHUB_ACTIONS || env.GITLAB_CI || env.BUILDKITE);
+}
+function shouldOpen(open, env = process.env, isTTY = Boolean(process.stdout.isTTY)) {
+  if (open !== void 0) return open;
+  const flag = env.REPORTERS_OPEN;
+  if (flag === "1" || flag === "true") return true;
+  if (flag === "0" || flag === "false") return false;
+  return isTTY && !isCI(env);
+}
+function openCommand(url, platform = process.platform) {
+  if (platform === "darwin") return ["open", [url]];
+  if (platform === "win32") return ["cmd", ["/c", "start", "", url]];
+  return ["xdg-open", [url]];
+}
+function openInBrowser(url) {
+  const [cmd, args] = openCommand(url);
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+var internals = { openInBrowser };
+// src/index.ts
+function hint(message) {
+  process.stderr.write(`${message}
+`);
+}
+async function* web(source, options = {}) {
+  const dest = soleFileDestination();
+  const serve = shouldOpen(options.open);
+  let server;
+  if (serve) {
+    server = await startViewerServer();
+    internals.openInBrowser(server.url);
+    hint(`
+@reporters/web: live report at ${server.url}`);
+  }
+  for await (const event of source) {
+    const line = serializeWireLine(event);
+    server?.push(line);
+    if (dest || !server) yield line;
+  }
+  if (!server) return;
+  if (process.stdin.isTTY) return;
+  await server.close();
+}
+export {
+  web as default
+};

package/dist/sink.d.ts ADDED Viewed

@@ -0,0 +1,24 @@
+interface Sink {
+    /** Start servers/streams; resolves once ready to receive writes. */
+    start?(): Promise<void>;
+    write(chunk: string | Buffer): void | Promise<void>;
+    /** Periodic durability hook (e.g. a future s3 re-PUT). */
+    flush?(): Promise<void>;
+    /** The run ended; release resources. */
+    close(): Promise<void>;
+    /** How a human views what was written, if anything. */
+    viewerUrl?(): string | undefined;
+}
+interface HttpServerOptions {
+    host?: string;
+}
+/**
+ * A sink that serves the run locally: the viewer page at `/` and the growing
+ * NDJSON at `/run.ndjson` (HTTP Range aware, so the viewer polls appended bytes
+ * — no `file://`/CORS limits). Stays alive after the run while attached to an
+ * interactive terminal; otherwise shuts down so the process can exit.
+ */
+declare function httpServer(opts?: HttpServerOptions): Sink;
+export { type HttpServerOptions, httpServer };

package/dist/sink.js ADDED Viewed

@@ -0,0 +1,26 @@
+import {
+  startViewerServer
+} from "./chunk-MZ7XNO2N.js";
+// src/sink.ts
+function httpServer(opts = {}) {
+  let server;
+  return {
+    async start() {
+      server = await startViewerServer(opts.host);
+    },
+    write(chunk) {
+      server?.push(chunk);
+    },
+    viewerUrl() {
+      return server?.url;
+    },
+    async close() {
+      if (process.stdin.isTTY) return;
+      await server?.close();
+    }
+  };
+}
+export {
+  httpServer
+};