@cevek/screentest 0.3.1 → 0.3.2

package/README.md

@@ -25,9 +25,12 @@ npx screentest init
 npx screentest serve
 
 # 3. Run.
-APP_URL=http://localhost:5050 npx screentest test
+APP_URL=http://localhost:5050 npx vitest run --config vitest.screentest.config.ts
 ```
 
+> Add `"screentest": "vitest run --config vitest.screentest.config.ts"`
+> to your package.json scripts so you can just `npm run screentest`.
+
 The daemon lives outside your project — one container serves every
 project on your machine. It listens on `ws://localhost:5180`, holds
 ~300MB RAM at idle, and stays up across reboots-of-your-app until you
@@ -46,9 +49,9 @@ container, over a WebSocket. Editing tests never needs an image rebuild.
 
 Existing files are not overwritten — re-run `init` safely.
 
-`screentest test` always runs vitest with
-`--config vitest.screentest.config.ts`, so unit tests via plain `vitest run`
-and screenshot tests via `screentest test` stay completely separate.
+Pass `--config vitest.screentest.config.ts` to keep the screenshot run
+separate from your normal `vitest run`. The screenshot config wires up
+our globalSetup; plain `vitest run` skips it entirely — no Firefox launch.
 
 ## Commands
 
@@ -59,12 +62,13 @@ screentest status   # is it running?
 ```
 
 ```bash
-screentest test
+npx vitest run --config vitest.screentest.config.ts
 ```
 
-Run vitest on the host, connect to the daemon for browser rendering.
-On failure (or new snapshots) auto-launch the review UI. Set `CI=1` to
-skip the auto-UI and just propagate the exit code.
+That's the test run — vitest on the host, our globalSetup connects to
+the daemon. On failure (or new snapshots) the UI auto-launches in your
+browser. Set `CI=1` to skip the auto-UI and just propagate the exit
+code; `SCREENTEST_NO_UI=1` does the same locally.
 
 ```bash
 screentest review
@@ -79,12 +83,15 @@ screentest init
 Scaffold vitest config + example test (see above).
 
 ```bash
-screentest <doc-json-path> [--port 5174] [--no-open]
+screentest <doc-json-path> [--port N] [--no-open]
                            [--worker-url URL] [--token TOKEN]
 ```
 
-Open the review UI on a pre-built `doc.json`. Used internally by
-`screentest test` and `screentest review`.
+Open the review UI on a pre-built `doc.json`. Used internally by the
+globalSetup hook and by `screentest review`. With no `--port`, picks a
+random free port in `[40000, 50000)` so parallel test runs don't clash.
+The UI also beacons a shutdown back to the server on tab close, so you
+don't need Ctrl+C in the terminal.
 
 ## Writing tests
 
@@ -153,7 +160,7 @@ Or pass `--worker-url` / `--token` to `screentest` directly.
 
 ```yaml
 - run: npx screentest serve # builds image + starts daemon
-- run: CI=1 npx screentest test
+- run: CI=1 npx vitest run --config vitest.screentest.config.ts
 ```
 
 In `CI=1` the orchestrator exits with vitest's code and never tries to
@@ -162,7 +169,7 @@ open the UI.
 ## Input format reference
 
 If you need to construct your own `doc.json` for the UI (instead of going
-through `screentest test` / `review`), see
+through `vitest run` / `screentest review`), see
 [the format documentation in the source repo](https://github.com/x-cevek/screentest#input-format-docjson).
 
 ## Security

package/dist/global-setup.js

@@ -1,20 +1,264 @@
 // src/runner/global-setup.ts
+import { spawn } from "child_process";
+import { promises as fs2 } from "fs";
+import { createConnection } from "net";
+import { dirname, join as join3 } from "path";
+import { fileURLToPath } from "url";
 import { firefox } from "playwright";
+
+// src/doc-builder.ts
+import { spawnSync } from "child_process";
+import { createHash } from "crypto";
+import { promises as fs } from "fs";
+import { join, relative, sep } from "path";
+function detectBranch(projectRoot) {
+  const r = spawnSync("git", ["-C", projectRoot, "rev-parse", "--abbrev-ref", "HEAD"], {
+    stdio: "pipe",
+    encoding: "utf8"
+  });
+  if (r.status !== 0) return null;
+  const branch = r.stdout.trim();
+  return branch || null;
+}
+function isGroup(node) {
+  return Array.isArray(node.items);
+}
+async function readSnapshot(snapshotFile) {
+  try {
+    return JSON.parse(await fs.readFile(snapshotFile, "utf8"));
+  } catch {
+    return { groups: [] };
+  }
+}
+function indexSnapshot(snap) {
+  const out = /* @__PURE__ */ new Map();
+  const walk = (items, prefix) => {
+    for (const it of items) {
+      if (isGroup(it)) walk(it.items, [...prefix, it.name]);
+      else out.set([...prefix, it.name].join("/"), it.hash);
+    }
+  };
+  for (const g of snap.groups) walk(g.items ?? [], [g.name]);
+  return out;
+}
+async function walkActual(dir, prefix = []) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      out.push(...await walkActual(join(dir, e.name), [...prefix, e.name]));
+    } else if (e.isFile() && e.name.endsWith(".png")) {
+      const stem = e.name.slice(0, -4);
+      out.push({ path: [...prefix, stem], absFile: join(dir, e.name) });
+    }
+  }
+  return out;
+}
+function insertLeaf(doc, path, leaf) {
+  let groups = doc.groups;
+  for (let i = 0; i < path.length - 1; i++) {
+    const name = path[i];
+    let g = groups.find((x) => "items" in x && x.name === name);
+    if (!g) {
+      g = { name, items: [] };
+      groups.push(g);
+    }
+    groups = g.items;
+  }
+  groups.push({ name: path[path.length - 1], ...leaf });
+}
+function countLeaves(doc) {
+  let n = 0;
+  const walk = (items) => {
+    for (const it of items) {
+      if ("items" in it) walk(it.items);
+      else n++;
+    }
+  };
+  for (const g of doc.groups) walk(g.items);
+  return n;
+}
+async function generateDoc(projectRoot, snapshotFile, actualDir, docFile, cacheDir) {
+  const snap = await readSnapshot(snapshotFile);
+  const expectedByPath = indexSnapshot(snap);
+  const actuals = await walkActual(actualDir);
+  const seen = /* @__PURE__ */ new Set();
+  const doc = {
+    project: { path: projectRoot, branch: detectBranch(projectRoot) },
+    groups: []
+  };
+  const summary = { new: 0, change: 0, deleted: 0, unchanged: 0 };
+  for (const a of actuals) {
+    const buf = await fs.readFile(a.absFile);
+    const hash = createHash("sha256").update(buf).digest("hex");
+    const key = a.path.join("/");
+    seen.add(key);
+    const expHash = expectedByPath.get(key);
+    const relPath = relative(cacheDir, a.absFile).split(sep).join("/");
+    if (expHash === void 0 || expHash === null) {
+      insertLeaf(doc, a.path, {
+        type: "new",
+        actualFilename: relPath,
+        patchSnapshotJsonFile: snapshotFile
+      });
+      summary.new++;
+      continue;
+    }
+    if (expHash === hash) {
+      summary.unchanged++;
+      continue;
+    }
+    insertLeaf(doc, a.path, {
+      type: "change",
+      expectedHash: expHash,
+      actualFilename: relPath,
+      patchSnapshotJsonFile: snapshotFile
+    });
+    summary.change++;
+  }
+  for (const [key, hash] of expectedByPath) {
+    if (seen.has(key) || !hash) continue;
+    insertLeaf(doc, key.split("/"), {
+      type: "deleted",
+      expectedHash: hash,
+      patchSnapshotJsonFile: snapshotFile
+    });
+    summary.deleted++;
+  }
+  await fs.mkdir(cacheDir, { recursive: true });
+  await fs.writeFile(docFile, JSON.stringify(doc, null, 2));
+  const total = countLeaves(doc);
+  process.stdout.write(
+    `Wrote ${docFile}
+  ${total} diff${total === 1 ? "" : "s"} to review (new: ${summary.new}, change: ${summary.change}, deleted: ${summary.deleted}, unchanged: ${summary.unchanged})
+`
+  );
+  return total;
+}
+
+// src/runner/paths.ts
+import { existsSync } from "fs";
+import { isAbsolute, join as join2, resolve } from "path";
+function resolveRunnerPaths(cwd = process.cwd()) {
+  const projectRoot = resolve(cwd);
+  const cacheDir = join2(projectRoot, "node_modules", ".cache", "screentest");
+  return {
+    projectRoot,
+    snapshotFile: resolveSnapshotFile(projectRoot),
+    cacheDir,
+    actualDir: join2(cacheDir, "actual"),
+    docFile: join2(cacheDir, "doc.json")
+  };
+}
+function resolveSnapshotFile(projectRoot) {
+  const envPath = process.env.SCREENTEST_SNAPSHOT_FILE;
+  if (envPath) {
+    return isAbsolute(envPath) ? envPath : join2(projectRoot, envPath);
+  }
+  const legacyRoot = join2(projectRoot, "snapshot.json");
+  const insideTests = join2(projectRoot, "tests", "snapshot.json");
+  if (existsSync(legacyRoot) && !existsSync(insideTests)) return legacyRoot;
+  return insideTests;
+}
+
+// src/runner/global-setup.ts
+var DAEMON_PORT = 5180;
+var DAEMON_WS = `ws://localhost:${DAEMON_PORT}/screentest-firefox`;
 var server;
-async function setup(project) {
+async function exists(p) {
+  try {
+    await fs2.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function probeDaemon() {
+  return new Promise((resolve2) => {
+    const s = createConnection({ host: "127.0.0.1", port: DAEMON_PORT });
+    s.once("connect", () => {
+      s.end();
+      resolve2(true);
+    });
+    s.once("error", () => resolve2(false));
+  });
+}
+async function resolveWsEndpoint() {
   const externalWs = process.env.SCREENTEST_FIREFOX_WS;
   if (externalWs) {
-    project.provide("wsEndpoint", externalWs);
-    console.log(`[screentest] using external firefox daemon: ${externalWs}`);
-    return async () => {
-    };
+    console.log(`[screentest] using firefox WS from env: ${externalWs}`);
+    return externalWs;
+  }
+  if (await probeDaemon()) {
+    console.log(`[screentest] using firefox daemon at ${DAEMON_WS}`);
+    return DAEMON_WS;
   }
   server = await firefox.launchServer();
-  const wsEndpoint = server.wsEndpoint();
+  const ws = server.wsEndpoint();
+  console.warn(
+    `[screentest] no daemon at :${DAEMON_PORT} \u2014 launched one-shot local firefox.
+[screentest] NOTE: host Firefox PNG bytes may diverge from CI / daemon
+[screentest]       (different fontconfig, AA, glyph rasterization).
+[screentest]       Run \`screentest serve\` once for CI-parity baselines.`
+  );
+  return ws;
+}
+function spawnUI(docFile) {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const bin = join3(here, "index.js");
+  return new Promise((resolve2) => {
+    const p = spawn(process.execPath, [bin, docFile], { stdio: "inherit" });
+    p.on("exit", (code) => resolve2(code ?? 0));
+  });
+}
+async function setup(project) {
+  const paths = resolveRunnerPaths();
+  await fs2.mkdir(paths.cacheDir, { recursive: true });
+  if (!await exists(paths.snapshotFile)) {
+    await fs2.mkdir(dirname(paths.snapshotFile), { recursive: true });
+    await fs2.writeFile(paths.snapshotFile, '{\n  "groups": []\n}\n');
+  }
+  await fs2.rm(paths.actualDir, { recursive: true, force: true });
+  const wsEndpoint = await resolveWsEndpoint();
   project.provide("wsEndpoint", wsEndpoint);
-  console.log(`[screentest] firefox server ready: ${wsEndpoint}`);
   return async () => {
-    await server?.close();
+    if (server) await server.close().catch(() => {
+    });
+    let total = 0;
+    try {
+      total = await generateDoc(
+        paths.projectRoot,
+        paths.snapshotFile,
+        paths.actualDir,
+        paths.docFile,
+        paths.cacheDir
+      );
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`[screentest] doc.json generation failed: ${msg}
+`);
+      return;
+    }
+    if (total === 0) return;
+    if (process.env.CI) return;
+    if (process.env.SCREENTEST_NO_UI) return;
+    process.stderr.write(
+      `
+\u2192 Visual diffs detected \u2014 launching screentest for review.
+  Close the tool (Ctrl+C) when done; the original test exit code will still propagate.
+
+`
+    );
+    const code = await spawnUI(paths.docFile);
+    if (code !== 0 && code !== 130) {
+      process.stderr.write(`(screentest UI exited with code ${code})
+`);
+    }
   };
 }
 export {