@cevek/screentest 0.3.6 → 0.4.0

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,16 +14,6 @@ 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
-
27
17
  ## Quick start
28
18
 
29
19
  ```bash
@@ -80,42 +70,6 @@ the daemon. On failure (or new snapshots) the UI auto-launches in your
80
70
  browser. Set `CI=1` to skip the auto-UI and just propagate the exit
81
71
  code; `SCREENTEST_NO_UI=1` does the same locally.
82
72
 
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
-
119
73
  ```bash
120
74
  screentest review
121
75
  ```
@@ -8,9 +8,16 @@ import { firefox } from "playwright";
8
8
 
9
9
  // src/doc-builder.ts
10
10
  import { spawnSync } from "child_process";
11
- import { createHash } from "crypto";
12
11
  import { promises as fs } from "fs";
13
12
  import { join, relative, sep } from "path";
13
+
14
+ // src/hash.ts
15
+ import { createHash } from "crypto";
16
+ function sha256Hex(buf) {
17
+ return createHash("sha256").update(buf).digest("hex");
18
+ }
19
+
20
+ // src/doc-builder.ts
14
21
  function detectBranch(projectRoot) {
15
22
  const r = spawnSync("git", ["-C", projectRoot, "rev-parse", "--abbrev-ref", "HEAD"], {
16
23
  stdio: "pipe",
@@ -38,7 +45,7 @@ function indexSnapshot(snap) {
38
45
  else out.set([...prefix, it.name].join("/"), it.hash);
39
46
  }
40
47
  };
41
- for (const g of snap.groups) walk(g.items ?? [], [g.name]);
48
+ for (const g of snap.groups ?? []) walk(g.items ?? [], [g.name]);
42
49
  return out;
43
50
  }
44
51
  async function walkActual(dir, prefix = []) {
@@ -72,6 +79,17 @@ function insertLeaf(doc, path, leaf) {
72
79
  }
73
80
  groups.push({ name: path[path.length - 1], ...leaf });
74
81
  }
82
+ function countLeaves(doc) {
83
+ let n = 0;
84
+ const walk = (items) => {
85
+ for (const it of items) {
86
+ if ("items" in it) walk(it.items);
87
+ else n++;
88
+ }
89
+ };
90
+ for (const g of doc.groups) walk(g.items);
91
+ return n;
92
+ }
75
93
  async function generateDoc(projectRoot, snapshotFile, actualDir, docFile, cacheDir, opts = {}) {
76
94
  const detectDeletions = opts.detectDeletions ?? true;
77
95
  const snap = await readSnapshot(snapshotFile);
@@ -83,10 +101,9 @@ async function generateDoc(projectRoot, snapshotFile, actualDir, docFile, cacheD
83
101
  groups: []
84
102
  };
85
103
  const summary = { new: 0, change: 0, deleted: 0, unchanged: 0 };
86
- const leaves = [];
87
104
  for (const a of actuals) {
88
105
  const buf = await fs.readFile(a.absFile);
89
- const hash = createHash("sha256").update(buf).digest("hex");
106
+ const hash = sha256Hex(buf);
90
107
  const key = a.path.join("/");
91
108
  seen.add(key);
92
109
  const expHash = expectedByPath.get(key);
@@ -97,7 +114,6 @@ async function generateDoc(projectRoot, snapshotFile, actualDir, docFile, cacheD
97
114
  actualFilename: relPath,
98
115
  patchSnapshotJsonFile: snapshotFile
99
116
  });
100
- leaves.push({ path: a.path, type: "new", absFile: a.absFile });
101
117
  summary.new++;
102
118
  continue;
103
119
  }
@@ -111,7 +127,6 @@ async function generateDoc(projectRoot, snapshotFile, actualDir, docFile, cacheD
111
127
  actualFilename: relPath,
112
128
  patchSnapshotJsonFile: snapshotFile
113
129
  });
114
- leaves.push({ path: a.path, type: "change", absFile: a.absFile });
115
130
  summary.change++;
116
131
  }
117
132
  if (detectDeletions) {
@@ -122,20 +137,19 @@ async function generateDoc(projectRoot, snapshotFile, actualDir, docFile, cacheD
122
137
  expectedHash: hash,
123
138
  patchSnapshotJsonFile: snapshotFile
124
139
  });
125
- leaves.push({ path: key.split("/"), type: "deleted" });
126
140
  summary.deleted++;
127
141
  }
128
142
  }
129
143
  await fs.mkdir(cacheDir, { recursive: true });
130
144
  await fs.writeFile(docFile, JSON.stringify(doc, null, 2));
131
- const total = leaves.length;
145
+ const total = countLeaves(doc);
132
146
  const deletedSummary = detectDeletions ? `deleted: ${summary.deleted}, ` : "";
133
147
  process.stdout.write(
134
148
  `Wrote ${docFile}
135
149
  ${total} diff${total === 1 ? "" : "s"} to review (new: ${summary.new}, change: ${summary.change}, ${deletedSummary}unchanged: ${summary.unchanged}${detectDeletions ? "" : "; deletion detection disabled \u2014 subset run"})
136
150
  `
137
151
  );
138
- return { total, leaves };
152
+ return total;
139
153
  }
140
154
 
141
155
  // src/runner/paths.ts
@@ -149,8 +163,7 @@ function resolveRunnerPaths(cwd = process.cwd()) {
149
163
  snapshotFile: resolveSnapshotFile(projectRoot),
150
164
  cacheDir,
151
165
  actualDir: join2(cacheDir, "actual"),
152
- docFile: join2(cacheDir, "doc.json"),
153
- softReportFile: join2(cacheDir, "soft-report.json")
166
+ docFile: join2(cacheDir, "doc.json")
154
167
  };
155
168
  }
156
169
  function resolveSnapshotFile(projectRoot) {
@@ -164,12 +177,6 @@ function resolveSnapshotFile(projectRoot) {
164
177
  return insideTests;
165
178
  }
166
179
 
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
180
  // src/runner/global-setup.ts
174
181
  var DAEMON_PORT = 5180;
175
182
  var DAEMON_WS = `ws://localhost:${DAEMON_PORT}/screentest-firefox`;
@@ -262,7 +269,6 @@ async function setup(project) {
262
269
  await fs2.writeFile(paths.snapshotFile, '{\n "groups": []\n}\n');
263
270
  }
264
271
  await fs2.rm(paths.actualDir, { recursive: true, force: true });
265
- await fs2.rm(paths.softReportFile, { force: true });
266
272
  const wsEndpoint = await resolveWsEndpoint();
267
273
  project.provide("wsEndpoint", wsEndpoint);
268
274
  return async () => {
@@ -277,9 +283,9 @@ async function setup(project) {
277
283
  `
278
284
  );
279
285
  }
280
- let result;
286
+ let total = 0;
281
287
  try {
282
- result = await generateDoc(
288
+ total = await generateDoc(
283
289
  paths.projectRoot,
284
290
  paths.snapshotFile,
285
291
  paths.actualDir,
@@ -293,22 +299,9 @@ async function setup(project) {
293
299
  `);
294
300
  return;
295
301
  }
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;
302
+ if (total === 0) return;
309
303
  if (process.env.CI) return;
310
304
  if (process.env.SCREENTEST_NO_UI) return;
311
- if (isSoftMode()) return;
312
305
  process.stderr.write(
313
306
  `
314
307
  \u2192 Visual diffs detected \u2014 launching screentest for review.