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 +47 -2
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +13 -3
- 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/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/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
|
|
|
@@ -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
|
-
-
|
|
356
|
-
|
|
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
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
|
}
|
|
@@ -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/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",
|
|
@@ -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
|