cypress-annotate 0.1.0 → 0.1.1

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.
Files changed (2) hide show
  1. package/DOCS/pipeline.md +50 -0
  2. package/package.json +1 -1
package/DOCS/pipeline.md CHANGED
@@ -58,6 +58,56 @@ overlay), the measured `elements`, the final `drawnRects` in image pixels, and
58
58
  a zero-sized box, element is outside the viewport, element is fixed during a
59
59
  full-page capture.
60
60
 
61
+ ### Annotating an image somebody else captured
62
+
63
+ `annotateImage()` is the one export here that never opens a browser and knows
64
+ nothing about any driver. Give it a PNG, the page metrics that were true when it
65
+ was taken, and rectangles in CSS pixels. The Cypress plugin and the MCP path both
66
+ go through it, and so can anything else that can produce those three things.
67
+
68
+ ```ts
69
+ import { annotateImage } from 'cypress-annotate';
70
+ import { readFile, writeFile } from 'node:fs/promises';
71
+
72
+ const result = await annotateImage(
73
+ await readFile('shot.png'),
74
+ [{
75
+ // Viewport-relative CSS px, straight from getBoundingClientRect().
76
+ viewportRect: { x: 100, y: 100, width: 320, height: 90 },
77
+ label: 'Apply button escapes its card',
78
+ }],
79
+ {
80
+ metrics: {
81
+ devicePixelRatio: 2,
82
+ scrollX: 0,
83
+ scrollY: 0,
84
+ viewportWidth: 1280,
85
+ viewportHeight: 800,
86
+ documentWidth: 1280,
87
+ documentHeight: 4200,
88
+ },
89
+ capture: 'viewport',
90
+ },
91
+ );
92
+
93
+ await writeFile('annotated.png', result.image);
94
+ console.log(result.scale, result.drawnRects, result.warnings);
95
+ ```
96
+
97
+ The argument list is positional, `(screenshot, targets, options)`, and the
98
+ metrics are the four dimensions plus scroll and dpr. Both are easy to get wrong
99
+ from the type names alone, which is why the example is here.
100
+
101
+ `devicePixelRatio` is treated as a hint rather than a fact. `resolveScale()`
102
+ compares the image against the viewport it was supposed to cover and uses the
103
+ measured ratio when the two disagree, because a screenshot that was downscaled
104
+ behind your back is exactly what makes a box drift. Whatever it settles on comes
105
+ back as `result.scale`, and a mismatch lands in `result.warnings`.
106
+
107
+ Set `isFixed: true` on a target whose element is `position: fixed`, so it gets no
108
+ scroll correction. Pass `documentRect` yourself only when the viewport rect and
109
+ the scroll offset are not enough to derive it.
110
+
61
111
  ### The region fallback
62
112
 
63
113
  When no element corresponds to the problem (blank space where something should
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cypress-annotate",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
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",