cypress-annotate 0.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 +65 -0
- package/DOCS/pipeline.md +258 -0
- package/LICENSE +21 -0
- package/README.md +360 -0
- package/dist/annotate-image.d.ts +60 -0
- package/dist/annotate-image.d.ts.map +1 -0
- package/dist/annotate-image.js +160 -0
- package/dist/annotate.d.ts +9 -0
- package/dist/annotate.d.ts.map +1 -0
- package/dist/annotate.js +82 -0
- package/dist/browser/collect-elements.js +158 -0
- package/dist/browser/measure-target.js +69 -0
- package/dist/claude-reasoner.d.ts +17 -0
- package/dist/claude-reasoner.d.ts.map +1 -0
- package/dist/claude-reasoner.js +192 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +74 -0
- package/dist/cypress/commands.d.ts +50 -0
- package/dist/cypress/commands.d.ts.map +1 -0
- package/dist/cypress/commands.js +68 -0
- package/dist/cypress/failure-explainer.d.ts +45 -0
- package/dist/cypress/failure-explainer.d.ts.map +1 -0
- package/dist/cypress/failure-explainer.js +123 -0
- package/dist/cypress/failure-hook.d.ts +30 -0
- package/dist/cypress/failure-hook.d.ts.map +1 -0
- package/dist/cypress/failure-hook.js +148 -0
- package/dist/cypress/failure-report.d.ts +41 -0
- package/dist/cypress/failure-report.d.ts.map +1 -0
- package/dist/cypress/failure-report.js +14 -0
- package/dist/cypress/failure-selector.d.ts +45 -0
- package/dist/cypress/failure-selector.d.ts.map +1 -0
- package/dist/cypress/failure-selector.js +107 -0
- package/dist/cypress/measure-dom.d.ts +52 -0
- package/dist/cypress/measure-dom.d.ts.map +1 -0
- package/dist/cypress/measure-dom.js +132 -0
- package/dist/cypress/scroll-into-view.d.ts +15 -0
- package/dist/cypress/scroll-into-view.d.ts.map +1 -0
- package/dist/cypress/scroll-into-view.js +17 -0
- package/dist/cypress/task.d.ts +47 -0
- package/dist/cypress/task.d.ts.map +1 -0
- package/dist/cypress/task.js +69 -0
- package/dist/draw.d.ts +19 -0
- package/dist/draw.d.ts.map +1 -0
- package/dist/draw.js +177 -0
- package/dist/finder.d.ts +68 -0
- package/dist/finder.d.ts.map +1 -0
- package/dist/finder.js +64 -0
- package/dist/index.d.ts +32 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +40 -0
- package/dist/inventory.d.ts +33 -0
- package/dist/inventory.d.ts.map +1 -0
- package/dist/inventory.js +88 -0
- package/dist/measure.d.ts +11 -0
- package/dist/measure.d.ts.map +1 -0
- package/dist/measure.js +145 -0
- package/dist/pipeline.d.ts +60 -0
- package/dist/pipeline.d.ts.map +1 -0
- package/dist/pipeline.js +115 -0
- package/dist/types.d.ts +115 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +1 -0
- package/package.json +113 -0
- package/skills/annotate-bug/SKILL.md +121 -0
- package/skills/cypress-annotate/SKILL.md +154 -0
- package/src/browser/collect-elements.js +158 -0
- package/src/browser/measure-target.js +69 -0
package/package.json
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "cypress-annotate",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Annotate Cypress screenshots and failed-test runs with pixel-accurate boxes, pointing at exactly what broke.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"cypress",
|
|
7
|
+
"cypress-plugin",
|
|
8
|
+
"cypress-screenshot",
|
|
9
|
+
"screenshot",
|
|
10
|
+
"annotate",
|
|
11
|
+
"annotation",
|
|
12
|
+
"test-failure",
|
|
13
|
+
"failed-test",
|
|
14
|
+
"debugging",
|
|
15
|
+
"e2e",
|
|
16
|
+
"e2e-testing",
|
|
17
|
+
"visual-testing",
|
|
18
|
+
"test-reporting",
|
|
19
|
+
"ci",
|
|
20
|
+
"cypress-cloud",
|
|
21
|
+
"bounding-box",
|
|
22
|
+
"pixel-accurate",
|
|
23
|
+
"playwright",
|
|
24
|
+
"ai",
|
|
25
|
+
"llm",
|
|
26
|
+
"claude",
|
|
27
|
+
"agent"
|
|
28
|
+
],
|
|
29
|
+
"license": "MIT",
|
|
30
|
+
"author": "bidemiajala",
|
|
31
|
+
"repository": {
|
|
32
|
+
"type": "git",
|
|
33
|
+
"url": "git+https://github.com/bidemiajala/cypress-annotate.git"
|
|
34
|
+
},
|
|
35
|
+
"bugs": {
|
|
36
|
+
"url": "https://github.com/bidemiajala/cypress-annotate/issues"
|
|
37
|
+
},
|
|
38
|
+
"homepage": "https://github.com/bidemiajala/cypress-annotate#readme",
|
|
39
|
+
"engines": {
|
|
40
|
+
"node": ">=20"
|
|
41
|
+
},
|
|
42
|
+
"type": "module",
|
|
43
|
+
"main": "dist/index.js",
|
|
44
|
+
"types": "dist/index.d.ts",
|
|
45
|
+
"exports": {
|
|
46
|
+
".": {
|
|
47
|
+
"types": "./dist/index.d.ts",
|
|
48
|
+
"import": "./dist/index.js"
|
|
49
|
+
},
|
|
50
|
+
"./reasoner": {
|
|
51
|
+
"types": "./dist/claude-reasoner.d.ts",
|
|
52
|
+
"import": "./dist/claude-reasoner.js"
|
|
53
|
+
},
|
|
54
|
+
"./cypress/*": {
|
|
55
|
+
"types": "./dist/cypress/*.d.ts",
|
|
56
|
+
"import": "./dist/cypress/*.js"
|
|
57
|
+
}
|
|
58
|
+
},
|
|
59
|
+
"files": [
|
|
60
|
+
"dist",
|
|
61
|
+
"src/browser",
|
|
62
|
+
"skills",
|
|
63
|
+
"DOCS",
|
|
64
|
+
"AGENTS.md",
|
|
65
|
+
"README.md",
|
|
66
|
+
"LICENSE"
|
|
67
|
+
],
|
|
68
|
+
"scripts": {
|
|
69
|
+
"build": "tsc -p tsconfig.build.json && node scripts/copy-browser-assets.js",
|
|
70
|
+
"prepare": "npm run build",
|
|
71
|
+
"annotate": "tsx src/cli.ts",
|
|
72
|
+
"verify": "tsx scripts/verify.ts",
|
|
73
|
+
"verify:image": "tsx scripts/verify-image.ts",
|
|
74
|
+
"annotate-shot": "tsx scripts/annotate-shot.ts",
|
|
75
|
+
"test:reasoner": "tsx scripts/test-reasoner.ts",
|
|
76
|
+
"test:failure-selector": "tsx scripts/test-failure-selector.ts",
|
|
77
|
+
"test:svg-escaping": "tsx scripts/test-svg-escaping.ts",
|
|
78
|
+
"test:cypress": "tsx scripts/run-cypress.ts run --e2e --spec cypress/e2e/annotate.cy.ts",
|
|
79
|
+
"test:cypress-failures": "tsx scripts/test-cypress-failures.ts",
|
|
80
|
+
"explain-failures": "tsx scripts/explain-failures.ts",
|
|
81
|
+
"cypress:open": "tsx scripts/run-cypress.ts open",
|
|
82
|
+
"find-bugs": "tsx scripts/find-bugs.ts",
|
|
83
|
+
"demo": "tsx scripts/find-bugs.ts --url fixtures/buggy-checkout.html --replay fixtures/buggy-checkout.expected.json --out-dir out/bugs",
|
|
84
|
+
"typecheck": "tsc --noEmit"
|
|
85
|
+
},
|
|
86
|
+
"dependencies": {
|
|
87
|
+
"sharp": "^0.35.4"
|
|
88
|
+
},
|
|
89
|
+
"peerDependencies": {
|
|
90
|
+
"@anthropic-ai/sdk": "^0.120.0",
|
|
91
|
+
"cypress": ">=13",
|
|
92
|
+
"playwright": "^1.56.1"
|
|
93
|
+
},
|
|
94
|
+
"peerDependenciesMeta": {
|
|
95
|
+
"@anthropic-ai/sdk": {
|
|
96
|
+
"optional": true
|
|
97
|
+
},
|
|
98
|
+
"cypress": {
|
|
99
|
+
"optional": true
|
|
100
|
+
},
|
|
101
|
+
"playwright": {
|
|
102
|
+
"optional": true
|
|
103
|
+
}
|
|
104
|
+
},
|
|
105
|
+
"devDependencies": {
|
|
106
|
+
"@anthropic-ai/sdk": "^0.120.0",
|
|
107
|
+
"@types/node": "^24.10.1",
|
|
108
|
+
"cypress": "^15.19.0",
|
|
109
|
+
"playwright": "^1.56.1",
|
|
110
|
+
"tsx": "^4.20.7",
|
|
111
|
+
"typescript": "^5.9.3"
|
|
112
|
+
}
|
|
113
|
+
}
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: annotate-bug
|
|
3
|
+
description: Draw an accurate box on a screenshot of the live page to show exactly where a visual bug is. Use after finding a layout or rendering defect during browser testing, when the bug report needs to point at a specific element rather than attach a raw screenshot. Works with whichever browser MCP backend is connected - Playwright MCP or Chrome DevTools MCP.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Annotating a bug on a live page
|
|
7
|
+
|
|
8
|
+
Turns "the Apply button escapes its card" into a screenshot with a box drawn
|
|
9
|
+
around that exact element.
|
|
10
|
+
|
|
11
|
+
This skill does **not** open a browser. It annotates a screenshot that the
|
|
12
|
+
browser backend already connected to this session has captured. That matters:
|
|
13
|
+
the live session is the one that is logged in, and a separately launched browser
|
|
14
|
+
would land on the SSO login page instead of the page under test.
|
|
15
|
+
|
|
16
|
+
## Setup
|
|
17
|
+
|
|
18
|
+
Set `ANNOTATE_REPO` to wherever the tool is checked out (it needs
|
|
19
|
+
`npm install` once):
|
|
20
|
+
|
|
21
|
+
```
|
|
22
|
+
ANNOTATE_REPO=/path/to/cypress-annotate
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## The protocol
|
|
26
|
+
|
|
27
|
+
Four steps, in this order. The ordering is the whole discipline: a rectangle is
|
|
28
|
+
only valid for the scroll position it was measured at.
|
|
29
|
+
|
|
30
|
+
### 1. Choose the element
|
|
31
|
+
|
|
32
|
+
Pick the single element that *is* wrong - not its container, and not the element
|
|
33
|
+
it collides with. If a page snapshot gave you an element ref, resolve it to a CSS
|
|
34
|
+
selector; prefer `#id` or `[data-testid=…]` over a structural path.
|
|
35
|
+
|
|
36
|
+
### 2. Measure it
|
|
37
|
+
|
|
38
|
+
Read `$ANNOTATE_REPO/src/browser/measure-target.js`, replace the `SELECTORS`
|
|
39
|
+
line with your selector(s), and evaluate the whole function in the page. Save the
|
|
40
|
+
result to a file.
|
|
41
|
+
|
|
42
|
+
**Playwright MCP:**
|
|
43
|
+
```
|
|
44
|
+
browser_evaluate({ function: "<the edited snippet>", filename: "/abs/path/measure.json" })
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
**Chrome DevTools MCP:**
|
|
48
|
+
```
|
|
49
|
+
evaluate_script({ pageId: <id>, function: "<the edited snippet>", filePath: "/abs/path/measure.json" })
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Check the result: each target has `found: true` and a `rect`. If `found` is
|
|
53
|
+
false, the selector is wrong - fix it rather than proceeding, or fall back to a
|
|
54
|
+
region (below). If `matchCount` is above 1, the selector is ambiguous and the
|
|
55
|
+
first match gets annotated, which may not be the one you mean.
|
|
56
|
+
|
|
57
|
+
### 3. Screenshot immediately
|
|
58
|
+
|
|
59
|
+
Take the screenshot **without navigating, scrolling, clicking, or waiting for a
|
|
60
|
+
re-render in between**. Anything that moves the page invalidates the rectangles
|
|
61
|
+
from step 2 and the box will be drawn in the wrong place.
|
|
62
|
+
|
|
63
|
+
**Playwright MCP:**
|
|
64
|
+
```
|
|
65
|
+
browser_take_screenshot({ filename: "/abs/path/shot.png" })
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
**Chrome DevTools MCP:**
|
|
69
|
+
```
|
|
70
|
+
take_screenshot({ pageId: <id>, filePath: "/abs/path/shot.png", format: "png" })
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Viewport capture is the default and is what you want. If you pass `fullPage`,
|
|
74
|
+
pass `--capture fullPage` in step 4 as well, or every box below the fold will be
|
|
75
|
+
misplaced.
|
|
76
|
+
|
|
77
|
+
### 4. Draw the box
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
cd $ANNOTATE_REPO && npm run annotate-shot -- \
|
|
81
|
+
--image /abs/path/shot.png \
|
|
82
|
+
--measurement /abs/path/measure.json \
|
|
83
|
+
--label "Apply button escapes its card" \
|
|
84
|
+
--out /abs/path/annotated.png
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
One `--label` per target, in the same order as `SELECTORS`. Useful extras:
|
|
88
|
+
|
|
89
|
+
- `--crop` - close-up of the element with the rest dimmed. Best for a ticket.
|
|
90
|
+
- `--capture fullPage` - required if the screenshot was a full-page capture.
|
|
91
|
+
- `--shape arrow` - point at it instead of boxing it.
|
|
92
|
+
- `--color '#FF6A00'` - e.g. colour by severity.
|
|
93
|
+
|
|
94
|
+
Then attach `annotated.png` to the report and say what is wrong in words as well.
|
|
95
|
+
|
|
96
|
+
## When there is no element to point at
|
|
97
|
+
|
|
98
|
+
If the defect is *absent* content - blank space where something should render -
|
|
99
|
+
there is no selector to measure. Skip step 2 and give a rectangle as percentages
|
|
100
|
+
of the viewport:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
npm run annotate-shot -- --image shot.png --region 10,50,30,8 \
|
|
104
|
+
--label "Delivery estimate missing" --out annotated.png
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
`--region` is `x,y,width,height` in percent. Use it only as a fallback: a
|
|
108
|
+
selector is measured, a region is guessed.
|
|
109
|
+
|
|
110
|
+
## Checks worth reading
|
|
111
|
+
|
|
112
|
+
The command prints warnings. Two are worth acting on:
|
|
113
|
+
|
|
114
|
+
- *"matched N elements; annotated the first"* - the selector is ambiguous. Make
|
|
115
|
+
it specific and re-run.
|
|
116
|
+
- *"the image was probably rescaled"* - not a problem. Both backends can resize
|
|
117
|
+
screenshots, so the true scale is measured from the image rather than trusted
|
|
118
|
+
from `devicePixelRatio`. The box is still correct.
|
|
119
|
+
|
|
120
|
+
If the box lands in the wrong place, the cause is almost always that the page
|
|
121
|
+
moved between steps 2 and 3. Redo both, back to back.
|
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cypress-annotate
|
|
3
|
+
description: Add pixel-accurate annotated screenshots to a Cypress suite. Use when someone wants a box drawn on what failed in a Cypress screenshot, wants failed tests to annotate themselves, asks why a Cypress screenshot is hard to read, or asks how to attach a visual to a bug ticket from an e2e run. Covers cy.annotate() and automatic failure capture.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# cypress-annotate
|
|
7
|
+
|
|
8
|
+
Draws a box on exactly what's wrong in a Cypress screenshot. Two ways to use it,
|
|
9
|
+
and neither calls an LLM.
|
|
10
|
+
|
|
11
|
+
## Setup
|
|
12
|
+
|
|
13
|
+
Three files change. All three are required for `cy.annotate()`.
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm install cypress-annotate
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
// cypress.config.ts
|
|
21
|
+
import { defineConfig } from 'cypress';
|
|
22
|
+
import { registerAnnotateTasks } from 'cypress-annotate/cypress/task';
|
|
23
|
+
|
|
24
|
+
export default defineConfig({
|
|
25
|
+
e2e: {
|
|
26
|
+
setupNodeEvents(on) {
|
|
27
|
+
registerAnnotateTasks(on);
|
|
28
|
+
},
|
|
29
|
+
},
|
|
30
|
+
});
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
// cypress/support/e2e.ts
|
|
35
|
+
import 'cypress-annotate/cypress/commands';
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
The task must be registered in `setupNodeEvents` because the measuring happens in
|
|
39
|
+
the browser and the image compositing happens in Node. Registering only the
|
|
40
|
+
command gives a "task not registered" failure at run time.
|
|
41
|
+
|
|
42
|
+
## Annotating a known problem
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
cy.annotate('#promo-apply', { label: 'Apply button escapes its card' });
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Several targets, one label each, in order:
|
|
49
|
+
|
|
50
|
+
```ts
|
|
51
|
+
cy.annotate(['#promo-apply', '#order-ref'], {
|
|
52
|
+
label: ['Escapes its card', 'Overflows'],
|
|
53
|
+
});
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Crop tight with the rest dimmed, which is what to use for a ticket attachment:
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
cy.annotate('#promo-apply', { label: 'Escapes its card', crop: true, cropPadding: 80 });
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
It overwrites the screenshot Cypress just recorded, so the annotated image is
|
|
63
|
+
what lands in `cypress/screenshots/`, in reports, and in CI artifacts. There is
|
|
64
|
+
no second file to collect.
|
|
65
|
+
|
|
66
|
+
It yields the result, so a test can assert on where the box landed:
|
|
67
|
+
|
|
68
|
+
```ts
|
|
69
|
+
cy.annotate('#grand-total-value', { label: 'Wrong total' }).then((result) => {
|
|
70
|
+
expect(result.warnings).to.be.empty;
|
|
71
|
+
});
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### Options
|
|
75
|
+
|
|
76
|
+
| Option | Default | Effect |
|
|
77
|
+
| --- | --- | --- |
|
|
78
|
+
| `label` | none | Box text. One string, or one per selector in order. |
|
|
79
|
+
| `name` | slug of first selector | Screenshot filename. |
|
|
80
|
+
| `crop` | `false` | Crop to the element, dim everything else. |
|
|
81
|
+
| `cropPadding` | pipeline default | CSS px of context kept around the crop. |
|
|
82
|
+
| `shape` | `box` | Shape drawn around the target. |
|
|
83
|
+
| `style` | none | Colours, stroke width, label colour, dim strength. |
|
|
84
|
+
| `scrollIntoView` | `true` | Scroll the first target in, but only if needed. |
|
|
85
|
+
| `scrollOffset` | `120` | CSS px left above the element when scrolling. |
|
|
86
|
+
| `keepRaw` | `false` | Keep the un-annotated image too. |
|
|
87
|
+
| `fullPage` | `false` | Whole document. Avoid it, see Traps. |
|
|
88
|
+
|
|
89
|
+
Result fields: `outPath`, `rawPath`, `width`, `height`, `scale`, `drawnRects`,
|
|
90
|
+
`warnings`.
|
|
91
|
+
|
|
92
|
+
## Annotating every failed test
|
|
93
|
+
|
|
94
|
+
This one needs no per-test code. Every failure annotates itself, labelled from
|
|
95
|
+
the assertion's own expected and actual values.
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
// cypress.config.ts
|
|
99
|
+
export default defineConfig({
|
|
100
|
+
screenshotOnRunFailure: false,
|
|
101
|
+
// ...
|
|
102
|
+
});
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
```ts
|
|
106
|
+
// cypress/support/e2e.ts
|
|
107
|
+
import { registerFailureCapture } from 'cypress-annotate/cypress/failure-hook';
|
|
108
|
+
|
|
109
|
+
registerFailureCapture();
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
`screenshotOnRunFailure: false` is required, not optional. Leave it on and
|
|
113
|
+
Cypress's automatic screenshot races this hook's screenshot, which makes it
|
|
114
|
+
ambiguous which image the DOM measurement matches.
|
|
115
|
+
|
|
116
|
+
Each failure produces an annotated screenshot plus one record in
|
|
117
|
+
`out/cypress/failures.json` carrying the spec and test name, the recovered
|
|
118
|
+
selector and where it came from, expected and actual, the label, image paths,
|
|
119
|
+
`drawnRect`, page metrics, and warnings.
|
|
120
|
+
|
|
121
|
+
Where no selector can be recovered, such as an existence check or a
|
|
122
|
+
`cy.contains()` chain, the failure still gets a screenshot plus a live inventory
|
|
123
|
+
of candidate elements, since the browser session is gone by the time anyone reads
|
|
124
|
+
the report.
|
|
125
|
+
|
|
126
|
+
## Traps
|
|
127
|
+
|
|
128
|
+
**Don't use `fullPage: true` casually.** Cypress builds a full-page screenshot by
|
|
129
|
+
scrolling and stitching, which paints `position: fixed` and `sticky` elements
|
|
130
|
+
several times in one image.
|
|
131
|
+
|
|
132
|
+
**Don't call `cy.scrollIntoView()` before annotating.** It always scrolls, even
|
|
133
|
+
when the element is already visible, which can push the target under a fixed
|
|
134
|
+
header. The command already handles this, measuring first and only scrolling when
|
|
135
|
+
genuinely needed.
|
|
136
|
+
|
|
137
|
+
**Don't insert anything between measuring and the screenshot.** No navigation,
|
|
138
|
+
scroll, or click. A rectangle is only valid for the scroll position it was
|
|
139
|
+
measured at. Using `cy.annotate()` rather than hand-rolling this is the point.
|
|
140
|
+
|
|
141
|
+
**Exact-colour assertions fail on macOS Electron.** Its capture applies a
|
|
142
|
+
colour-profile shift, so `#FF00E4` comes back as `rgb(234,51,221)`. Sample the
|
|
143
|
+
colour from the image rather than trusting the stylesheet.
|
|
144
|
+
|
|
145
|
+
**"bad option: --no-sandbox" on start** means something set
|
|
146
|
+
`ELECTRON_RUN_AS_NODE=1`, which VS Code's extension host does. Unset it before
|
|
147
|
+
running Cypress.
|
|
148
|
+
|
|
149
|
+
## What this does not do
|
|
150
|
+
|
|
151
|
+
No LLM is involved in either path above, and no API key is needed. The package
|
|
152
|
+
also ships an optional Claude-based reasoning layer and a Playwright pipeline for
|
|
153
|
+
finding bugs you haven't identified yet. Those are separate entry points that
|
|
154
|
+
install nothing by default. See `DOCS/pipeline.md` in the package.
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
// This file is read as text and evaluated inside the page - it is never
|
|
2
|
+
// imported or bundled. Keeping it out of the TypeScript build is deliberate:
|
|
3
|
+
// esbuild's keepNames transform injects a `__name` helper into any function it
|
|
4
|
+
// compiles, and that helper does not exist in the browser, so a serialized
|
|
5
|
+
// TypeScript function throws `__name is not defined` on evaluation.
|
|
6
|
+
//
|
|
7
|
+
// The whole file is therefore a single arrow-function expression.
|
|
8
|
+
//
|
|
9
|
+
// Tags every candidate element with a ref attribute and returns a description
|
|
10
|
+
// of it. Tagging rather than deriving a selector afterwards is deliberate: a
|
|
11
|
+
// selector we injected always resolves, whereas a path built from classes can
|
|
12
|
+
// be invalidated by anything that re-renders between measuring and annotating.
|
|
13
|
+
|
|
14
|
+
(function (options) {
|
|
15
|
+
var prefix = options.prefix;
|
|
16
|
+
var refAttr = options.refAttr;
|
|
17
|
+
var minSize = options.minSize;
|
|
18
|
+
var viewportOnly = options.viewportOnly;
|
|
19
|
+
|
|
20
|
+
var INTERACTIVE = ['a', 'button', 'input', 'select', 'textarea', 'label', 'summary', 'option'];
|
|
21
|
+
var STRUCTURAL = ['header', 'nav', 'main', 'footer', 'aside', 'form', 'table', 'img', 'svg', 'video', 'dialog'];
|
|
22
|
+
var HEADING = /^h[1-6]$/;
|
|
23
|
+
var testAttrs = ['data-testid', 'data-test-id', 'data-test', 'data-cy', 'data-qa'];
|
|
24
|
+
|
|
25
|
+
function readableSelector(el) {
|
|
26
|
+
// Prefer whatever a developer would actually paste into devtools.
|
|
27
|
+
var id = el.getAttribute('id');
|
|
28
|
+
if (id && /^[A-Za-z][\w-]*$/.test(id) && el.ownerDocument.querySelectorAll('#' + id).length === 1) {
|
|
29
|
+
return '#' + id;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
for (var i = 0; i < testAttrs.length; i++) {
|
|
33
|
+
var value = el.getAttribute(testAttrs[i]);
|
|
34
|
+
if (value) {
|
|
35
|
+
var candidate = '[' + testAttrs[i] + '="' + value + '"]';
|
|
36
|
+
if (el.ownerDocument.querySelectorAll(candidate).length === 1) return candidate;
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
var parts = [];
|
|
41
|
+
var node = el;
|
|
42
|
+
for (var depth = 0; node && depth < 4; depth++) {
|
|
43
|
+
var tag = node.tagName.toLowerCase();
|
|
44
|
+
if (tag === 'body' || tag === 'html') break;
|
|
45
|
+
|
|
46
|
+
var nodeId = node.getAttribute('id');
|
|
47
|
+
if (nodeId && /^[A-Za-z][\w-]*$/.test(nodeId)) {
|
|
48
|
+
parts.unshift('#' + nodeId);
|
|
49
|
+
break;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
var parent = node.parentElement;
|
|
53
|
+
var part = tag;
|
|
54
|
+
if (parent) {
|
|
55
|
+
var siblings = [];
|
|
56
|
+
for (var c = 0; c < parent.children.length; c++) {
|
|
57
|
+
if (parent.children[c].tagName === node.tagName) siblings.push(parent.children[c]);
|
|
58
|
+
}
|
|
59
|
+
if (siblings.length > 1) part += ':nth-of-type(' + (siblings.indexOf(node) + 1) + ')';
|
|
60
|
+
}
|
|
61
|
+
parts.unshift(part);
|
|
62
|
+
|
|
63
|
+
var joined = parts.join(' > ');
|
|
64
|
+
try {
|
|
65
|
+
if (el.ownerDocument.querySelectorAll(joined).length === 1) return joined;
|
|
66
|
+
} catch (e) {
|
|
67
|
+
// An unusual tag name can produce an invalid selector; keep walking.
|
|
68
|
+
}
|
|
69
|
+
node = parent;
|
|
70
|
+
}
|
|
71
|
+
return parts.join(' > ') || el.tagName.toLowerCase();
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
function accessibleName(el) {
|
|
75
|
+
var aria = el.getAttribute('aria-label');
|
|
76
|
+
if (aria) return aria.trim();
|
|
77
|
+
var alt = el.getAttribute('alt');
|
|
78
|
+
if (alt) return alt.trim();
|
|
79
|
+
var placeholder = el.getAttribute('placeholder');
|
|
80
|
+
if (placeholder) return 'placeholder: ' + placeholder.trim();
|
|
81
|
+
if (el.tagName === 'INPUT' && typeof el.value === 'string' && el.value) {
|
|
82
|
+
return 'value: ' + el.value.trim();
|
|
83
|
+
}
|
|
84
|
+
return (el.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 80);
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
// An element a developer deliberately named is worth listing even when it is
|
|
88
|
+
// just a wrapper - a misaligned or overflowing container is exactly the kind
|
|
89
|
+
// of target whose children, not itself, carry the text.
|
|
90
|
+
function hasStableName(el) {
|
|
91
|
+
if (el.hasAttribute('id')) return true;
|
|
92
|
+
for (var i = 0; i < testAttrs.length; i++) {
|
|
93
|
+
if (el.hasAttribute(testAttrs[i])) return true;
|
|
94
|
+
}
|
|
95
|
+
return false;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
// Text-bearing leaf: has its own text but no child element that also has text.
|
|
99
|
+
function isTextLeaf(el) {
|
|
100
|
+
if (!(el.textContent || '').trim()) return false;
|
|
101
|
+
for (var i = 0; i < el.children.length; i++) {
|
|
102
|
+
if ((el.children[i].textContent || '').trim()) return false;
|
|
103
|
+
}
|
|
104
|
+
return true;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
// Clear handles left by an earlier pass. Counters restart at 1 each time, so
|
|
108
|
+
// without this a stale e5 from a previous scroll position still matches
|
|
109
|
+
// [data-annot-ref="e5"] and the annotation can land on the wrong element.
|
|
110
|
+
var stale = document.querySelectorAll('[' + refAttr + ']');
|
|
111
|
+
for (var s = 0; s < stale.length; s++) stale[s].removeAttribute(refAttr);
|
|
112
|
+
|
|
113
|
+
var results = [];
|
|
114
|
+
var counter = 0;
|
|
115
|
+
var all = document.querySelectorAll('*');
|
|
116
|
+
|
|
117
|
+
for (var i = 0; i < all.length; i++) {
|
|
118
|
+
var el = all[i];
|
|
119
|
+
var tag = el.tagName.toLowerCase();
|
|
120
|
+
if (tag === 'script' || tag === 'style' || tag === 'meta' || tag === 'link') continue;
|
|
121
|
+
|
|
122
|
+
var style = getComputedStyle(el);
|
|
123
|
+
if (style.visibility === 'hidden' || style.display === 'none') continue;
|
|
124
|
+
if (parseFloat(style.opacity) < 0.05) continue;
|
|
125
|
+
|
|
126
|
+
var rect = el.getBoundingClientRect();
|
|
127
|
+
if (rect.width < minSize || rect.height < minSize) continue;
|
|
128
|
+
|
|
129
|
+
var intersects =
|
|
130
|
+
rect.bottom > 0 && rect.right > 0 &&
|
|
131
|
+
rect.top < window.innerHeight && rect.left < window.innerWidth;
|
|
132
|
+
if (viewportOnly && !intersects) continue;
|
|
133
|
+
|
|
134
|
+
var interesting =
|
|
135
|
+
INTERACTIVE.indexOf(tag) !== -1 ||
|
|
136
|
+
STRUCTURAL.indexOf(tag) !== -1 ||
|
|
137
|
+
HEADING.test(tag) ||
|
|
138
|
+
el.hasAttribute('role') ||
|
|
139
|
+
hasStableName(el) ||
|
|
140
|
+
isTextLeaf(el);
|
|
141
|
+
if (!interesting) continue;
|
|
142
|
+
|
|
143
|
+
var ref = prefix + ++counter;
|
|
144
|
+
el.setAttribute(refAttr, ref);
|
|
145
|
+
|
|
146
|
+
results.push({
|
|
147
|
+
ref: ref,
|
|
148
|
+
reportSelector: readableSelector(el),
|
|
149
|
+
tag: tag,
|
|
150
|
+
role: el.getAttribute('role'),
|
|
151
|
+
name: accessibleName(el),
|
|
152
|
+
rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
|
|
153
|
+
inViewport: intersects,
|
|
154
|
+
});
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
return results;
|
|
158
|
+
})
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
// Paste this into whichever browser MCP is live, as the evaluate function:
|
|
2
|
+
//
|
|
3
|
+
// Playwright MCP browser_evaluate({ function: "<this>", filename: "measure.json" })
|
|
4
|
+
// Chrome DevTools evaluate_script({ pageId, function: "<this>", filePath: "measure.json" })
|
|
5
|
+
//
|
|
6
|
+
// Edit the SELECTORS line, and nothing else. The result is the exact JSON that
|
|
7
|
+
// `annotate-shot --measurement` expects.
|
|
8
|
+
//
|
|
9
|
+
// It deliberately does not scroll, click, or change anything: every rectangle it
|
|
10
|
+
// returns is only valid for the scroll position the page is in right now, so
|
|
11
|
+
// the screenshot must be taken immediately after this runs, with no navigation
|
|
12
|
+
// in between.
|
|
13
|
+
|
|
14
|
+
() => {
|
|
15
|
+
const SELECTORS = ['#place-order'];
|
|
16
|
+
|
|
17
|
+
const doc = document.documentElement;
|
|
18
|
+
const body = document.body;
|
|
19
|
+
|
|
20
|
+
const metrics = {
|
|
21
|
+
devicePixelRatio: window.devicePixelRatio,
|
|
22
|
+
scrollX: window.scrollX,
|
|
23
|
+
scrollY: window.scrollY,
|
|
24
|
+
// innerWidth/Height rather than documentElement.clientWidth/Height: on a
|
|
25
|
+
// page with no doctype (quirks mode) the root element reports the content
|
|
26
|
+
// size, not the viewport.
|
|
27
|
+
viewportWidth: window.innerWidth,
|
|
28
|
+
viewportHeight: window.innerHeight,
|
|
29
|
+
documentWidth: Math.max(doc.scrollWidth, body ? body.scrollWidth : 0),
|
|
30
|
+
documentHeight: Math.max(doc.scrollHeight, body ? body.scrollHeight : 0),
|
|
31
|
+
};
|
|
32
|
+
|
|
33
|
+
const targets = SELECTORS.map((selector) => {
|
|
34
|
+
let matches;
|
|
35
|
+
try {
|
|
36
|
+
matches = document.querySelectorAll(selector);
|
|
37
|
+
} catch (e) {
|
|
38
|
+
return { selector, found: false, error: 'invalid selector: ' + e.message };
|
|
39
|
+
}
|
|
40
|
+
if (matches.length === 0) return { selector, found: false, error: 'no element matched' };
|
|
41
|
+
|
|
42
|
+
const el = matches[0];
|
|
43
|
+
const r = el.getBoundingClientRect();
|
|
44
|
+
|
|
45
|
+
// An element inside a fixed subtree does not move with document scroll, so
|
|
46
|
+
// it has no meaningful document-space position.
|
|
47
|
+
let isFixed = false;
|
|
48
|
+
for (let node = el; node; node = node.parentElement) {
|
|
49
|
+
if (getComputedStyle(node).position === 'fixed') {
|
|
50
|
+
isFixed = true;
|
|
51
|
+
break;
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
return {
|
|
56
|
+
selector,
|
|
57
|
+
found: true,
|
|
58
|
+
matchCount: matches.length,
|
|
59
|
+
tag: el.tagName.toLowerCase(),
|
|
60
|
+
text: (el.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 80),
|
|
61
|
+
isFixed,
|
|
62
|
+
rect: { x: r.x, y: r.y, width: r.width, height: r.height },
|
|
63
|
+
inViewport:
|
|
64
|
+
r.bottom > 0 && r.right > 0 && r.top < window.innerHeight && r.left < window.innerWidth,
|
|
65
|
+
};
|
|
66
|
+
});
|
|
67
|
+
|
|
68
|
+
return { metrics, targets };
|
|
69
|
+
}
|