@cevek/screentest 0.2.3 → 0.2.5

package/dist/index.js

@@ -15093,32 +15093,13 @@ async function runUI(opts) {
 
 // src/orchestrator.ts
 import { spawn, spawnSync } from "child_process";
+import { promises as fs5 } from "fs";
+import { join as join4 } from "path";
+
+// src/doc-builder.ts
 import { createHash as createHash2 } from "crypto";
 import { promises as fs4 } from "fs";
-import { join as join3, relative, sep } from "path";
-
-// src/runner/paths.ts
-import { join as join2, resolve as resolve5 } from "path";
-function resolveRunnerPaths(cwd = process.cwd()) {
-  const projectRoot = resolve5(cwd);
-  const cacheDir = join2(projectRoot, "node_modules", ".cache", "screentest");
-  return {
-    projectRoot,
-    snapshotFile: join2(projectRoot, "snapshot.json"),
-    cacheDir,
-    actualDir: join2(cacheDir, "actual"),
-    docFile: join2(cacheDir, "doc.json")
-  };
-}
-
-// src/orchestrator.ts
-var DOCKER_IMAGE = "screentest-tests";
-function run(cmd, argv) {
-  return new Promise((resolve7) => {
-    const p = spawn(cmd, argv, { stdio: "inherit" });
-    p.on("exit", (code) => resolve7(code ?? 0));
-  });
-}
+import { join as join2, relative, sep } from "path";
 function isGroup(node) {
   return Array.isArray(node.items);
 }
@@ -15150,10 +15131,10 @@ async function walkActual(dir, prefix = []) {
   const out = [];
   for (const e of entries) {
     if (e.isDirectory()) {
-      out.push(...await walkActual(join3(dir, e.name), [...prefix, e.name]));
+      out.push(...await walkActual(join2(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: join3(dir, e.name) });
+      out.push({ path: [...prefix, stem], absFile: join2(dir, e.name) });
     }
   }
   return out;
@@ -15236,20 +15217,114 @@ async function generateDoc(snapshotFile, actualDir, docFile, cacheDir) {
   );
   return total;
 }
-function ensureDockerImage() {
-  const r = spawnSync("docker", ["image", "inspect", DOCKER_IMAGE], { stdio: "pipe" });
-  if (r.status !== 0) {
+
+// src/runner/paths.ts
+import { join as join3, resolve as resolve5 } from "path";
+function resolveRunnerPaths(cwd = process.cwd()) {
+  const projectRoot = resolve5(cwd);
+  const cacheDir = join3(projectRoot, "node_modules", ".cache", "screentest");
+  return {
+    projectRoot,
+    snapshotFile: join3(projectRoot, "snapshot.json"),
+    cacheDir,
+    actualDir: join3(cacheDir, "actual"),
+    docFile: join3(cacheDir, "doc.json")
+  };
+}
+
+// src/orchestrator.ts
+var DOCKER_IMAGE = "screentest-tests";
+function run(cmd, argv) {
+  return new Promise((resolve7) => {
+    const p = spawn(cmd, argv, { stdio: "inherit" });
+    p.on("exit", (code) => resolve7(code ?? 0));
+  });
+}
+async function exists(absPath) {
+  try {
+    await fs5.access(absPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function ensureDockerImageFresh(projectRoot) {
+  const dockerfile = join4(projectRoot, "Dockerfile.tests");
+  if (!await exists(dockerfile)) {
     process.stderr.write(
-      `Docker image "${DOCKER_IMAGE}" not found.
-  Build it first:  pnpm exec screentest init && docker build -f Dockerfile.tests -t screentest-tests .
-  Or run host-side: pnpm exec screentest test --host
+      `Dockerfile.tests not found at ${dockerfile}
+  Did you run \`screentest init\` in this project?
 `
     );
     return false;
   }
+  const inspect = spawnSync(
+    "docker",
+    ["image", "inspect", "--format", "{{.Created}}", DOCKER_IMAGE],
+    { stdio: "pipe", encoding: "utf8" }
+  );
+  let reason = null;
+  if (inspect.status !== 0) {
+    reason = `Docker image "${DOCKER_IMAGE}" not found \u2014 building it (first build takes ~2 min).`;
+  } else {
+    const imageCreated = new Date(inspect.stdout.trim()).getTime();
+    const inputs = [
+      "package.json",
+      "pnpm-lock.yaml",
+      "package-lock.json",
+      "yarn.lock",
+      "Dockerfile.tests"
+    ];
+    for (const f of inputs) {
+      const abs = join4(projectRoot, f);
+      try {
+        const st = await fs5.stat(abs);
+        if (st.mtimeMs > imageCreated) {
+          reason = `${f} changed since the image was built \u2014 rebuilding.`;
+          break;
+        }
+      } catch {
+      }
+    }
+  }
+  if (!reason) return true;
+  process.stderr.write(`${reason}
+`);
+  const code = await run("docker", [
+    "build",
+    "-f",
+    "Dockerfile.tests",
+    "-t",
+    DOCKER_IMAGE,
+    projectRoot
+  ]);
+  if (code !== 0) {
+    process.stderr.write(`docker build failed (exit ${code})
+`);
+    return false;
+  }
   return true;
 }
-async function runVitestInDocker(snapshotFile, cacheDir) {
+async function runVitestInDocker(projectRoot, snapshotFile, cacheDir) {
+  const testsDir = join4(projectRoot, "tests");
+  const configFile = join4(projectRoot, "vitest.screentest.config.ts");
+  const tsconfigFile = join4(projectRoot, "tsconfig.json");
+  if (!await exists(testsDir)) {
+    process.stderr.write(
+      `tests/ not found at ${testsDir}
+  Did you run \`screentest init\` in this project?
+`
+    );
+    return 1;
+  }
+  if (!await exists(configFile)) {
+    process.stderr.write(
+      `vitest.screentest.config.ts not found at ${configFile}
+  Did you run \`screentest init\` in this project?
+`
+    );
+    return 1;
+  }
   const dockerArgs = ["run", "--rm", "--init", "--network=host"];
   dockerArgs.push("-e", `APP_URL=${process.env.APP_URL || "http://localhost:5050"}`);
   if (process.env.CI) dockerArgs.push("-e", "CI=1");
@@ -15258,8 +15333,15 @@ async function runVitestInDocker(snapshotFile, cacheDir) {
     `${cacheDir}:/work/node_modules/.cache/screentest`,
     "-v",
     `${snapshotFile}:/work/snapshot.json`,
-    DOCKER_IMAGE
+    "-v",
+    `${testsDir}:/work/tests:ro`,
+    "-v",
+    `${configFile}:/work/vitest.screentest.config.ts:ro`
   );
+  if (await exists(tsconfigFile)) {
+    dockerArgs.push("-v", `${tsconfigFile}:/work/tsconfig.json:ro`);
+  }
+  dockerArgs.push(DOCKER_IMAGE);
   return run("docker", dockerArgs);
 }
 async function runOrchestrator(opts = {}) {
@@ -15277,21 +15359,21 @@ async function runOrchestrator(opts = {}) {
     }
     return await run("node", [process.argv[1], paths.docFile]);
   }
-  await fs4.mkdir(paths.cacheDir, { recursive: true });
+  await fs5.mkdir(paths.cacheDir, { recursive: true });
   try {
-    await fs4.access(paths.snapshotFile);
+    await fs5.access(paths.snapshotFile);
   } catch {
-    await fs4.writeFile(paths.snapshotFile, '{\n  "groups": []\n}\n');
+    await fs5.writeFile(paths.snapshotFile, '{\n  "groups": []\n}\n');
   }
-  await fs4.rm(paths.actualDir, { recursive: true, force: true });
+  await fs5.rm(paths.actualDir, { recursive: true, force: true });
   let testCode;
   if (opts.hostMode) {
     testCode = await run("npx", ["vitest", "--config", "vitest.screentest.config.ts", "run"]);
   } else {
-    if (opts.requireDockerImage !== false && !ensureDockerImage()) {
+    if (opts.requireDockerImage !== false && !await ensureDockerImageFresh(paths.projectRoot)) {
       return 1;
     }
-    testCode = await runVitestInDocker(paths.snapshotFile, paths.cacheDir);
+    testCode = await runVitestInDocker(paths.projectRoot, paths.snapshotFile, paths.cacheDir);
   }
   if (testCode !== 0 && !process.env.CI) {
     process.stderr.write(
@@ -15322,15 +15404,15 @@ async function runOrchestrator(opts = {}) {
 // src/init.ts
 import { copyFile, mkdir, readFile } from "fs/promises";
 import { existsSync as existsSync2 } from "fs";
-import { dirname as dirname4, join as join4, resolve as resolve6 } from "path";
+import { dirname as dirname4, join as join5, resolve as resolve6 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 async function detectPackageManager(cwd) {
-  if (existsSync2(join4(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync2(join4(cwd, "yarn.lock"))) return "yarn";
-  if (existsSync2(join4(cwd, "package-lock.json"))) return "npm";
+  if (existsSync2(join5(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync2(join5(cwd, "yarn.lock"))) return "yarn";
+  if (existsSync2(join5(cwd, "package-lock.json"))) return "npm";
   try {
     const pkg = JSON.parse(
-      await readFile(join4(cwd, "package.json"), "utf8")
+      await readFile(join5(cwd, "package.json"), "utf8")
     );
     const pm = pkg.packageManager ?? "";
     if (pm.startsWith("pnpm")) return "pnpm";
@@ -15353,8 +15435,8 @@ async function runInit() {
     { from: "example.test.ts", to: "tests/example.test.ts" }
   ];
   for (const { from, to } of targets) {
-    const src = join4(templatesDir, from);
-    const dst = join4(cwd, to);
+    const src = join5(templatesDir, from);
+    const dst = join5(cwd, to);
     if (existsSync2(dst)) {
       process.stdout.write(`  exists  ${to}
 `);

package/dist/runner.d.ts

@@ -1,28 +1,47 @@
-import type { BrowserContext, BrowserContextOptions, Page, PageScreenshotOptions } from 'playwright';
+import type {
+  BrowserContext,
+  BrowserContextOptions,
+  Locator,
+  Page,
+  PageScreenshotOptions,
+} from 'playwright';
 
 /**
  * Extra Playwright screenshot options the caller can pass through to
- * `compareSnapshot` (e.g. `clip`, `mask`, `omitBackground`, `fullPage: false`).
- * `type` and `path` are reserved — the runner always shoots PNG and writes
- * into `node_modules/.cache/screentest/actual/...`.
+ * `compareSnapshot` (e.g. `clip`, `mask`, `omitBackground`, `fullPage: false`,
+ * `style` for Locator targets). `type` and `path` are reserved — the runner
+ * always shoots PNG and writes into `node_modules/.cache/screentest/actual/`.
+ *
+ * For `Locator` targets, page-only options (`fullPage`, `clip`) are silently
+ * ignored by Playwright.
  */
-export type CompareSnapshotOptions = Omit<PageScreenshotOptions, 'type' | 'path'>;
+export type CompareSnapshotOptions = Omit<PageScreenshotOptions, 'type' | 'path'> & {
+  /** Locator-only: CSS injected before screenshotting (e.g. hide scrollbars). */
+  style?: string;
+};
 
 /**
  * Capture a PNG, save under
  * `<project>/node_modules/.cache/screentest/actual/<...path>.png`, and
  * compare its SHA256 against the hash in `<project>/snapshot.json`.
  *
+ * Pass a `Page` for a full-page screenshot, or a `Locator` to capture just
+ * that element's bounding box.
+ *
  * The snapshot path is built automatically from the surrounding
  * `describe(...)` + `it(...)` chain, plus `name` as the leaf. Prefix `name`
  * with `/` to opt out of auto-grouping and use an absolute path.
  *
  * Pass `opts` to forward extra Playwright screenshot options (clip, mask,
- * etc.). Defaults: `fullPage: true`, `animations: 'disabled'`,
+ * etc.). Defaults: `fullPage: true` (Page only), `animations: 'disabled'`,
  * `caret: 'hide'`.
+ *
+ * @example
+ *   await compareSnapshot(page, 'page');                // full page
+ *   await compareSnapshot(page.locator('h1'), 'h1');   // element only
  */
 export function compareSnapshot(
-  page: Page,
+  target: Page | Locator,
   name: string,
   opts?: CompareSnapshotOptions,
 ): Promise<void>;
@@ -31,10 +50,7 @@ export function compareSnapshot(
  * Freeze `Date` inside `ctx`. `when` may be an ISO string, unix-ms number,
  * or `Date`. Must be called BEFORE the first navigation in the context.
  */
-export function freezeDate(
-  ctx: BrowserContext,
-  when: string | number | Date,
-): Promise<void>;
+export function freezeDate(ctx: BrowserContext, when: string | number | Date): Promise<void>;
 
 /**
  * Wait for `document.fonts.ready` and every `<img>` to reach `complete`.

package/dist/runner.js

@@ -64,6 +64,9 @@ function initScript(opts) {
 }
 
 // src/runner/snapshot.ts
+function isPage(target) {
+  return typeof target.goto === "function";
+}
 function isGroup(x) {
   return Array.isArray(x.items);
 }
@@ -91,12 +94,51 @@ function findExpected(snap, path) {
   );
   return leaf ? leaf.hash : void 0;
 }
+var fileLocks = /* @__PURE__ */ new Map();
+async function withFileLock(absPath, fn) {
+  const prev = fileLocks.get(absPath) ?? Promise.resolve();
+  let release;
+  const next = new Promise((r) => {
+    release = r;
+  });
+  fileLocks.set(
+    absPath,
+    prev.then(() => next)
+  );
+  try {
+    await prev;
+    return await fn();
+  } finally {
+    release();
+  }
+}
+async function insertNullEntry(snapshotFile, path) {
+  await withFileLock(snapshotFile, async () => {
+    const doc = await loadSnapshot(snapshotFile);
+    const testName = path[path.length - 1];
+    const groupPath = path.slice(0, -1);
+    let items = doc.groups;
+    for (const g of groupPath) {
+      let found = items.find((n) => isGroup(n) && n.name === g);
+      if (!found) {
+        found = { name: g, items: [] };
+        items.push(found);
+      }
+      items = found.items;
+    }
+    const existing = items.find((n) => !isGroup(n) && n.name === testName);
+    if (existing) return;
+    items.push({ name: testName, hash: null });
+    await mkdir(dirname(snapshotFile), { recursive: true });
+    await writeFile(snapshotFile, JSON.stringify(doc, null, 2) + "\n", "utf8");
+  });
+}
 function currentTestChain() {
   const full = expect.getState().currentTestName ?? "";
   if (!full) return [];
   return full.split(" > ");
 }
-async function compareSnapshot(page, name, opts = {}) {
+async function compareSnapshot(target, name, opts = {}) {
   const explicit = name.split("/").filter(Boolean);
   const path = name.startsWith("/") ? explicit : [...currentTestChain(), ...explicit];
   if (path.length === 0) throw new Error("compareSnapshot: empty name");
@@ -104,18 +146,27 @@ async function compareSnapshot(page, name, opts = {}) {
   const fileRelative = `${path.join("/")}.png`;
   const absFile = join2(paths.actualDir, fileRelative);
   await mkdir(dirname(absFile), { recursive: true });
+  const page = isPage(target) ? target : target.page();
   await waitForVisualStable(page);
-  const actualBuf = await page.screenshot({
+  const actualBuf = isPage(target) ? await target.screenshot({
     fullPage: true,
     animations: "disabled",
     caret: "hide",
     ...opts,
     type: "png"
     // always — we hash PNG bytes
+  }) : await target.screenshot({
+    animations: "disabled",
+    caret: "hide",
+    ...opts,
+    type: "png"
   });
   await writeFile(absFile, actualBuf);
   const actualHash = createHash("sha256").update(actualBuf).digest("hex");
   const expectedHash = findExpected(await loadSnapshot(paths.snapshotFile), path);
+  if (expectedHash === void 0) {
+    await insertNullEntry(paths.snapshotFile, path);
+  }
   if (expectedHash === void 0 || expectedHash === null) {
     expect.soft(
       null,

package/dist/templates/Dockerfile.npm.tests

@@ -7,10 +7,9 @@ WORKDIR /work
 COPY package.json package-lock.json ./
 RUN npm ci --ignore-scripts
 
-# Only the bits needed to run vitest.
-COPY vitest.screentest.config.ts ./
-COPY tsconfig*.json ./
-COPY tests ./tests
+# tests/, vitest.screentest.config.ts, tsconfig.json, and snapshot.json are
+# bind-mounted by `screentest test` at run-time — no rebuild needed for test
+# or config edits. Rebuild only when package.json/package-lock.json change.
 
 # Run vitest directly (skipping `npm exec`) — keeps the test image simple
 # and matches how the host orchestrator invokes it.

package/dist/templates/Dockerfile.pnpm.tests

@@ -17,10 +17,9 @@ COPY package.json pnpm-lock.yaml ./
 COPY pnpm-workspace.yaml* ./
 RUN pnpm install --frozen-lockfile --ignore-scripts --config.minimumReleaseAge=0
 
-# Only the bits needed to run vitest.
-COPY vitest.screentest.config.ts ./
-COPY tsconfig*.json ./
-COPY tests ./tests
+# tests/, vitest.screentest.config.ts, tsconfig.json, and snapshot.json are
+# bind-mounted by `screentest test` at run-time — no rebuild needed for test
+# or config edits. Rebuild only when package.json/pnpm-lock.yaml change.
 
 # Run vitest directly (not via pnpm exec) — pnpm 11 re-runs its supply-chain
 # policy on every exec, which would re-fail freshly-published packages

package/dist/templates/Dockerfile.yarn.tests

@@ -13,9 +13,8 @@ COPY package.json yarn.lock ./
 COPY .yarnrc.yml* ./
 RUN yarn install --frozen-lockfile --ignore-scripts
 
-# Only the bits needed to run vitest.
-COPY vitest.screentest.config.ts ./
-COPY tsconfig*.json ./
-COPY tests ./tests
+# tests/, vitest.screentest.config.ts, tsconfig.json, and snapshot.json are
+# bind-mounted by `screentest test` at run-time — no rebuild needed for test
+# or config edits. Rebuild only when package.json/yarn.lock change.
 
 CMD ["./node_modules/.bin/vitest", "--config", "vitest.screentest.config.ts", "run"]

package/dist/templates/vitest.screentest.config.ts

@@ -6,8 +6,11 @@ export default defineConfig({
     globalSetup: ['@cevek/screentest/global-setup'],
     testTimeout: 10_000,
     hookTimeout: 10_000,
+    // One file at a time: screenshot tests share a Firefox browserServer
+    // (launched in global-setup) and would collide if files ran in parallel.
+    // In vitest 4 `poolOptions` was removed; `fileParallelism: false` forces
+    // maxWorkers=1, which is the equivalent of the old `singleFork: true`.
     pool: 'forks',
-    poolOptions: { forks: { singleFork: true } },
     fileParallelism: false,
   },
 });

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Local desktop tool for visual screenshot-test review — CLI, runner helpers, and review UI shipped as a single package.",
   "license": "MIT",
   "type": "module",