@cevek/screentest 0.2.2 → 0.2.4

package/dist/runner.d.ts

@@ -1,15 +1,50 @@
-import type { BrowserContext, BrowserContextOptions, Page } from 'playwright';
+import type {
+  BrowserContext,
+  BrowserContextOptions,
+  Locator,
+  Page,
+  PageScreenshotOptions,
+} from 'playwright';
 
 /**
- * Capture a full-page PNG, save under
+ * Extra Playwright screenshot options the caller can pass through to
+ * `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'> & {
+  /** 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` (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, name: string): Promise<void>;
+export function compareSnapshot(
+  target: Page | Locator,
+  name: string,
+  opts?: CompareSnapshotOptions,
+): Promise<void>;
 
 /**
  * Freeze `Date` inside `ctx`. `when` may be an ISO string, unix-ms number,

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) {
+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,16 +146,27 @@ async function compareSnapshot(page, name) {
   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,
-    type: "png",
     animations: "disabled",
-    caret: "hide"
+    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/package.json

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