cypress-annotate 0.3.0 → 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 +25 -2
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +13 -3
- package/dist/index.d.ts +0 -9
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +21 -1
- package/package.json +4 -1
package/README.md
CHANGED
|
@@ -374,8 +374,31 @@ present and importing each entry point for real. CI now does that on every push.
|
|
|
374
374
|
|
|
375
375
|
- Label pill widths are estimated from an average glyph ratio, because librsvg
|
|
376
376
|
gives no text measurement API. Long labels get slightly generous padding.
|
|
377
|
-
-
|
|
378
|
-
|
|
377
|
+
- The Cypress plugin is exercised on Electron, Chrome and Firefox in CI, so
|
|
378
|
+
element measurement, dpr scaling, transforms, cropping and iframe offsets are
|
|
379
|
+
verified on Gecko as well as Chromium. The alignment suites behind
|
|
380
|
+
[How alignment is verified](#how-alignment-is-verified) still run on Chromium
|
|
381
|
+
only, and no suite on any browser covers the fixed-element behaviour in
|
|
382
|
+
coordinate rule 2, which the plugin sidesteps by capturing the viewport by
|
|
383
|
+
default.
|
|
384
|
+
|
|
385
|
+
## The CLI
|
|
386
|
+
|
|
387
|
+
Installing the package puts a `cypress-annotate` binary on your path. It drives
|
|
388
|
+
the Playwright pipeline rather than the Cypress plugin, so it needs the optional
|
|
389
|
+
peer:
|
|
390
|
+
|
|
391
|
+
```bash
|
|
392
|
+
npm install playwright
|
|
393
|
+
npx playwright install chromium
|
|
394
|
+
|
|
395
|
+
npx cypress-annotate --url https://example.com --selector 'a' --label 'Broken link'
|
|
396
|
+
npx cypress-annotate --help
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
Run it without playwright and it says so, along with the two commands that fix
|
|
400
|
+
it. `--selector` and `--label` are repeatable and pair up in order, and
|
|
401
|
+
`iframe#pay >>> .btn` reaches into a frame.
|
|
379
402
|
|
|
380
403
|
## Also in this package
|
|
381
404
|
|
package/dist/cli.d.ts
CHANGED
package/dist/cli.js
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
1
2
|
import { writeFile } from 'node:fs/promises';
|
|
2
3
|
import { parseArgs } from 'node:util';
|
|
3
4
|
import { captureAnnotated } from './index.js';
|
|
4
5
|
const USAGE = `
|
|
5
|
-
Usage:
|
|
6
|
+
Usage: cypress-annotate --url <url> --selector <css> [options]
|
|
6
7
|
|
|
7
8
|
--url <url> Page to open (http(s):// or file://).
|
|
8
9
|
--selector <css> Element to annotate. Repeatable.
|
|
@@ -47,6 +48,15 @@ const annotations = values.selector.map((selector, i) => ({
|
|
|
47
48
|
label: values.label[i],
|
|
48
49
|
shape: values.shape,
|
|
49
50
|
}));
|
|
51
|
+
/**
|
|
52
|
+
* A CLI should print what went wrong and nothing else. Without this, a missing
|
|
53
|
+
* playwright surfaces as an unhandled rejection: the useful sentence buried in
|
|
54
|
+
* a Node module-loader stack, plus the whole `cause` chain printed underneath.
|
|
55
|
+
*/
|
|
56
|
+
function fail(error) {
|
|
57
|
+
console.error(error instanceof Error ? error.message : String(error));
|
|
58
|
+
process.exit(1);
|
|
59
|
+
}
|
|
50
60
|
const result = await captureAnnotated(values.url, annotations, {
|
|
51
61
|
mode: values.mode,
|
|
52
62
|
viewport: { width: Number(values.width), height: Number(values.height) },
|
|
@@ -56,8 +66,8 @@ const result = await captureAnnotated(values.url, annotations, {
|
|
|
56
66
|
...(values.color ? { color: values.color } : {}),
|
|
57
67
|
...(values.dim ? { dimOutside: Number(values.dim) } : {}),
|
|
58
68
|
},
|
|
59
|
-
});
|
|
60
|
-
await writeFile(values.out, result.image);
|
|
69
|
+
}).catch(fail);
|
|
70
|
+
await writeFile(values.out, result.image).catch(fail);
|
|
61
71
|
if (values.json) {
|
|
62
72
|
console.log(JSON.stringify({ out: values.out, width: result.width, height: result.height, metrics: result.metrics, elements: result.elements, drawnRects: result.drawnRects, warnings: result.warnings }, null, 2));
|
|
63
73
|
}
|
package/dist/index.d.ts
CHANGED
|
@@ -19,14 +19,5 @@ export interface CaptureOptions extends AnnotateOptions {
|
|
|
19
19
|
settleMs?: number;
|
|
20
20
|
launch?: LaunchOptions;
|
|
21
21
|
}
|
|
22
|
-
/**
|
|
23
|
-
* One-shot: open a URL, annotate it, close the browser.
|
|
24
|
-
*
|
|
25
|
-
* Playwright is loaded lazily, on the first call, rather than imported at the
|
|
26
|
-
* top of this file. `playwright` is an optional peer dependency - a consumer
|
|
27
|
-
* who only wants annotateImage()/the Cypress plugin (neither of which touch a
|
|
28
|
-
* browser at all) should never be forced to have it installed just because
|
|
29
|
-
* this function exists somewhere else in the same package.
|
|
30
|
-
*/
|
|
31
22
|
export declare function captureAnnotated(url: string, annotations: Annotation[], options?: CaptureOptions): Promise<AnnotateResult>;
|
|
32
23
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,KAAK,EAAW,aAAa,EAAE,MAAM,YAAY,CAAC;AAEzD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EACL,aAAa,EACb,YAAY,EACZ,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAKvF,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,QAAQ,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AACpF,mBAAmB,YAAY,CAAC;AAEhC,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,KAAK,EAAW,aAAa,EAAE,MAAM,YAAY,CAAC;AAEzD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EACL,aAAa,EACb,YAAY,EACZ,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAKvF,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,QAAQ,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AACpF,mBAAmB,YAAY,CAAC;AAEhC,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAkCD,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,UAAU,EAAE,EACzB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,cAAc,CAAC,CAgBzB"}
|
package/dist/index.js
CHANGED
|
@@ -19,10 +19,30 @@ export { runBugHunt } from './pipeline.js';
|
|
|
19
19
|
* browser at all) should never be forced to have it installed just because
|
|
20
20
|
* this function exists somewhere else in the same package.
|
|
21
21
|
*/
|
|
22
|
+
/**
|
|
23
|
+
* playwright is an optional peer, so a consumer who only uses the Cypress
|
|
24
|
+
* plugin or annotateImage never installs it. Reaching this without it is an
|
|
25
|
+
* ordinary mistake, and the bare ERR_MODULE_NOT_FOUND names an internal dist
|
|
26
|
+
* path rather than the two commands that fix it.
|
|
27
|
+
*/
|
|
28
|
+
async function loadChromium() {
|
|
29
|
+
try {
|
|
30
|
+
return await import('playwright');
|
|
31
|
+
}
|
|
32
|
+
catch (error) {
|
|
33
|
+
if (error?.code === 'ERR_MODULE_NOT_FOUND') {
|
|
34
|
+
throw new Error('captureAnnotated() needs playwright, which is an optional peer dependency.\n' +
|
|
35
|
+
' npm install playwright\n' +
|
|
36
|
+
' npx playwright install chromium\n' +
|
|
37
|
+
'The Cypress plugin and annotateImage() do not need it.', { cause: error });
|
|
38
|
+
}
|
|
39
|
+
throw error;
|
|
40
|
+
}
|
|
41
|
+
}
|
|
22
42
|
export async function captureAnnotated(url, annotations, options = {}) {
|
|
23
43
|
let browser;
|
|
24
44
|
try {
|
|
25
|
-
const { chromium } = await
|
|
45
|
+
const { chromium } = await loadChromium();
|
|
26
46
|
browser = await chromium.launch({ headless: options.headless ?? true, ...options.launch });
|
|
27
47
|
const context = await browser.newContext({
|
|
28
48
|
viewport: options.viewport ?? { width: 1280, height: 800 },
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cypress-annotate",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "Annotate Cypress screenshots and failed-test runs with pixel-accurate boxes, pointing at exactly what broke.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"cypress",
|
|
@@ -42,6 +42,9 @@
|
|
|
42
42
|
"type": "module",
|
|
43
43
|
"main": "dist/index.js",
|
|
44
44
|
"types": "dist/index.d.ts",
|
|
45
|
+
"bin": {
|
|
46
|
+
"cypress-annotate": "./dist/cli.js"
|
|
47
|
+
},
|
|
45
48
|
"exports": {
|
|
46
49
|
".": {
|
|
47
50
|
"types": "./dist/index.d.ts",
|