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 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
- - Only Chromium is exercised. The fixed-element behaviour in rule 2 is
378
- specifically a Chromium capture behaviour and would need re-checking elsewhere.
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
@@ -1,2 +1,3 @@
1
+ #!/usr/bin/env node
1
2
  export {};
2
3
  //# sourceMappingURL=cli.d.ts.map
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: npm run annotate -- --url <url> --selector <css> [options]
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
@@ -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;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,UAAU,EAAE,EACzB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,cAAc,CAAC,CAgBzB"}
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 import('playwright');
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.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",