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.
Files changed (68) hide show
  1. package/AGENTS.md +65 -0
  2. package/DOCS/pipeline.md +258 -0
  3. package/LICENSE +21 -0
  4. package/README.md +360 -0
  5. package/dist/annotate-image.d.ts +60 -0
  6. package/dist/annotate-image.d.ts.map +1 -0
  7. package/dist/annotate-image.js +160 -0
  8. package/dist/annotate.d.ts +9 -0
  9. package/dist/annotate.d.ts.map +1 -0
  10. package/dist/annotate.js +82 -0
  11. package/dist/browser/collect-elements.js +158 -0
  12. package/dist/browser/measure-target.js +69 -0
  13. package/dist/claude-reasoner.d.ts +17 -0
  14. package/dist/claude-reasoner.d.ts.map +1 -0
  15. package/dist/claude-reasoner.js +192 -0
  16. package/dist/cli.d.ts +2 -0
  17. package/dist/cli.d.ts.map +1 -0
  18. package/dist/cli.js +74 -0
  19. package/dist/cypress/commands.d.ts +50 -0
  20. package/dist/cypress/commands.d.ts.map +1 -0
  21. package/dist/cypress/commands.js +68 -0
  22. package/dist/cypress/failure-explainer.d.ts +45 -0
  23. package/dist/cypress/failure-explainer.d.ts.map +1 -0
  24. package/dist/cypress/failure-explainer.js +123 -0
  25. package/dist/cypress/failure-hook.d.ts +30 -0
  26. package/dist/cypress/failure-hook.d.ts.map +1 -0
  27. package/dist/cypress/failure-hook.js +148 -0
  28. package/dist/cypress/failure-report.d.ts +41 -0
  29. package/dist/cypress/failure-report.d.ts.map +1 -0
  30. package/dist/cypress/failure-report.js +14 -0
  31. package/dist/cypress/failure-selector.d.ts +45 -0
  32. package/dist/cypress/failure-selector.d.ts.map +1 -0
  33. package/dist/cypress/failure-selector.js +107 -0
  34. package/dist/cypress/measure-dom.d.ts +52 -0
  35. package/dist/cypress/measure-dom.d.ts.map +1 -0
  36. package/dist/cypress/measure-dom.js +132 -0
  37. package/dist/cypress/scroll-into-view.d.ts +15 -0
  38. package/dist/cypress/scroll-into-view.d.ts.map +1 -0
  39. package/dist/cypress/scroll-into-view.js +17 -0
  40. package/dist/cypress/task.d.ts +47 -0
  41. package/dist/cypress/task.d.ts.map +1 -0
  42. package/dist/cypress/task.js +69 -0
  43. package/dist/draw.d.ts +19 -0
  44. package/dist/draw.d.ts.map +1 -0
  45. package/dist/draw.js +177 -0
  46. package/dist/finder.d.ts +68 -0
  47. package/dist/finder.d.ts.map +1 -0
  48. package/dist/finder.js +64 -0
  49. package/dist/index.d.ts +32 -0
  50. package/dist/index.d.ts.map +1 -0
  51. package/dist/index.js +40 -0
  52. package/dist/inventory.d.ts +33 -0
  53. package/dist/inventory.d.ts.map +1 -0
  54. package/dist/inventory.js +88 -0
  55. package/dist/measure.d.ts +11 -0
  56. package/dist/measure.d.ts.map +1 -0
  57. package/dist/measure.js +145 -0
  58. package/dist/pipeline.d.ts +60 -0
  59. package/dist/pipeline.d.ts.map +1 -0
  60. package/dist/pipeline.js +115 -0
  61. package/dist/types.d.ts +115 -0
  62. package/dist/types.d.ts.map +1 -0
  63. package/dist/types.js +1 -0
  64. package/package.json +113 -0
  65. package/skills/annotate-bug/SKILL.md +121 -0
  66. package/skills/cypress-annotate/SKILL.md +154 -0
  67. package/src/browser/collect-elements.js +158 -0
  68. package/src/browser/measure-target.js +69 -0
@@ -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
+ }
@@ -0,0 +1,17 @@
1
+ import Anthropic from '@anthropic-ai/sdk';
2
+ import type { BugFinding, Reasoner, ReasonerInput } from './finder.js';
3
+ export interface ClaudeReasonerOptions {
4
+ model?: string;
5
+ maxTokens?: number;
6
+ effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
7
+ client?: Anthropic;
8
+ }
9
+ export declare class ClaudeReasoner implements Reasoner {
10
+ private readonly client;
11
+ private readonly model;
12
+ private readonly maxTokens;
13
+ private readonly effort;
14
+ constructor(options?: ClaudeReasonerOptions);
15
+ propose(input: ReasonerInput): Promise<BugFinding[]>;
16
+ }
17
+ //# sourceMappingURL=claude-reasoner.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"claude-reasoner.d.ts","sourceRoot":"","sources":["../src/claude-reasoner.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAE1C,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,aAAa,EAAY,MAAM,aAAa,CAAC;AA2FjF,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;IACrD,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAED,qBAAa,cAAe,YAAW,QAAQ;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8C;gBAEzD,OAAO,GAAE,qBAA0B;IAOzC,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;CAkE3D"}
@@ -0,0 +1,192 @@
1
+ import Anthropic from '@anthropic-ai/sdk';
2
+ import { renderInventory } from './inventory.js';
3
+ /**
4
+ * Split out from finder.ts on purpose: this is the only file in the package
5
+ * with a real (non-type-only) import of `@anthropic-ai/sdk`. finder.ts's other
6
+ * exports (findingsToAnnotations, gatherReasonerInput, ReplayReasoner, ...) do
7
+ * not need the SDK at all, and index.ts re-exports them from its root barrel -
8
+ * if ClaudeReasoner lived in the same file, importing anything from that
9
+ * barrel would eagerly load the SDK too, since ES module imports evaluate the
10
+ * whole file regardless of which export you asked for. Caught by actually
11
+ * installing the built package into a scratch project and importing it with
12
+ * no SDK present, not by inspection.
13
+ */
14
+ const SEVERITIES = ['blocker', 'major', 'minor', 'cosmetic'];
15
+ const FINDING_SCHEMA = {
16
+ type: 'object',
17
+ properties: {
18
+ findings: {
19
+ type: 'array',
20
+ description: 'Every visual or functional defect found. Empty if the page looks correct.',
21
+ items: {
22
+ type: 'object',
23
+ properties: {
24
+ description: {
25
+ type: 'string',
26
+ description: 'What is wrong, in one sentence a developer could act on.',
27
+ },
28
+ evidence: {
29
+ type: 'string',
30
+ description: 'What in the screenshot or element list shows this is a defect.',
31
+ },
32
+ severity: { type: 'string', enum: SEVERITIES },
33
+ ref: {
34
+ type: ['string', 'null'],
35
+ description: 'The handle of the single element the annotation should point at, e.g. "e12". ' +
36
+ 'Null only if no listed element corresponds to the problem.',
37
+ },
38
+ region: {
39
+ type: ['object', 'null'],
40
+ description: 'Fallback used only when ref is null: the area of the viewport to box, in percentages.',
41
+ properties: {
42
+ xPct: { type: 'number' },
43
+ yPct: { type: 'number' },
44
+ widthPct: { type: 'number' },
45
+ heightPct: { type: 'number' },
46
+ },
47
+ required: ['xPct', 'yPct', 'widthPct', 'heightPct'],
48
+ additionalProperties: false,
49
+ },
50
+ },
51
+ required: ['description', 'evidence', 'severity', 'ref', 'region'],
52
+ additionalProperties: false,
53
+ },
54
+ },
55
+ },
56
+ required: ['findings'],
57
+ additionalProperties: false,
58
+ };
59
+ const SYSTEM_PROMPT = `You are doing exploratory visual testing of a web page.
60
+
61
+ You get a screenshot and a list of the page's elements. Every element has a handle
62
+ like [e12], its tag, its accessible name, and its bounding box in CSS pixels
63
+ (x,y width x height) relative to the viewport.
64
+
65
+ Report defects a developer would accept as real bugs: overlapping or clipped
66
+ content, misalignment, text overflowing its container, invisible or unreadable
67
+ text, controls positioned off-screen or outside their container, broken images,
68
+ inconsistent spacing that breaks an otherwise regular rhythm, and anything that
69
+ contradicts the ticket.
70
+
71
+ Do not report subjective styling preferences, and do not invent defects. If the
72
+ page looks correct, return an empty findings array.
73
+
74
+ For each finding, set "ref" to the handle of the single element the annotation
75
+ should point at - the element that is wrong, not its container, and not the
76
+ element it collides with. The bounding boxes in the element list are the best
77
+ evidence for geometric bugs: overlapping boxes, boxes extending past a parent,
78
+ and boxes with a zero or negative gap are all visible in the numbers.
79
+
80
+ Only set "ref" to null when no listed element corresponds to the problem - for
81
+ example whitespace where something should be. In that case fill in "region"
82
+ with the area to box, as percentages of the viewport.
83
+
84
+ Always call the report_findings tool exactly once, even when you find nothing.`;
85
+ export class ClaudeReasoner {
86
+ client;
87
+ model;
88
+ maxTokens;
89
+ effort;
90
+ constructor(options = {}) {
91
+ this.client = options.client ?? new Anthropic();
92
+ this.model = options.model ?? 'claude-opus-5';
93
+ this.maxTokens = options.maxTokens ?? 16000;
94
+ this.effort = options.effort ?? 'high';
95
+ }
96
+ async propose(input) {
97
+ const stream = this.client.messages.stream({
98
+ model: this.model,
99
+ max_tokens: this.maxTokens,
100
+ system: SYSTEM_PROMPT,
101
+ thinking: { type: 'adaptive' },
102
+ output_config: { effort: this.effort },
103
+ tools: [
104
+ {
105
+ name: 'report_findings',
106
+ description: 'Report every defect found on the page.',
107
+ input_schema: FINDING_SCHEMA,
108
+ strict: true,
109
+ },
110
+ ],
111
+ messages: [
112
+ {
113
+ role: 'user',
114
+ content: [
115
+ {
116
+ type: 'image',
117
+ source: {
118
+ type: 'base64',
119
+ media_type: 'image/png',
120
+ data: input.screenshotPng.toString('base64'),
121
+ },
122
+ },
123
+ {
124
+ type: 'text',
125
+ text: `URL: ${input.url}\n\n` +
126
+ `${describeIntent(input.ticket)}\n\n` +
127
+ `Elements on the page:\n${renderInventory(input.inventory)}`,
128
+ },
129
+ ],
130
+ },
131
+ ],
132
+ });
133
+ const message = await stream.finalMessage();
134
+ if (message.stop_reason === 'refusal') {
135
+ throw new Error(`Model declined the request (${message.stop_details?.category ?? 'unknown'}).`);
136
+ }
137
+ const call = message.content.find((block) => block.type === 'tool_use' && block.name === 'report_findings');
138
+ if (!call) {
139
+ const text = message.content
140
+ .filter((b) => b.type === 'text')
141
+ .map((b) => b.text)
142
+ .join(' ');
143
+ throw new Error(`Model did not call report_findings (stop_reason: ${message.stop_reason}). Said: ${text.slice(0, 300)}`);
144
+ }
145
+ // Tool inputs are already parsed objects, but escaping varies by model, so
146
+ // never string-match on them.
147
+ const parsed = call.input;
148
+ return normaliseFindings(parsed.findings);
149
+ }
150
+ }
151
+ /**
152
+ * With no ticket there is nothing to contradict, so the model is told to judge
153
+ * the page on its own terms rather than being handed an empty requirement it
154
+ * might try to reason against.
155
+ */
156
+ function describeIntent(ticket) {
157
+ const trimmed = ticket.trim();
158
+ return trimmed
159
+ ? `Ticket / what this page is supposed to do:\n${trimmed}`
160
+ : 'No ticket was supplied. Judge the page on its own terms: report anything that ' +
161
+ 'looks broken, misaligned, unreadable, clipped, or otherwise unintentional.';
162
+ }
163
+ function normaliseFindings(raw) {
164
+ if (!Array.isArray(raw))
165
+ return [];
166
+ const findings = [];
167
+ for (const entry of raw) {
168
+ if (typeof entry !== 'object' || entry === null)
169
+ continue;
170
+ const record = entry;
171
+ const severity = SEVERITIES.includes(record.severity)
172
+ ? record.severity
173
+ : 'minor';
174
+ findings.push({
175
+ description: String(record.description ?? '').trim(),
176
+ evidence: String(record.evidence ?? '').trim(),
177
+ severity,
178
+ ref: typeof record.ref === 'string' && record.ref ? record.ref : null,
179
+ region: isRegion(record.region) ? record.region : null,
180
+ });
181
+ }
182
+ return findings.filter((f) => f.description.length > 0);
183
+ }
184
+ function isRegion(value) {
185
+ if (typeof value !== 'object' || value === null)
186
+ return false;
187
+ const r = value;
188
+ return (typeof r.xPct === 'number' &&
189
+ typeof r.yPct === 'number' &&
190
+ typeof r.widthPct === 'number' &&
191
+ typeof r.heightPct === 'number');
192
+ }
package/dist/cli.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=cli.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}
package/dist/cli.js ADDED
@@ -0,0 +1,74 @@
1
+ import { writeFile } from 'node:fs/promises';
2
+ import { parseArgs } from 'node:util';
3
+ import { captureAnnotated } from './index.js';
4
+ const USAGE = `
5
+ Usage: npm run annotate -- --url <url> --selector <css> [options]
6
+
7
+ --url <url> Page to open (http(s):// or file://).
8
+ --selector <css> Element to annotate. Repeatable.
9
+ Use ">>>" to pierce iframes: "iframe#pay >>> .btn".
10
+ --label <text> Label for the matching --selector. Repeatable.
11
+ --out <path> Output PNG. Default: annotated.png
12
+ --mode <m> viewport | fullPage | element. Default: viewport
13
+ --shape <s> box | circle | arrow. Default: box
14
+ --color <css> Outline colour. Default: #FF3B30
15
+ --dim <0..1> Darken everything outside the annotation. Default: 0
16
+ --width <px> Viewport width, CSS px. Default: 1280
17
+ --height <px> Viewport height, CSS px. Default: 800
18
+ --dpr <n> Device scale factor. Default: 2
19
+ --crop-padding <px> Context to keep around the element in 'element' mode.
20
+ --json Print the measurement report as JSON.
21
+ `.trim();
22
+ const { values } = parseArgs({
23
+ options: {
24
+ url: { type: 'string' },
25
+ selector: { type: 'string', multiple: true, default: [] },
26
+ label: { type: 'string', multiple: true, default: [] },
27
+ out: { type: 'string', default: 'annotated.png' },
28
+ mode: { type: 'string', default: 'viewport' },
29
+ shape: { type: 'string', default: 'box' },
30
+ color: { type: 'string' },
31
+ dim: { type: 'string' },
32
+ width: { type: 'string', default: '1280' },
33
+ height: { type: 'string', default: '800' },
34
+ dpr: { type: 'string', default: '2' },
35
+ 'crop-padding': { type: 'string' },
36
+ json: { type: 'boolean', default: false },
37
+ help: { type: 'boolean', default: false },
38
+ },
39
+ allowPositionals: false,
40
+ });
41
+ if (values.help || !values.url || values.selector.length === 0) {
42
+ console.log(USAGE);
43
+ process.exit(values.help ? 0 : 1);
44
+ }
45
+ const annotations = values.selector.map((selector, i) => ({
46
+ selector: selector.includes('>>>') ? selector.split('>>>').map((s) => s.trim()) : selector,
47
+ label: values.label[i],
48
+ shape: values.shape,
49
+ }));
50
+ const result = await captureAnnotated(values.url, annotations, {
51
+ mode: values.mode,
52
+ viewport: { width: Number(values.width), height: Number(values.height) },
53
+ deviceScaleFactor: Number(values.dpr),
54
+ cropPadding: values['crop-padding'] ? Number(values['crop-padding']) : undefined,
55
+ style: {
56
+ ...(values.color ? { color: values.color } : {}),
57
+ ...(values.dim ? { dimOutside: Number(values.dim) } : {}),
58
+ },
59
+ });
60
+ await writeFile(values.out, result.image);
61
+ if (values.json) {
62
+ 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
+ }
64
+ else {
65
+ console.log(`Wrote ${values.out} (${result.width}x${result.height})`);
66
+ for (const element of result.elements) {
67
+ const r = result.drawnRects[result.elements.indexOf(element)];
68
+ console.log(` ${element.selector} -> <${element.tagName}> ` +
69
+ `css ${element.viewportRect.width.toFixed(0)}x${element.viewportRect.height.toFixed(0)} ` +
70
+ `@ image ${r ? `${r.x.toFixed(0)},${r.y.toFixed(0)}` : '?'}`);
71
+ }
72
+ for (const warning of result.warnings)
73
+ console.log(` ! ${warning}`);
74
+ }
@@ -0,0 +1,50 @@
1
+ import type { AnnotateTaskResult } from './task.js';
2
+ import type { AnnotationStyle, ShapeKind } from '../types.js';
3
+ /**
4
+ * Registers cy.annotate(). Import once from cypress/support/e2e.ts:
5
+ *
6
+ * import 'cypress-annotate/cypress/commands';
7
+ *
8
+ * The command exists mainly to enforce an ordering that is easy to get wrong by
9
+ * hand: scroll, then measure, then screenshot, with nothing in between. Every
10
+ * rectangle is only valid for the scroll position it was measured at.
11
+ */
12
+ export interface AnnotateCommandOptions {
13
+ /** One per selector, in order. */
14
+ label?: string | string[];
15
+ /** Screenshot name; defaults to a slug of the first selector. */
16
+ name?: string;
17
+ /** Crop to the element with the surroundings dimmed. Good for a ticket. */
18
+ crop?: boolean;
19
+ cropPadding?: number;
20
+ shape?: ShapeKind;
21
+ style?: AnnotationStyle;
22
+ /** Bring the first target into view if it is not already. Default true. */
23
+ scrollIntoView?: boolean;
24
+ /**
25
+ * When scrolling is needed, leave this many CSS px above the element. Cypress
26
+ * otherwise scrolls it flush to the top of the viewport, where a fixed header
27
+ * covers the very thing being annotated. Default 120.
28
+ */
29
+ scrollOffset?: number;
30
+ /** Keep the un-annotated image alongside, for assertions. */
31
+ keepRaw?: boolean;
32
+ /**
33
+ * Capture the whole document rather than the viewport. Off by default and
34
+ * best avoided: Cypress builds a full-page screenshot by scrolling and
35
+ * stitching, which paints position:fixed and sticky elements repeatedly.
36
+ */
37
+ fullPage?: boolean;
38
+ }
39
+ declare global {
40
+ namespace Cypress {
41
+ interface Chainable {
42
+ /**
43
+ * Screenshot the page with an accurate box drawn around `selector`.
44
+ * Yields the annotation result, including where the box was drawn.
45
+ */
46
+ annotate(selector: string | string[], options?: AnnotateCommandOptions): Chainable<AnnotateTaskResult>;
47
+ }
48
+ }
49
+ }
50
+ //# sourceMappingURL=commands.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/cypress/commands.ts"],"names":[],"mappings":"AAGA,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;AA6ED,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,OAAO,CAAC;QAChB,UAAU,SAAS;YACjB;;;eAGG;YACH,QAAQ,CACN,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,EAC3B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,SAAS,CAAC,kBAAkB,CAAC,CAAC;SAClC;KACF;CACF"}
@@ -0,0 +1,68 @@
1
+ /// <reference types="cypress" />
2
+ import { measureTargets } from './measure-dom.js';
3
+ import { isFullyVisible, scrollIntoViewIfNeeded } from './scroll-into-view.js';
4
+ function slugify(text) {
5
+ return text.replace(/[^a-z0-9]+/gi, '-').replace(/^-+|-+$/g, '').toLowerCase() || 'annotated';
6
+ }
7
+ Cypress.Commands.add('annotate', (selector, options = {}) => {
8
+ const selectors = Array.isArray(selector) ? selector : [selector];
9
+ const labels = options.label === undefined
10
+ ? []
11
+ : Array.isArray(options.label)
12
+ ? options.label
13
+ : [options.label];
14
+ const name = options.name ?? slugify(selectors[0] ?? 'annotated');
15
+ const capture = options.fullPage ? 'fullPage' : 'viewport';
16
+ return cy
17
+ .window({ log: false })
18
+ .then((win) => {
19
+ const initial = measureTargets(win, selectors);
20
+ const first = initial.targets[0];
21
+ // Only scroll when the element genuinely is not fully visible. Cypress's
22
+ // scrollIntoView always scrolls, so calling it unconditionally moves a
23
+ // perfectly visible element under a sticky header for no reason.
24
+ const needsScroll = options.scrollIntoView !== false &&
25
+ first?.found === true &&
26
+ first.rect !== undefined &&
27
+ !isFullyVisible(first.rect, win);
28
+ if (!needsScroll)
29
+ return cy.wrap(initial, { log: false });
30
+ return scrollIntoViewIfNeeded(selectors[0], options.scrollOffset ?? 120)
31
+ // Re-measure: the rects from before the scroll are now meaningless.
32
+ .then(() => cy.window({ log: false }).then((w) => measureTargets(w, selectors)));
33
+ })
34
+ .then((measurement) => {
35
+ let screenshotPath;
36
+ return cy
37
+ .screenshot(name, {
38
+ capture,
39
+ overwrite: true,
40
+ log: false,
41
+ onAfterScreenshot(_el, props) {
42
+ screenshotPath = props.path;
43
+ },
44
+ })
45
+ .then(() => {
46
+ if (!screenshotPath) {
47
+ throw new Error('cy.annotate: Cypress did not report a screenshot path.');
48
+ }
49
+ return cy.task('annotateScreenshot', {
50
+ screenshotPath,
51
+ measurement,
52
+ labels,
53
+ capture,
54
+ crop: options.crop,
55
+ cropPadding: options.cropPadding,
56
+ shape: options.shape,
57
+ style: options.style,
58
+ keepRaw: options.keepRaw,
59
+ });
60
+ })
61
+ .then((result) => {
62
+ for (const warning of result.warnings) {
63
+ Cypress.log({ name: 'annotate', message: `! ${warning}` });
64
+ }
65
+ return result;
66
+ });
67
+ });
68
+ });