cypress-annotate 0.2.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
@@ -81,6 +81,28 @@ cy.annotate(['#promo-apply', '#order-ref'], {
81
81
  });
82
82
  ```
83
83
 
84
+ Reach into an iframe with `{ frame, selector }`. The offset is the frame's
85
+ content origin, so a frame with its own border and padding lands correctly, and a
86
+ frame scrolled internally needs no correction:
87
+
88
+ ```ts
89
+ cy.annotate({ frame: 'iframe#checkout', selector: '.pay-button' }, {
90
+ label: 'Pay button overflows the frame',
91
+ });
92
+
93
+ // nested frames, outermost first
94
+ cy.annotate({ frame: ['iframe#outer', 'iframe#inner'], selector: '.total' });
95
+
96
+ // mix frame targets and plain ones in a single shot
97
+ cy.annotate([
98
+ '#order-ref',
99
+ { frame: 'iframe#checkout', selector: '.pay-button' },
100
+ ], { label: ['Overflows', 'Escapes its card'] });
101
+ ```
102
+
103
+ Cross-origin frames cannot be measured from the page, so those fail loudly
104
+ rather than drawing a box in the wrong place.
105
+
84
106
  Crop tight to the element with the rest of the page dimmed, which is usually what
85
107
  you want to paste into a ticket:
86
108
 
@@ -352,8 +374,31 @@ present and importing each entry point for real. CI now does that on every push.
352
374
 
353
375
  - Label pill widths are estimated from an average glyph ratio, because librsvg
354
376
  gives no text measurement API. Long labels get slightly generous padding.
355
- - Only Chromium is exercised. The fixed-element behaviour in rule 2 is
356
- 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.
357
402
 
358
403
  ## Also in this package
359
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
  }
@@ -1,3 +1,4 @@
1
+ import { type AnnotateTargetSpec } from './measure-dom.js';
1
2
  import type { AnnotateTaskResult } from './task.js';
2
3
  import type { AnnotationStyle, ShapeKind } from '../types.js';
3
4
  /**
@@ -36,14 +37,23 @@ export interface AnnotateCommandOptions {
36
37
  */
37
38
  fullPage?: boolean;
38
39
  }
40
+ export type { AnnotateTargetSpec };
39
41
  declare global {
40
42
  namespace Cypress {
41
43
  interface Chainable {
42
44
  /**
43
- * Screenshot the page with an accurate box drawn around `selector`.
45
+ * Screenshot the page with an accurate box drawn around the target.
46
+ *
47
+ * A target is a CSS selector, or `{ frame, selector }` to reach into one
48
+ * or more nested iframes. An array annotates several at once.
49
+ *
50
+ * cy.annotate('#promo-apply')
51
+ * cy.annotate({ frame: 'iframe#checkout', selector: '.pay-button' })
52
+ * cy.annotate(['#total', { frame: 'iframe#checkout', selector: '.pay' }])
53
+ *
44
54
  * Yields the annotation result, including where the box was drawn.
45
55
  */
46
- annotate(selector: string | string[], options?: AnnotateCommandOptions): Chainable<AnnotateTaskResult>;
56
+ annotate(target: AnnotateTargetSpec | AnnotateTargetSpec[], options?: AnnotateCommandOptions): Chainable<AnnotateTaskResult>;
47
57
  }
48
58
  }
49
59
  }
@@ -1 +1 @@
1
- {"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/cypress/commands.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE9D;;;;;;;;GAQG;AAEH,MAAM,WAAW,sBAAsB;IACrC,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,2EAA2E;IAC3E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AA6ED,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,OAAO,CAAC;QAChB,UAAU,SAAS;YACjB;;;eAGG;YACH,QAAQ,CACN,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,EAC3B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,SAAS,CAAC,kBAAkB,CAAC,CAAC;SAClC;KACF;CACF"}
1
+ {"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/cypress/commands.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,kBAAkB,EAExB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE9D;;;;;;;;GAQG;AAEH,MAAM,WAAW,sBAAsB;IACrC,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,2EAA2E;IAC3E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,YAAY,EAAE,kBAAkB,EAAE,CAAC;AAoFnC,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,OAAO,CAAC;QAChB,UAAU,SAAS;YACjB;;;;;;;;;;;eAWG;YACH,QAAQ,CACN,MAAM,EAAE,kBAAkB,GAAG,kBAAkB,EAAE,EACjD,OAAO,CAAC,EAAE,sBAAsB,GAC/B,SAAS,CAAC,kBAAkB,CAAC,CAAC;SAClC;KACF;CACF"}
@@ -1,22 +1,23 @@
1
1
  /// <reference types="cypress" />
2
- import { measureTargets } from './measure-dom.js';
2
+ import { measureTargets, describeTarget, } from './measure-dom.js';
3
3
  import { isFullyVisible, scrollIntoViewIfNeeded } from './scroll-into-view.js';
4
4
  function slugify(text) {
5
5
  return text.replace(/[^a-z0-9]+/gi, '-').replace(/^-+|-+$/g, '').toLowerCase() || 'annotated';
6
6
  }
7
- Cypress.Commands.add('annotate', (selector, options = {}) => {
8
- const selectors = Array.isArray(selector) ? selector : [selector];
7
+ Cypress.Commands.add('annotate', (target, options = {}) => {
8
+ const specs = Array.isArray(target) ? target : [target];
9
9
  const labels = options.label === undefined
10
10
  ? []
11
11
  : Array.isArray(options.label)
12
12
  ? options.label
13
13
  : [options.label];
14
- const name = options.name ?? slugify(selectors[0] ?? 'annotated');
14
+ const first0 = specs[0];
15
+ const name = options.name ?? slugify(first0 === undefined ? 'annotated' : describeTarget(first0));
15
16
  const capture = options.fullPage ? 'fullPage' : 'viewport';
16
17
  return cy
17
18
  .window({ log: false })
18
19
  .then((win) => {
19
- const initial = measureTargets(win, selectors);
20
+ const initial = measureTargets(win, specs);
20
21
  const first = initial.targets[0];
21
22
  // Only scroll when the element genuinely is not fully visible. Cypress's
22
23
  // scrollIntoView always scrolls, so calling it unconditionally moves a
@@ -27,9 +28,15 @@ Cypress.Commands.add('annotate', (selector, options = {}) => {
27
28
  !isFullyVisible(first.rect, win);
28
29
  if (!needsScroll)
29
30
  return cy.wrap(initial, { log: false });
30
- return scrollIntoViewIfNeeded(selectors[0], options.scrollOffset ?? 120)
31
+ // cy.scrollIntoView only reaches the top document, so a target inside a
32
+ // frame is left where it is. The box is still drawn correctly; it may
33
+ // just sit outside a viewport capture.
34
+ const firstSpec = specs[0];
35
+ if (typeof firstSpec !== 'string')
36
+ return cy.wrap(initial, { log: false });
37
+ return scrollIntoViewIfNeeded(firstSpec, options.scrollOffset ?? 120)
31
38
  // Re-measure: the rects from before the scroll are now meaningless.
32
- .then(() => cy.window({ log: false }).then((w) => measureTargets(w, selectors)));
39
+ .then(() => cy.window({ log: false }).then((w) => measureTargets(w, specs)));
33
40
  })
34
41
  .then((measurement) => {
35
42
  let screenshotPath;
@@ -6,6 +6,16 @@ import type { PageMetrics } from '../types.js';
6
6
  * copy-pasteable version for agent MCP sessions. They must stay in agreement:
7
7
  * same metrics definitions, same fixed-ancestry rule, same rect shape.
8
8
  */
9
+ /**
10
+ * A target to measure. A bare string is a selector in the top document. The
11
+ * object form reaches into one or more nested iframes first, the same shape the
12
+ * Playwright path takes as `selector: ['iframe#checkout', '.pay-button']`.
13
+ */
14
+ export type AnnotateTargetSpec = string | {
15
+ frame: string | string[];
16
+ selector: string;
17
+ };
18
+ export declare function describeTarget(spec: AnnotateTargetSpec): string;
9
19
  export interface MeasuredDomTarget {
10
20
  selector: string;
11
21
  found: boolean;
@@ -48,5 +58,5 @@ export interface InventoryItem {
48
58
  */
49
59
  export declare function collectInventory(win: Window, limit?: number): InventoryItem[];
50
60
  export declare function refSelector(ref: string): string;
51
- export declare function measureTargets(win: Window, selectors: string[]): DomMeasurement;
61
+ export declare function measureTargets(top: Window, specs: AnnotateTargetSpec[]): DomMeasurement;
52
62
  //# sourceMappingURL=measure-dom.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"measure-dom.d.ts","sourceRoot":"","sources":["../../src/cypress/measure-dom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;GAMG;AAEH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAChE;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,WAAW,CAAC;IACrB,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAepD;AAOD,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/D;AAuBD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,SAAM,GAAG,aAAa,EAAE,CAqC1E;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,cAAc,CA2C/E"}
1
+ {"version":3,"file":"measure-dom.d.ts","sourceRoot":"","sources":["../../src/cypress/measure-dom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;GAMG;AAEH;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzF,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAI/D;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAChE;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,WAAW,CAAC;IACrB,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAepD;AAOD,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/D;AAuBD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,SAAM,GAAG,aAAa,EAAE,CAqC1E;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AAqDD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,EAAE,GAAG,cAAc,CAmEvF"}
@@ -1,3 +1,9 @@
1
+ export function describeTarget(spec) {
2
+ if (typeof spec === 'string')
3
+ return spec;
4
+ const frames = Array.isArray(spec.frame) ? spec.frame : [spec.frame];
5
+ return [...frames, spec.selector].join(' >>> ');
6
+ }
1
7
  export function readMetrics(win) {
2
8
  const doc = win.document.documentElement;
3
9
  const body = win.document.body;
@@ -90,12 +96,72 @@ export function collectInventory(win, limit = 120) {
90
96
  export function refSelector(ref) {
91
97
  return `[${REF_ATTR}="${ref}"]`;
92
98
  }
93
- export function measureTargets(win, selectors) {
94
- const metrics = readMetrics(win);
95
- const targets = selectors.map((selector) => {
99
+ /**
100
+ * Walk a chain of iframe selectors, accumulating the offset of each frame's
101
+ * content origin.
102
+ *
103
+ * The offset is the frame's border box plus its own border and padding, not the
104
+ * border box alone. A rect measured inside the frame is already relative to that
105
+ * frame's viewport, so the frame's internal scroll needs no correction. This is
106
+ * the same rule src/measure.ts applies on the Playwright path, and the two must
107
+ * not drift.
108
+ */
109
+ function resolveHost(top, frames) {
110
+ let win = top;
111
+ let offsetX = 0;
112
+ let offsetY = 0;
113
+ for (const frameSelector of frames) {
114
+ const frameEl = win.document.querySelector(frameSelector);
115
+ if (!frameEl)
116
+ throw new Error(`frame not found: ${frameSelector}`);
117
+ if (frameEl.tagName.toLowerCase() !== 'iframe') {
118
+ throw new Error(`not an iframe: ${frameSelector}`);
119
+ }
120
+ // Cross-origin frames throw here, or hand back null. Either way the frame's
121
+ // document cannot be measured, and saying so beats a silently wrong box.
122
+ let inner = null;
123
+ try {
124
+ inner = frameEl.contentWindow;
125
+ if (inner)
126
+ void inner.document;
127
+ }
128
+ catch {
129
+ inner = null;
130
+ }
131
+ if (!inner || !inner.document) {
132
+ throw new Error(`cross-origin frame cannot be measured: ${frameSelector}`);
133
+ }
134
+ const rect = frameEl.getBoundingClientRect();
135
+ const style = win.getComputedStyle(frameEl);
136
+ offsetX += rect.left + parseFloat(style.borderLeftWidth) + parseFloat(style.paddingLeft);
137
+ offsetY += rect.top + parseFloat(style.borderTopWidth) + parseFloat(style.paddingTop);
138
+ win = inner;
139
+ }
140
+ return { win, offsetX, offsetY };
141
+ }
142
+ export function measureTargets(top, specs) {
143
+ const metrics = readMetrics(top);
144
+ const targets = specs.map((spec) => {
145
+ const selector = describeTarget(spec);
146
+ const frames = typeof spec === 'string'
147
+ ? []
148
+ : Array.isArray(spec.frame) ? spec.frame : [spec.frame];
149
+ const targetSelector = typeof spec === 'string' ? spec : spec.selector;
150
+ let host;
151
+ try {
152
+ host = resolveHost(top, frames);
153
+ }
154
+ catch (error) {
155
+ return {
156
+ selector,
157
+ found: false,
158
+ error: error instanceof Error ? error.message : String(error),
159
+ };
160
+ }
161
+ const { win, offsetX, offsetY } = host;
96
162
  let matches;
97
163
  try {
98
- matches = win.document.querySelectorAll(selector);
164
+ matches = win.document.querySelectorAll(targetSelector);
99
165
  }
100
166
  catch (error) {
101
167
  return {
@@ -117,6 +183,10 @@ export function measureTargets(win, selectors) {
117
183
  break;
118
184
  }
119
185
  }
186
+ // Lift the frame-relative rect into top-document viewport space, which is
187
+ // the space the screenshot is in.
188
+ const x = r.x + offsetX;
189
+ const y = r.y + offsetY;
120
190
  return {
121
191
  selector,
122
192
  found: true,
@@ -124,8 +194,8 @@ export function measureTargets(win, selectors) {
124
194
  tag: el.tagName.toLowerCase(),
125
195
  text: (el.textContent ?? '').replace(/\s+/g, ' ').trim().slice(0, 80),
126
196
  isFixed,
127
- rect: { x: r.x, y: r.y, width: r.width, height: r.height },
128
- inViewport: r.bottom > 0 && r.right > 0 && r.top < win.innerHeight && r.left < win.innerWidth,
197
+ rect: { x, y, width: r.width, height: r.height },
198
+ inViewport: y + r.height > 0 && x + r.width > 0 && y < top.innerHeight && x < top.innerWidth,
129
199
  };
130
200
  });
131
201
  return { metrics, targets };
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.2.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",
@@ -53,6 +53,17 @@ cy.annotate(['#promo-apply', '#order-ref'], {
53
53
  });
54
54
  ```
55
55
 
56
+ Reach into an iframe with `{ frame, selector }`, outermost frame first:
57
+
58
+ ```ts
59
+ cy.annotate({ frame: 'iframe#checkout', selector: '.pay-button' });
60
+ cy.annotate({ frame: ['iframe#outer', 'iframe#inner'], selector: '.total' });
61
+ ```
62
+
63
+ The offset used is the frame's content origin, so frames with their own border
64
+ and padding land correctly and a frame's internal scroll needs no correction.
65
+ Cross-origin frames cannot be measured and fail loudly.
66
+
56
67
  Crop tight with the rest dimmed, which is what to use for a ticket attachment:
57
68
 
58
69
  ```ts