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 +22 -0
- package/dist/cypress/commands.d.ts +12 -2
- package/dist/cypress/commands.d.ts.map +1 -1
- package/dist/cypress/commands.js +14 -7
- package/dist/cypress/measure-dom.d.ts +11 -1
- package/dist/cypress/measure-dom.d.ts.map +1 -1
- package/dist/cypress/measure-dom.js +76 -6
- package/package.json +1 -1
- package/skills/cypress-annotate/SKILL.md +11 -0
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
|
|
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(
|
|
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":"
|
|
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"}
|
package/dist/cypress/commands.js
CHANGED
|
@@ -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', (
|
|
8
|
-
const
|
|
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
|
|
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,
|
|
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
|
-
|
|
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,
|
|
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(
|
|
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;
|
|
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
|
-
|
|
94
|
-
|
|
95
|
-
|
|
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(
|
|
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
|
|
128
|
-
inViewport: r.
|
|
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
|
@@ -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
|