cypress-annotate 0.2.0 → 0.3.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
 
@@ -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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cypress-annotate",
3
- "version": "0.2.0",
3
+ "version": "0.3.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",
@@ -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