cypress-annotate 1.0.0 → 1.1.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/AGENTS.md CHANGED
@@ -49,7 +49,7 @@ say so explicitly, and they mean it.
49
49
 
50
50
  ```bash
51
51
  npm run typecheck
52
- npm run test:cypress # 12 cases, real Cypress
52
+ npm run test:cypress # 14 cases, real Cypress
53
53
  npm run test:cypress-failures # 4 cases end to end, real Cypress
54
54
  npm run test:failure-selector # 12 cases, no browser
55
55
  npm run test:svg-escaping # 9 cases
package/CHANGELOG.md CHANGED
@@ -3,6 +3,38 @@
3
3
  Notable changes to `cypress-annotate`. Each release's section here becomes the
4
4
  body of its GitHub release.
5
5
 
6
+ ## 1.1.0
7
+
8
+ ### Fixed
9
+
10
+ - Boxes landed up and to the left of the target when the viewport was bigger
11
+ than the headless browser window. A 1920x1080 viewport in a 1280x720 window
12
+ produces a screenshot of the viewport's top-left corner at full scale, and the
13
+ narrow image was taken for a resized one, so on a 2x screen every coordinate
14
+ came out at two thirds of its true value. `cy.annotate()` and the failure hook
15
+ now pass Cypress's own `pixelRatio` and `scaled` to the task, and the image
16
+ width is only used to infer a scale when Cypress says it resized the image.
17
+ - A target outside the captured area is skipped with a warning instead of being
18
+ drawn somewhere it isn't. A screenshot that covers less than the viewport also
19
+ gets a warning that says so.
20
+ - Headless Chrome keeps 87px of its window for UI it never draws, so a default
21
+ 1280x720 window captures 1280x633. The new warning caught this in the repo's
22
+ own Chrome run, where one target in a multi-target case had been drawn off the
23
+ bottom of the image. The test config now sizes the window to fit, and the
24
+ skill's traps section explains how to do the same.
25
+
26
+ ### Security
27
+
28
+ - `sharp` now needs 0.35.5 or later. Earlier versions bundle a librsvg affected
29
+ by CVE-2026-96889 ([GHSA-wq5f-xc86-pv6w](https://github.com/advisories/GHSA-wq5f-xc86-pv6w)),
30
+ and librsvg is what renders the overlay.
31
+
32
+ ### Added
33
+
34
+ - `annotateImage()` takes `captureReport: { pixelRatio, scaled }`, and
35
+ `resolveScale()` takes it as an optional fifth argument, for callers outside
36
+ Cypress whose capture tool reports the same thing.
37
+
6
38
  ## 1.0.0
7
39
 
8
40
  The package shipped two products under one name. `cy.annotate()` and the failure
package/DOCS/internals.md CHANGED
@@ -77,7 +77,7 @@ Playwright pipeline they were written for.
77
77
 
78
78
  ```bash
79
79
  npm install
80
- npm run test:cypress # cy.annotate and theming, 12 cases, real Cypress 15
80
+ npm run test:cypress # cy.annotate and theming, 14 cases, real Cypress 15
81
81
  npm run test:cypress-failures # failed-test capture end to end, 4 cases, real Cypress 15
82
82
  npm run test:failure-selector # failed-test selector recovery, 12 cases, no browser
83
83
  npm run test:svg-escaping # SVG injection regression suite, 9 cases
@@ -1,4 +1,4 @@
1
- import type { AnnotationStyle, CssRect, PageMetrics, PixelRect, ShapeKind } from './types.js';
1
+ import type { AnnotationStyle, CaptureReport, CssRect, PageMetrics, PixelRect, ShapeKind } from './types.js';
2
2
  /**
3
3
  * Annotating an image that somebody else captured.
4
4
  *
@@ -33,6 +33,12 @@ export interface AnnotateImageOptions {
33
33
  /** Context to keep around the target when cropping, CSS px. Default 40. */
34
34
  cropPadding?: number;
35
35
  style?: AnnotationStyle;
36
+ /**
37
+ * What the capturing tool reported about the image. Without it, the scale is
38
+ * inferred from the image width, which cannot tell a resized image from one
39
+ * the browser window cut short.
40
+ */
41
+ captureReport?: CaptureReport;
36
42
  }
37
43
  export interface AnnotateImageResult {
38
44
  image: Buffer;
@@ -42,6 +48,7 @@ export interface AnnotateImageResult {
42
48
  height: number;
43
49
  /** Image pixels per CSS pixel actually used. */
44
50
  scale: number;
51
+ /** One per target that landed in the image. A target outside it is skipped, with a warning. */
45
52
  drawnRects: PixelRect[];
46
53
  warnings: string[];
47
54
  }
@@ -59,7 +66,12 @@ export declare function resolveStyle(...layers: (AnnotationStyle | undefined)[])
59
66
  * screenshots to keep them cheap to send, and a capture that has been resized
60
67
  * behind your back is exactly what makes a box drift. So the image is measured
61
68
  * and the reported ratio is treated as a hint.
69
+ *
70
+ * A narrow image has a second explanation, though. A headless browser window
71
+ * smaller than the viewport captures only its top-left corner, at full scale,
72
+ * and width alone cannot tell that apart from a resize. So when the capturing
73
+ * tool says the image was not resized, its pixel ratio wins.
62
74
  */
63
- export declare function resolveScale(imageWidth: number, cssWidth: number, devicePixelRatio: number, warnings: string[]): number;
75
+ export declare function resolveScale(imageWidth: number, cssWidth: number, devicePixelRatio: number, warnings: string[], report?: CaptureReport): number;
64
76
  export declare function annotateImage(screenshot: Buffer, targets: MeasuredTarget[], options: AnnotateImageOptions): Promise<AnnotateImageResult>;
65
77
  //# sourceMappingURL=annotate-image.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"annotate-image.d.ts","sourceRoot":"","sources":["../src/annotate-image.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,eAAe,EACf,OAAO,EACP,WAAW,EACX,SAAS,EACT,SAAS,EACV,MAAM,YAAY,CAAC;AAEpB;;;;;;;;GAQG;AAEH,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,YAAY,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gFAAgF;IAChF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,WAAW,CAAC;IACrB,uEAAuE;IACvE,OAAO,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAClC,+CAA+C;IAC/C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAeD;;;;GAIG;AAEH,wBAAgB,YAAY,CAAC,GAAG,MAAM,EAAE,CAAC,eAAe,GAAG,SAAS,CAAC,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC,CAQlG;AAoCD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,MAAM,EAAE,GACjB,MAAM,CAgBR;AAYD,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,cAAc,EAAE,EACzB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAkG9B"}
1
+ {"version":3,"file":"annotate-image.d.ts","sourceRoot":"","sources":["../src/annotate-image.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,OAAO,EACP,WAAW,EACX,SAAS,EACT,SAAS,EACV,MAAM,YAAY,CAAC;AAEpB;;;;;;;;GAQG;AAEH,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,YAAY,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gFAAgF;IAChF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,WAAW,CAAC;IACrB,uEAAuE;IACvE,OAAO,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAClC,+CAA+C;IAC/C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,+FAA+F;IAC/F,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAeD;;;;GAIG;AAEH,wBAAgB,YAAY,CAAC,GAAG,MAAM,EAAE,CAAC,eAAe,GAAG,SAAS,CAAC,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC,CAQlG;AAoCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,MAAM,EAAE,EAClB,MAAM,CAAC,EAAE,aAAa,GACrB,MAAM,CAkBR;AAYD,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,cAAc,EAAE,EACzB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CA6H9B"}
@@ -61,8 +61,15 @@ function clampRect(rect, width, height) {
61
61
  * screenshots to keep them cheap to send, and a capture that has been resized
62
62
  * behind your back is exactly what makes a box drift. So the image is measured
63
63
  * and the reported ratio is treated as a hint.
64
+ *
65
+ * A narrow image has a second explanation, though. A headless browser window
66
+ * smaller than the viewport captures only its top-left corner, at full scale,
67
+ * and width alone cannot tell that apart from a resize. So when the capturing
68
+ * tool says the image was not resized, its pixel ratio wins.
64
69
  */
65
- export function resolveScale(imageWidth, cssWidth, devicePixelRatio, warnings) {
70
+ export function resolveScale(imageWidth, cssWidth, devicePixelRatio, warnings, report) {
71
+ if (report && !report.scaled && report.pixelRatio > 0)
72
+ return report.pixelRatio;
66
73
  if (cssWidth <= 0) {
67
74
  warnings.push('Page metrics reported a zero-width viewport; falling back to devicePixelRatio.');
68
75
  return devicePixelRatio;
@@ -100,7 +107,17 @@ export async function annotateImage(screenshot, targets, options) {
100
107
  if (imageWidth === 0 || imageHeight === 0)
101
108
  throw new Error('Could not read the screenshot dimensions.');
102
109
  const cssWidth = fullPage ? metrics.documentWidth : metrics.viewportWidth;
103
- const scale = resolveScale(imageWidth, cssWidth, metrics.devicePixelRatio, warnings);
110
+ const cssHeight = fullPage ? metrics.documentHeight : metrics.viewportHeight;
111
+ const scale = resolveScale(imageWidth, cssWidth, metrics.devicePixelRatio, warnings, options.captureReport);
112
+ // The CSS area the image actually holds, from its own top-left corner.
113
+ const coveredWidth = imageWidth / scale;
114
+ const coveredHeight = imageHeight / scale;
115
+ if (coveredWidth < cssWidth - 1 || coveredHeight < cssHeight - 1) {
116
+ warnings.push(`Screenshot covers only ${Math.round(coveredWidth)}x${Math.round(coveredHeight)} CSS px of the ` +
117
+ `${Math.round(cssWidth)}x${Math.round(cssHeight)} ${fullPage ? 'page' : 'viewport'}, which usually ` +
118
+ `means the browser window is smaller than the viewport. Size the window to match in before:browser:launch.`);
119
+ }
120
+ const placed = [];
104
121
  for (const target of targets) {
105
122
  const name = target.describe ?? 'target';
106
123
  if (target.viewportRect.width === 0 || target.viewportRect.height === 0) {
@@ -110,18 +127,26 @@ export async function annotateImage(screenshot, targets, options) {
110
127
  warnings.push(`${name} is position:fixed, so it has no stable document position in a full-page capture; ` +
111
128
  `annotated where it was painted.`);
112
129
  }
113
- }
114
- const sourceRects = targets.map((target) => {
115
- const style = resolveStyle(options.style, target.style);
116
130
  const base = fullPage ? documentRectOf(target, metrics) : target.viewportRect;
117
- return scaleRect(inflate(base, style.padding), scale);
118
- });
131
+ const right = base.x + base.width;
132
+ const bottom = base.y + base.height;
133
+ if (base.x >= coveredWidth || base.y >= coveredHeight || right <= 0 || bottom <= 0) {
134
+ warnings.push(`${name} is outside the captured area, so no box was drawn for it.`);
135
+ continue;
136
+ }
137
+ if (base.x < 0 || base.y < 0 || right > coveredWidth || bottom > coveredHeight) {
138
+ warnings.push(`${name} runs past the edge of the captured area; its box is clipped.`);
139
+ }
140
+ const style = resolveStyle(options.style, target.style);
141
+ placed.push({ target, rect: scaleRect(inflate(base, style.padding), scale) });
142
+ }
143
+ const sourceRects = placed.map((p) => p.rect);
119
144
  let finalImage = screenshot;
120
145
  let finalWidth = imageWidth;
121
146
  let finalHeight = imageHeight;
122
147
  let originX = 0;
123
148
  let originY = 0;
124
- if (options.crop) {
149
+ if (options.crop && sourceRects.length > 0) {
125
150
  const pad = (options.cropPadding ?? 40) * scale;
126
151
  const union = sourceRects.reduce((acc, r) => {
127
152
  const x = Math.min(acc.x, r.x);
@@ -152,7 +177,7 @@ export async function annotateImage(screenshot, targets, options) {
152
177
  }
153
178
  const drawnRects = sourceRects.map((r) => ({ ...r, x: r.x - originX, y: r.y - originY }));
154
179
  const specs = drawnRects.map((rect, i) => {
155
- const target = targets[i];
180
+ const target = placed[i]?.target;
156
181
  const style = resolveStyle(options.style, target?.style);
157
182
  return {
158
183
  rect,
@@ -161,7 +186,11 @@ export async function annotateImage(screenshot, targets, options) {
161
186
  style: toDeviceStyle(style, scale),
162
187
  };
163
188
  });
164
- const image = await compositeOverlay(finalImage, buildOverlaySvg(finalWidth, finalHeight, specs));
189
+ // Nothing landed in the image, so leave it untouched. Dimming everything
190
+ // outside zero boxes would only darken the whole screenshot.
191
+ const image = specs.length > 0
192
+ ? await compositeOverlay(finalImage, buildOverlaySvg(finalWidth, finalHeight, specs))
193
+ : finalImage;
165
194
  return {
166
195
  image,
167
196
  rawImage: finalImage,
@@ -1 +1 @@
1
- {"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/cypress/commands.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,kBAAkB,EAExB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE9D;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,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;AA0FnC,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
+ {"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/cypress/commands.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,kBAAkB,EAExB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAiB,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7E;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,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;AAgGnC,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"}
@@ -44,6 +44,7 @@ Cypress.Commands.add('annotate', (target, options = {}) => {
44
44
  })
45
45
  .then((measurement) => {
46
46
  let screenshotPath;
47
+ let captureReport;
47
48
  return cy
48
49
  .screenshot(name, {
49
50
  capture,
@@ -51,6 +52,11 @@ Cypress.Commands.add('annotate', (target, options = {}) => {
51
52
  log: false,
52
53
  onAfterScreenshot(_el, props) {
53
54
  screenshotPath = props.path;
55
+ // Cypress sets `scaled` at runtime but leaves it out of its types.
56
+ // Without it, send nothing and let the scale be inferred as before.
57
+ const scaled = props.scaled;
58
+ if (typeof scaled === 'boolean')
59
+ captureReport = { pixelRatio: props.pixelRatio, scaled };
54
60
  },
55
61
  })
56
62
  .then(() => {
@@ -60,6 +66,7 @@ Cypress.Commands.add('annotate', (target, options = {}) => {
60
66
  return cy.task('annotateScreenshot', {
61
67
  screenshotPath,
62
68
  measurement,
69
+ captureReport,
63
70
  labels,
64
71
  capture,
65
72
  crop: options.crop ?? defaults.crop,
@@ -1 +1 @@
1
- {"version":3,"file":"failure-hook.d.ts","sourceRoot":"","sources":["../../src/cypress/failure-hook.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAe,MAAM,aAAa,CAAC;AAGhE,MAAM,WAAW,qBAAqB;IACpC,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,qBAA0B,GAAG,IAAI,CAmJhF"}
1
+ {"version":3,"file":"failure-hook.d.ts","sourceRoot":"","sources":["../../src/cypress/failure-hook.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAA8B,MAAM,aAAa,CAAC;AAG/E,MAAM,WAAW,qBAAqB;IACpC,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,qBAA0B,GAAG,IAAI,CAyJhF"}
@@ -91,6 +91,7 @@ export function registerFailureCapture(options = {}) {
91
91
  .then((win) => prepare(win))
92
92
  .then(({ target, resolved, inventory, metrics }) => {
93
93
  let screenshotPath;
94
+ let captureReport;
94
95
  return cy
95
96
  .screenshot(name, {
96
97
  capture: 'viewport',
@@ -98,6 +99,11 @@ export function registerFailureCapture(options = {}) {
98
99
  log: false,
99
100
  onAfterScreenshot(_el, props) {
100
101
  screenshotPath = props.path;
102
+ // Cypress sets `scaled` at runtime but leaves it out of its types.
103
+ // Without it, send nothing and let the scale be inferred as before.
104
+ const scaled = props.scaled;
105
+ if (typeof scaled === 'boolean')
106
+ captureReport = { pixelRatio: props.pixelRatio, scaled };
101
107
  },
102
108
  })
103
109
  .then(() => {
@@ -110,6 +116,7 @@ export function registerFailureCapture(options = {}) {
110
116
  return cy.task('annotateScreenshot', {
111
117
  screenshotPath,
112
118
  measurement: { metrics, targets: [target] },
119
+ captureReport,
113
120
  labels: [label],
114
121
  capture: 'viewport',
115
122
  style: { ...defaults.style, ...options.style },
@@ -1,4 +1,4 @@
1
- import type { AnnotationStyle, PixelRect, ShapeKind } from '../types.js';
1
+ import type { AnnotationStyle, CaptureReport, PixelRect, ShapeKind } from '../types.js';
2
2
  import type { DomMeasurement } from './measure-dom.js';
3
3
  /**
4
4
  * The Node half of the Cypress plugin.
@@ -10,6 +10,8 @@ import type { DomMeasurement } from './measure-dom.js';
10
10
  export interface AnnotateTaskArgs {
11
11
  screenshotPath: string;
12
12
  measurement: DomMeasurement;
13
+ /** `pixelRatio` and `scaled` from Cypress's `onAfterScreenshot` props. */
14
+ captureReport?: CaptureReport;
13
15
  labels?: (string | undefined)[];
14
16
  capture?: 'viewport' | 'fullPage';
15
17
  crop?: boolean;
@@ -1 +1 @@
1
- {"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/cypress/task.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAIvD;;;;;;GAMG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,cAAc,CAAC;IAC5B,MAAM,CAAC,EAAE,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAClC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAwCD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA4E5F;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;AAI5D,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAQ9F"}
1
+ {"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/cypress/task.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAIvD;;;;;;GAMG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,cAAc,CAAC;IAC5B,0EAA0E;IAC1E,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,MAAM,CAAC,EAAE,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAClC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAwCD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA6E5F;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;AAI5D,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAQ9F"}
@@ -72,6 +72,7 @@ export async function annotateScreenshot(args) {
72
72
  crop: args.crop,
73
73
  cropPadding: args.cropPadding,
74
74
  style: args.style,
75
+ captureReport: args.captureReport,
75
76
  });
76
77
  const outPath = args.outPath ?? screenshotPath;
77
78
  let rawPath = null;
package/dist/types.d.ts CHANGED
@@ -25,6 +25,16 @@ export interface PageMetrics {
25
25
  documentWidth: number;
26
26
  documentHeight: number;
27
27
  }
28
+ /**
29
+ * What the tool that took the screenshot says about it. Cypress hands this to
30
+ * `onAfterScreenshot` as `props.pixelRatio` and `props.scaled`.
31
+ */
32
+ export interface CaptureReport {
33
+ /** Image pixels per CSS pixel at capture time. */
34
+ pixelRatio: number;
35
+ /** Whether the image was resized after capture. */
36
+ scaled: boolean;
37
+ }
28
38
  export type ShapeKind = 'box' | 'circle' | 'arrow';
29
39
  export interface AnnotationStyle {
30
40
  /** CSS colour for the outline and label background. */
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,MAAM,WAAW,OAAO;IACtB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,iFAAiF;AACjF,MAAM,WAAW,SAAS;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,8DAA8D;IAC9D,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEnD,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4FAA4F;IAC5F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qCAAqC;IACrC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qCAAqC;IACrC,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACnC"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,MAAM,WAAW,OAAO;IACtB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,iFAAiF;AACjF,MAAM,WAAW,SAAS;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,8DAA8D;IAC9D,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEnD,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4FAA4F;IAC5F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qCAAqC;IACrC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qCAAqC;IACrC,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACnC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cypress-annotate",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "description": "Draw a box on exactly what failed. Every failed Cypress test gets an annotated screenshot, in CI, with no AI and no browser download.",
5
5
  "keywords": [
6
6
  "cypress",
@@ -100,7 +100,7 @@
100
100
  "typecheck": "tsc --noEmit"
101
101
  },
102
102
  "dependencies": {
103
- "sharp": "^0.35.4"
103
+ "sharp": "^0.35.5"
104
104
  },
105
105
  "peerDependencies": {
106
106
  "cypress": ">=13"
@@ -156,6 +156,17 @@ genuinely needed.
156
156
  scroll, or click. A rectangle is only valid for the scroll position it was
157
157
  measured at. Using `cy.annotate()` rather than hand-rolling this is the point.
158
158
 
159
+ **A viewport bigger than the headless window is captured only up to the
160
+ window's edge.** Headless browsers open at 1280x720, so `viewportWidth: 1920`
161
+ gets a screenshot of the viewport's top-left 1280x720 corner. The box still lands
162
+ in the right place, but anything past that corner has no box and a warning in
163
+ `annotations.json`. Size the window to match in `before:browser:launch`, with
164
+ `--window-size=1920,1080` for Chrome or `launchOptions.preferences.width` and
165
+ `height` for Electron. Headless Chrome also keeps 87px of its window height for
166
+ UI it never draws, so its default 1280x720 window captures only 1280x633, which
167
+ cuts the bottom off even Cypress's default 1000x660 viewport. Make the Chrome
168
+ window 87px taller than the viewport.
169
+
159
170
  **Exact-colour assertions fail on macOS Electron.** Its capture applies a
160
171
  colour-profile shift, so `#FF00E4` comes back as `rgb(234,51,221)`. Sample the
161
172
  colour from the image rather than trusting the stylesheet.