@cevek/screentest 0.3.5 → 0.3.6

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.
package/README.md CHANGED
@@ -14,6 +14,16 @@ npm i -D @cevek/screentest playwright vitest && npx playwright install firefox
14
14
 
15
15
  `playwright` and `vitest` are peer-deps — keep them in your devDependencies.
16
16
 
17
+ > **Linking a local checkout** (`pnpm link` / `npm link` / `file:` dep): the
18
+ > linked package resolves `playwright` from its own `node_modules`, so your
19
+ > app and the runner end up on two separate playwright instances. Playwright
20
+ > keeps its selector registry as per-instance module state, so a
21
+ > `selectors.setTestIdAttribute(...)` your suite calls has no effect on the
22
+ > pages `newPage()` creates. Anchor the resolution on the consumer side
23
+ > (typically by aliasing `playwright` to the realpath of your own copy in
24
+ > the vitest config), or install the package normally — with the peer-dep
25
+ > there is a single instance and nothing to anchor.
26
+
17
27
  ## Quick start
18
28
 
19
29
  ```bash
@@ -70,6 +80,42 @@ the daemon. On failure (or new snapshots) the UI auto-launches in your
70
80
  browser. Set `CI=1` to skip the auto-UI and just propagate the exit
71
81
  code; `SCREENTEST_NO_UI=1` does the same locally.
72
82
 
83
+ ### Soft mode — diffs as data, not failures
84
+
85
+ `SCREENTEST_SOFT=1` keeps the exit code green when the only failures
86
+ are visual (new or changed snapshots) — functional assertions still
87
+ fail the run. Each diff is warned to the console and recorded to
88
+ `node_modules/.cache/screentest/soft-report.json`:
89
+
90
+ ```json
91
+ {
92
+ "entries": [
93
+ { "path": ["team", "login flow", "login"], "status": "CHANGED", "actualPng": "/abs/….png" },
94
+ { "path": ["team", "login flow", "header"], "status": "NEW", "actualPng": "/abs/….png" },
95
+ { "path": ["old group", "gone"], "status": "ORPHAN" }
96
+ ]
97
+ }
98
+ ```
99
+
100
+ `NEW`/`CHANGED` point at the PNG this run captured. `ORPHAN` means
101
+ `snapshot.json` holds a hash the run didn't capture (reported only on
102
+ unfiltered runs, like deletions in the UI). `entries: []` means the run
103
+ was classified clean; an **absent** file means the run never reached
104
+ classification — don't read absence as "no diffs". Soft mode never
105
+ auto-launches the review UI: it exists for machine-driven (CI / agent)
106
+ e2e runs where a visual diff is a human's decision to make later via
107
+ `screentest review`, not a reason to break the pipeline.
108
+
109
+ The flag is read as a value, not as "is it defined": empty, `0` and
110
+ `false` (any case) keep soft mode **off**, anything else turns it on — so
111
+ a CI matrix can carry `SCREENTEST_SOFT=0` on the strict legs instead of
112
+ having to unset the variable.
113
+
114
+ Set the flag in the **shell environment** of the vitest process, not via
115
+ vitest's `test.env` option — that option reaches only test workers, so
116
+ diffs would be softened but the report (written by our globalSetup in
117
+ the main process) would never appear.
118
+
73
119
  ```bash
74
120
  screentest review
75
121
  ```
@@ -72,17 +72,6 @@ function insertLeaf(doc, path, leaf) {
72
72
  }
73
73
  groups.push({ name: path[path.length - 1], ...leaf });
74
74
  }
75
- function countLeaves(doc) {
76
- let n = 0;
77
- const walk = (items) => {
78
- for (const it of items) {
79
- if ("items" in it) walk(it.items);
80
- else n++;
81
- }
82
- };
83
- for (const g of doc.groups) walk(g.items);
84
- return n;
85
- }
86
75
  async function generateDoc(projectRoot, snapshotFile, actualDir, docFile, cacheDir, opts = {}) {
87
76
  const detectDeletions = opts.detectDeletions ?? true;
88
77
  const snap = await readSnapshot(snapshotFile);
@@ -94,6 +83,7 @@ async function generateDoc(projectRoot, snapshotFile, actualDir, docFile, cacheD
94
83
  groups: []
95
84
  };
96
85
  const summary = { new: 0, change: 0, deleted: 0, unchanged: 0 };
86
+ const leaves = [];
97
87
  for (const a of actuals) {
98
88
  const buf = await fs.readFile(a.absFile);
99
89
  const hash = createHash("sha256").update(buf).digest("hex");
@@ -107,6 +97,7 @@ async function generateDoc(projectRoot, snapshotFile, actualDir, docFile, cacheD
107
97
  actualFilename: relPath,
108
98
  patchSnapshotJsonFile: snapshotFile
109
99
  });
100
+ leaves.push({ path: a.path, type: "new", absFile: a.absFile });
110
101
  summary.new++;
111
102
  continue;
112
103
  }
@@ -120,6 +111,7 @@ async function generateDoc(projectRoot, snapshotFile, actualDir, docFile, cacheD
120
111
  actualFilename: relPath,
121
112
  patchSnapshotJsonFile: snapshotFile
122
113
  });
114
+ leaves.push({ path: a.path, type: "change", absFile: a.absFile });
123
115
  summary.change++;
124
116
  }
125
117
  if (detectDeletions) {
@@ -130,19 +122,20 @@ async function generateDoc(projectRoot, snapshotFile, actualDir, docFile, cacheD
130
122
  expectedHash: hash,
131
123
  patchSnapshotJsonFile: snapshotFile
132
124
  });
125
+ leaves.push({ path: key.split("/"), type: "deleted" });
133
126
  summary.deleted++;
134
127
  }
135
128
  }
136
129
  await fs.mkdir(cacheDir, { recursive: true });
137
130
  await fs.writeFile(docFile, JSON.stringify(doc, null, 2));
138
- const total = countLeaves(doc);
131
+ const total = leaves.length;
139
132
  const deletedSummary = detectDeletions ? `deleted: ${summary.deleted}, ` : "";
140
133
  process.stdout.write(
141
134
  `Wrote ${docFile}
142
135
  ${total} diff${total === 1 ? "" : "s"} to review (new: ${summary.new}, change: ${summary.change}, ${deletedSummary}unchanged: ${summary.unchanged}${detectDeletions ? "" : "; deletion detection disabled \u2014 subset run"})
143
136
  `
144
137
  );
145
- return total;
138
+ return { total, leaves };
146
139
  }
147
140
 
148
141
  // src/runner/paths.ts
@@ -156,7 +149,8 @@ function resolveRunnerPaths(cwd = process.cwd()) {
156
149
  snapshotFile: resolveSnapshotFile(projectRoot),
157
150
  cacheDir,
158
151
  actualDir: join2(cacheDir, "actual"),
159
- docFile: join2(cacheDir, "doc.json")
152
+ docFile: join2(cacheDir, "doc.json"),
153
+ softReportFile: join2(cacheDir, "soft-report.json")
160
154
  };
161
155
  }
162
156
  function resolveSnapshotFile(projectRoot) {
@@ -170,6 +164,12 @@ function resolveSnapshotFile(projectRoot) {
170
164
  return insideTests;
171
165
  }
172
166
 
167
+ // src/runner/soft-mode.ts
168
+ function isSoftMode() {
169
+ const raw = process.env.SCREENTEST_SOFT?.trim().toLowerCase();
170
+ return raw !== void 0 && raw !== "" && raw !== "0" && raw !== "false";
171
+ }
172
+
173
173
  // src/runner/global-setup.ts
174
174
  var DAEMON_PORT = 5180;
175
175
  var DAEMON_WS = `ws://localhost:${DAEMON_PORT}/screentest-firefox`;
@@ -262,6 +262,7 @@ async function setup(project) {
262
262
  await fs2.writeFile(paths.snapshotFile, '{\n "groups": []\n}\n');
263
263
  }
264
264
  await fs2.rm(paths.actualDir, { recursive: true, force: true });
265
+ await fs2.rm(paths.softReportFile, { force: true });
265
266
  const wsEndpoint = await resolveWsEndpoint();
266
267
  project.provide("wsEndpoint", wsEndpoint);
267
268
  return async () => {
@@ -276,9 +277,9 @@ async function setup(project) {
276
277
  `
277
278
  );
278
279
  }
279
- let total = 0;
280
+ let result;
280
281
  try {
281
- total = await generateDoc(
282
+ result = await generateDoc(
282
283
  paths.projectRoot,
283
284
  paths.snapshotFile,
284
285
  paths.actualDir,
@@ -292,9 +293,22 @@ async function setup(project) {
292
293
  `);
293
294
  return;
294
295
  }
295
- if (total === 0) return;
296
+ if (isSoftMode()) {
297
+ const entries = result.leaves.map(
298
+ (l) => l.type === "deleted" ? { path: l.path, status: "ORPHAN" } : { path: l.path, status: l.type === "new" ? "NEW" : "CHANGED", actualPng: l.absFile }
299
+ );
300
+ const tmpFile = `${paths.softReportFile}.tmp`;
301
+ await fs2.writeFile(tmpFile, JSON.stringify({ entries }, null, 2) + "\n");
302
+ await fs2.rename(tmpFile, paths.softReportFile);
303
+ process.stderr.write(
304
+ `[screentest] SOFT: ${entries.length} snapshot diff(s) recorded to ${paths.softReportFile} \u2014 exit code not affected.
305
+ `
306
+ );
307
+ }
308
+ if (result.total === 0) return;
296
309
  if (process.env.CI) return;
297
310
  if (process.env.SCREENTEST_NO_UI) return;
311
+ if (isSoftMode()) return;
298
312
  process.stderr.write(
299
313
  `
300
314
  \u2192 Visual diffs detected \u2014 launching screentest for review.
package/dist/index.js CHANGED
@@ -15232,17 +15232,6 @@ function insertLeaf(doc, path, leaf) {
15232
15232
  }
15233
15233
  groups.push({ name: path[path.length - 1], ...leaf });
15234
15234
  }
15235
- function countLeaves(doc) {
15236
- let n = 0;
15237
- const walk = (items) => {
15238
- for (const it of items) {
15239
- if ("items" in it) walk(it.items);
15240
- else n++;
15241
- }
15242
- };
15243
- for (const g of doc.groups) walk(g.items);
15244
- return n;
15245
- }
15246
15235
  async function generateDoc(projectRoot, snapshotFile, actualDir, docFile, cacheDir, opts = {}) {
15247
15236
  const detectDeletions = opts.detectDeletions ?? true;
15248
15237
  const snap = await readSnapshot(snapshotFile);
@@ -15254,6 +15243,7 @@ async function generateDoc(projectRoot, snapshotFile, actualDir, docFile, cacheD
15254
15243
  groups: []
15255
15244
  };
15256
15245
  const summary = { new: 0, change: 0, deleted: 0, unchanged: 0 };
15246
+ const leaves = [];
15257
15247
  for (const a of actuals) {
15258
15248
  const buf = await fs4.readFile(a.absFile);
15259
15249
  const hash2 = createHash2("sha256").update(buf).digest("hex");
@@ -15267,6 +15257,7 @@ async function generateDoc(projectRoot, snapshotFile, actualDir, docFile, cacheD
15267
15257
  actualFilename: relPath,
15268
15258
  patchSnapshotJsonFile: snapshotFile
15269
15259
  });
15260
+ leaves.push({ path: a.path, type: "new", absFile: a.absFile });
15270
15261
  summary.new++;
15271
15262
  continue;
15272
15263
  }
@@ -15280,6 +15271,7 @@ async function generateDoc(projectRoot, snapshotFile, actualDir, docFile, cacheD
15280
15271
  actualFilename: relPath,
15281
15272
  patchSnapshotJsonFile: snapshotFile
15282
15273
  });
15274
+ leaves.push({ path: a.path, type: "change", absFile: a.absFile });
15283
15275
  summary.change++;
15284
15276
  }
15285
15277
  if (detectDeletions) {
@@ -15290,19 +15282,20 @@ async function generateDoc(projectRoot, snapshotFile, actualDir, docFile, cacheD
15290
15282
  expectedHash: hash2,
15291
15283
  patchSnapshotJsonFile: snapshotFile
15292
15284
  });
15285
+ leaves.push({ path: key.split("/"), type: "deleted" });
15293
15286
  summary.deleted++;
15294
15287
  }
15295
15288
  }
15296
15289
  await fs4.mkdir(cacheDir, { recursive: true });
15297
15290
  await fs4.writeFile(docFile, JSON.stringify(doc, null, 2));
15298
- const total = countLeaves(doc);
15291
+ const total = leaves.length;
15299
15292
  const deletedSummary = detectDeletions ? `deleted: ${summary.deleted}, ` : "";
15300
15293
  process.stdout.write(
15301
15294
  `Wrote ${docFile}
15302
15295
  ${total} diff${total === 1 ? "" : "s"} to review (new: ${summary.new}, change: ${summary.change}, ${deletedSummary}unchanged: ${summary.unchanged}${detectDeletions ? "" : "; deletion detection disabled \u2014 subset run"})
15303
15296
  `
15304
15297
  );
15305
- return total;
15298
+ return { total, leaves };
15306
15299
  }
15307
15300
 
15308
15301
  // src/runner/paths.ts
@@ -15316,7 +15309,8 @@ function resolveRunnerPaths(cwd = process.cwd()) {
15316
15309
  snapshotFile: resolveSnapshotFile(projectRoot),
15317
15310
  cacheDir,
15318
15311
  actualDir: join3(cacheDir, "actual"),
15319
- docFile: join3(cacheDir, "doc.json")
15312
+ docFile: join3(cacheDir, "doc.json"),
15313
+ softReportFile: join3(cacheDir, "soft-report.json")
15320
15314
  };
15321
15315
  }
15322
15316
  function resolveSnapshotFile(projectRoot) {
@@ -15339,7 +15333,7 @@ function run(cmd, argv) {
15339
15333
  }
15340
15334
  async function runReview() {
15341
15335
  const paths = resolveRunnerPaths();
15342
- const total = await generateDoc(
15336
+ const { total } = await generateDoc(
15343
15337
  paths.projectRoot,
15344
15338
  paths.snapshotFile,
15345
15339
  paths.actualDir,
@@ -15613,6 +15607,10 @@ function printHelp() {
15613
15607
  " APP_URL default http://localhost:5050",
15614
15608
  " CI if set, do not auto-open the review UI on failure",
15615
15609
  " SCREENTEST_NO_UI if set, never auto-open the review UI",
15610
+ " SCREENTEST_SOFT snapshot diffs (new/changed) warn instead of failing",
15611
+ " the run; a machine-readable soft-report.json is written",
15612
+ " to node_modules/.cache/screentest/. Off for empty, 0",
15613
+ " and false; on for any other value",
15616
15614
  " SCREENTEST_FIREFOX_WS override the daemon WS endpoint",
15617
15615
  " SCREENTEST_SNAPSHOT_FILE override snapshot.json path (default tests/snapshot.json)",
15618
15616
  ""
package/dist/runner.js CHANGED
@@ -15,7 +15,8 @@ function resolveRunnerPaths(cwd = process.cwd()) {
15
15
  snapshotFile: resolveSnapshotFile(projectRoot),
16
16
  cacheDir,
17
17
  actualDir: join(cacheDir, "actual"),
18
- docFile: join(cacheDir, "doc.json")
18
+ docFile: join(cacheDir, "doc.json"),
19
+ softReportFile: join(cacheDir, "soft-report.json")
19
20
  };
20
21
  }
21
22
  function resolveSnapshotFile(projectRoot) {
@@ -29,6 +30,12 @@ function resolveSnapshotFile(projectRoot) {
29
30
  return insideTests;
30
31
  }
31
32
 
33
+ // src/runner/soft-mode.ts
34
+ function isSoftMode() {
35
+ const raw = process.env.SCREENTEST_SOFT?.trim().toLowerCase();
36
+ return raw !== void 0 && raw !== "" && raw !== "0" && raw !== "false";
37
+ }
38
+
32
39
  // src/runner/stabilize.ts
33
40
  async function freezeDate(ctx, when) {
34
41
  const fixedMs = when instanceof Date ? when.getTime() : typeof when === "number" ? when : Date.parse(when);
@@ -178,15 +185,23 @@ async function compareSnapshot(target, name, opts = {}) {
178
185
  if (expectedHash === void 0) {
179
186
  await insertNullEntry(paths.snapshotFile, path);
180
187
  }
188
+ const soft = isSoftMode();
181
189
  if (expectedHash === void 0 || expectedHash === null) {
182
- expect.soft(
183
- null,
184
- `Snapshot "${name}" is NEW (hash ${actualHash.slice(0, 12)}\u2026). Run \`screentest review\` to accept it.`
185
- ).toBeTruthy();
190
+ const message = `Snapshot "${name}" is NEW (hash ${actualHash.slice(0, 12)}\u2026). Run \`screentest review\` to accept it.`;
191
+ if (soft) {
192
+ console.warn(`[screentest] SOFT: ${message}`);
193
+ return;
194
+ }
195
+ expect.soft(null, message).toBeTruthy();
186
196
  return;
187
197
  }
188
198
  if (actualHash !== expectedHash) {
189
- expect.soft(actualHash, `Snapshot "${name}" changed. Run \`screentest review\` to inspect.`).toBe(expectedHash);
199
+ const message = `Snapshot "${name}" changed. Run \`screentest review\` to inspect.`;
200
+ if (soft) {
201
+ console.warn(`[screentest] SOFT: ${message}`);
202
+ return;
203
+ }
204
+ expect.soft(actualHash, message).toBe(expectedHash);
190
205
  }
191
206
  }
192
207
 
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "publishConfig": {
4
4
  "access": "public"
5
5
  },
6
- "version": "0.3.5",
6
+ "version": "0.3.6",
7
7
  "description": "Local desktop tool for visual screenshot-test review — CLI, runner helpers, and review UI shipped as a single package.",
8
8
  "license": "MIT",
9
9
  "type": "module",
@@ -27,6 +27,7 @@
27
27
  "scripts": {
28
28
  "build": "tsup && node scripts/postbuild.mjs",
29
29
  "start": "node dist/index.js",
30
+ "test": "vitest run",
30
31
  "typecheck": "tsc --noEmit",
31
32
  "prepublishOnly": "pnpm -w typecheck && pnpm -w build"
32
33
  },