@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 +46 -0
- package/dist/global-setup.js +31 -17
- package/dist/index.js +13 -15
- package/dist/runner.js +21 -6
- package/package.json +2 -1
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
|
```
|
package/dist/global-setup.js
CHANGED
|
@@ -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 =
|
|
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
|
|
280
|
+
let result;
|
|
280
281
|
try {
|
|
281
|
-
|
|
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 (
|
|
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 =
|
|
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
|
-
|
|
183
|
-
|
|
184
|
-
`
|
|
185
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
},
|