@cevek/screentest 0.2.1 → 0.2.3

package/README.md

@@ -7,33 +7,45 @@ screenshots. Everything ships in one npm package — no copy-paste.
 ## Install
 
 ```bash
-pnpm add -D @cevek/screentest playwright vitest
-pnpm exec playwright install firefox
+# pick your package manager — all three are supported:
+npm  i -D @cevek/screentest playwright vitest && npx  playwright install firefox
+# pnpm add -D @cevek/screentest playwright vitest && pnpm exec playwright install firefox
+# yarn add -D @cevek/screentest playwright vitest && yarn playwright install firefox
 ```
 
 `playwright` and `vitest` are peer-deps — keep them in your devDependencies.
 
+`screentest init` detects your package manager (from your lockfile or
+`packageManager` field) and writes a matching `Dockerfile.tests`.
+
 ## Quick start
 
 ```bash
 # 1. Scaffold the test harness into your project.
-pnpm exec screentest init
+npx screentest init
 
 # 2. Build the Docker image once.
 docker build -f Dockerfile.tests -t screentest-tests .
 
 # 3. Run.
-APP_URL=http://localhost:5050 pnpm exec screentest test
+APP_URL=http://localhost:5050 npx screentest test
 ```
 
 `screentest init` creates:
 
 - `Dockerfile.tests` — playwright-noble + your project deps + vitest CMD
-- `vitest.config.ts` — pre-wired with the package's globalSetup
+  (auto-picked for pnpm / npm / yarn based on your lockfile)
+- `vitest.screentest.config.ts` — separate vitest config wired with the
+  package's globalSetup. Kept under its own name so your normal
+  `vitest.config.ts` (unit tests) is untouched.
 - `tests/example.test.ts` — minimal Playwright test using the runner helpers
 
 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.
+
 ## Commands
 
 ```bash
@@ -125,7 +137,7 @@ Or pass `--worker-url` / `--token` to `screentest` directly.
 
 ```yaml
 - run: docker build -f Dockerfile.tests -t screentest-tests .
-- run: CI=1 pnpm exec screentest test
+- run: CI=1 npx screentest test
 ```
 
 In `CI=1` the orchestrator exits with vitest's code and never tries to open

package/dist/index.js

@@ -15286,7 +15286,7 @@ async function runOrchestrator(opts = {}) {
   await fs4.rm(paths.actualDir, { recursive: true, force: true });
   let testCode;
   if (opts.hostMode) {
-    testCode = await run("pnpm", ["exec", "vitest", "run"]);
+    testCode = await run("npx", ["vitest", "--config", "vitest.screentest.config.ts", "run"]);
   } else {
     if (opts.requireDockerImage !== false && !ensureDockerImage()) {
       return 1;
@@ -15320,17 +15320,36 @@ async function runOrchestrator(opts = {}) {
 }
 
 // src/init.ts
-import { copyFile, mkdir } from "fs/promises";
+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 { 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";
+  try {
+    const pkg = JSON.parse(
+      await readFile(join4(cwd, "package.json"), "utf8")
+    );
+    const pm = pkg.packageManager ?? "";
+    if (pm.startsWith("pnpm")) return "pnpm";
+    if (pm.startsWith("yarn")) return "yarn";
+  } catch {
+  }
+  return "npm";
+}
 async function runInit() {
   const here = dirname4(fileURLToPath2(import.meta.url));
   const templatesDir = [resolve6(here, "./templates"), resolve6(here, "../templates")].find((p) => existsSync2(p)) ?? resolve6(here, "./templates");
   const cwd = process.cwd();
+  const pm = await detectPackageManager(cwd);
+  process.stdout.write(`Detected package manager: ${pm}
+
+`);
   const targets = [
-    { from: "Dockerfile.tests", to: "Dockerfile.tests" },
-    { from: "vitest.config.ts", to: "vitest.config.ts" },
+    { from: `Dockerfile.${pm}.tests`, to: "Dockerfile.tests" },
+    { from: "vitest.screentest.config.ts", to: "vitest.screentest.config.ts" },
     { from: "example.test.ts", to: "tests/example.test.ts" }
   ];
   for (const { from, to } of targets) {
@@ -15355,7 +15374,7 @@ async function runInit() {
     `
 Next steps:
   1. docker build -f Dockerfile.tests -t screentest-tests .
-  2. APP_URL=http://localhost:<your-app-port> pnpm exec screentest test
+  2. APP_URL=http://localhost:<your-app-port> npx screentest test
 `
   );
   return 0;

package/dist/runner.d.ts

@@ -1,21 +1,40 @@
-import type { BrowserContext, BrowserContextOptions, Page } from 'playwright';
+import type { BrowserContext, BrowserContextOptions, 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`).
+ * `type` and `path` are reserved — the runner always shoots PNG and writes
+ * into `node_modules/.cache/screentest/actual/...`.
+ */
+export type CompareSnapshotOptions = Omit<PageScreenshotOptions, 'type' | 'path'>;
+
+/**
+ * Capture a PNG, save under
  * `<project>/node_modules/.cache/screentest/actual/<...path>.png`, and
  * compare its SHA256 against the hash in `<project>/snapshot.json`.
  *
  * 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'`,
+ * `caret: 'hide'`.
  */
-export function compareSnapshot(page: Page, name: string): Promise<void>;
+export function compareSnapshot(
+  page: Page,
+  name: string,
+  opts?: CompareSnapshotOptions,
+): Promise<void>;
 
 /**
  * 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

@@ -96,7 +96,7 @@ function currentTestChain() {
   if (!full) return [];
   return full.split(" > ");
 }
-async function compareSnapshot(page, name) {
+async function compareSnapshot(page, 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");
@@ -107,9 +107,11 @@ async function compareSnapshot(page, name) {
   await waitForVisualStable(page);
   const actualBuf = await page.screenshot({
     fullPage: true,
-    type: "png",
     animations: "disabled",
-    caret: "hide"
+    caret: "hide",
+    ...opts,
+    type: "png"
+    // always — we hash PNG bytes
   });
   await writeFile(absFile, actualBuf);
   const actualHash = createHash("sha256").update(actualBuf).digest("hex");

package/dist/templates/Dockerfile.npm.tests

@@ -0,0 +1,17 @@
+FROM mcr.microsoft.com/playwright:v1.60.0-noble
+
+WORKDIR /work
+
+# Install dependencies. --ignore-scripts skips your project's postinstall
+# hooks (which usually scan src/ — not needed for the test image).
+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
+
+# Run vitest directly (skipping `npm exec`) — keeps the test image simple
+# and matches how the host orchestrator invokes it.
+CMD ["./node_modules/.bin/vitest", "--config", "vitest.screentest.config.ts", "run"]

package/dist/templates/Dockerfile.pnpm.tests

@@ -0,0 +1,28 @@
+FROM mcr.microsoft.com/playwright:v1.60.0-noble
+
+WORKDIR /work
+
+# corepack lets us use whatever pnpm version your project's `packageManager`
+# field pins (pnpm 11 by default in modern projects). If your project uses
+# npm or yarn instead, swap the install commands accordingly.
+RUN corepack enable
+
+# Install dependencies. Flags:
+#   --ignore-scripts        skips your project's postinstall hooks (which
+#                            usually scan src/ — not needed for the test image).
+#   --config.minimumReleaseAge=0  bypass pnpm 11's supply-chain policy for
+#                            freshly-published packages (the test image is
+#                            ephemeral, runs only what's already in lockfile).
+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
+
+# 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
+# even after install succeeded.
+CMD ["./node_modules/.bin/vitest", "--config", "vitest.screentest.config.ts", "run"]

package/dist/templates/Dockerfile.yarn.tests

@@ -0,0 +1,21 @@
+FROM mcr.microsoft.com/playwright:v1.60.0-noble
+
+WORKDIR /work
+
+# corepack lets yarn 2+/berry self-install from your project's
+# `packageManager` field. For yarn 1 it's a no-op (yarn is bundled in newer
+# Node images anyway).
+RUN corepack enable
+
+# Install dependencies. --ignore-scripts skips your project's postinstall
+# hooks (which usually scan src/ — not needed for the test image).
+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
+
+CMD ["./node_modules/.bin/vitest", "--config", "vitest.screentest.config.ts", "run"]

package/package.json

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

package/dist/templates/Dockerfile.tests

@@ -1,19 +0,0 @@
-FROM mcr.microsoft.com/playwright:v1.60.0-noble
-
-WORKDIR /work
-
-# Install pnpm — if your project uses npm/yarn, swap the next two lines.
-RUN npm install -g pnpm@9
-
-# Install dependencies. --ignore-scripts skips your project's postinstall
-# hooks (which usually scan src/ — not needed for the test image).
-COPY package.json pnpm-lock.yaml ./
-COPY pnpm-workspace.yaml* ./
-RUN pnpm install --frozen-lockfile --ignore-scripts
-
-# Only the bits needed to run vitest.
-COPY vitest.config.ts ./
-COPY tsconfig*.json ./
-COPY tests ./tests
-
-CMD ["pnpm", "exec", "vitest", "run"]