cypress-annotate 0.1.0 → 0.1.2
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/DOCS/pipeline.md +50 -0
- package/README.md +4 -0
- package/package.json +11 -5
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/README.md
CHANGED
|
@@ -16,6 +16,10 @@ else to configure.
|
|
|
16
16
|
npm install --save-dev cypress-annotate
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
+
Needs Node 20.19+ or 22.12+. The package is ESM, and those are the versions that
|
|
20
|
+
can `require()` an ES module, which is what Cypress's default webpack and Babel
|
|
21
|
+
preprocessor ends up doing with the import in step 3.
|
|
22
|
+
|
|
19
23
|
### 2. Register the Node task
|
|
20
24
|
|
|
21
25
|
The measuring happens in the browser, the image compositing happens in Node. This
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cypress-annotate",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
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",
|
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
},
|
|
38
38
|
"homepage": "https://github.com/bidemiajala/cypress-annotate#readme",
|
|
39
39
|
"engines": {
|
|
40
|
-
"node": ">=
|
|
40
|
+
"node": "^20.19.0 || >=22.12.0"
|
|
41
41
|
},
|
|
42
42
|
"type": "module",
|
|
43
43
|
"main": "dist/index.js",
|
|
@@ -45,15 +45,21 @@
|
|
|
45
45
|
"exports": {
|
|
46
46
|
".": {
|
|
47
47
|
"types": "./dist/index.d.ts",
|
|
48
|
-
"import": "./dist/index.js"
|
|
48
|
+
"import": "./dist/index.js",
|
|
49
|
+
"require": "./dist/index.js",
|
|
50
|
+
"default": "./dist/index.js"
|
|
49
51
|
},
|
|
50
52
|
"./reasoner": {
|
|
51
53
|
"types": "./dist/claude-reasoner.d.ts",
|
|
52
|
-
"import": "./dist/claude-reasoner.js"
|
|
54
|
+
"import": "./dist/claude-reasoner.js",
|
|
55
|
+
"require": "./dist/claude-reasoner.js",
|
|
56
|
+
"default": "./dist/claude-reasoner.js"
|
|
53
57
|
},
|
|
54
58
|
"./cypress/*": {
|
|
55
59
|
"types": "./dist/cypress/*.d.ts",
|
|
56
|
-
"import": "./dist/cypress/*.js"
|
|
60
|
+
"import": "./dist/cypress/*.js",
|
|
61
|
+
"require": "./dist/cypress/*.js",
|
|
62
|
+
"default": "./dist/cypress/*.js"
|
|
57
63
|
}
|
|
58
64
|
},
|
|
59
65
|
"files": [
|