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,45 @@
1
+ import Anthropic from '@anthropic-ai/sdk';
2
+ import type { FailureRecord } from './failure-report.js';
3
+ /**
4
+ * Claude fallback for the failures registerFailureCapture could not resolve
5
+ * deterministically - no selector recovered, or the recovered selector matched
6
+ * nothing live. Deliberately a separate, narrower task from finder.ts's
7
+ * open-ended bug hunting: the failure is already known (err.message says so);
8
+ * the only open question is *where on screen it shows up*, from a fixed list
9
+ * of candidate elements captured live at failure time. That's a smaller,
10
+ * cheaper, more constrained ask than "find bugs on this page".
11
+ */
12
+ export interface FailureExplanation {
13
+ /** One of the inventory selectors from the record, or null if none fit. */
14
+ selector: string | null;
15
+ label: string;
16
+ /** Fallback region (percent of viewport) when no inventory item fits. */
17
+ region: {
18
+ xPct: number;
19
+ yPct: number;
20
+ widthPct: number;
21
+ heightPct: number;
22
+ } | null;
23
+ }
24
+ export interface FailureExplainer {
25
+ explain(record: FailureRecord): Promise<FailureExplanation>;
26
+ }
27
+ export interface ClaudeFailureExplainerOptions {
28
+ model?: string;
29
+ effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
30
+ client?: Anthropic;
31
+ }
32
+ export declare class ClaudeFailureExplainer implements FailureExplainer {
33
+ private readonly client;
34
+ private readonly model;
35
+ private readonly effort;
36
+ constructor(options?: ClaudeFailureExplainerOptions);
37
+ explain(record: FailureRecord): Promise<FailureExplanation>;
38
+ }
39
+ /** For tests and offline runs - no API call. */
40
+ export declare class ReplayFailureExplainer implements FailureExplainer {
41
+ private readonly explanation;
42
+ constructor(explanation: FailureExplanation);
43
+ explain(): Promise<FailureExplanation>;
44
+ }
45
+ //# sourceMappingURL=failure-explainer.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"failure-explainer.d.ts","sourceRoot":"","sources":["../../src/cypress/failure-explainer.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;;GAQG;AAEH,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACpF;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC7D;AA6DD,MAAM,WAAW,6BAA6B;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;IACrD,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAED,qBAAa,sBAAuB,YAAW,gBAAgB;IAC7D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8C;gBAEzD,OAAO,GAAE,6BAAkC;IAMjD,OAAO,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAoDlE;AAED,gDAAgD;AAChD,qBAAa,sBAAuB,YAAW,gBAAgB;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAAX,WAAW,EAAE,kBAAkB;IACtD,OAAO,IAAI,OAAO,CAAC,kBAAkB,CAAC;CAG7C"}
@@ -0,0 +1,123 @@
1
+ import Anthropic from '@anthropic-ai/sdk';
2
+ const SCHEMA = {
3
+ type: 'object',
4
+ properties: {
5
+ selector: {
6
+ type: ['string', 'null'],
7
+ description: 'The "selector" value of the single inventory element that best shows where this failure is ' +
8
+ 'visible on screen. Null only if no listed element corresponds to it.',
9
+ },
10
+ label: {
11
+ type: 'string',
12
+ description: 'One short sentence for the annotation, explaining the failure in plain terms.',
13
+ },
14
+ region: {
15
+ type: ['object', 'null'],
16
+ description: 'Fallback used only when selector is null: the area to box, in percentages of the viewport.',
17
+ properties: {
18
+ xPct: { type: 'number' },
19
+ yPct: { type: 'number' },
20
+ widthPct: { type: 'number' },
21
+ heightPct: { type: 'number' },
22
+ },
23
+ required: ['xPct', 'yPct', 'widthPct', 'heightPct'],
24
+ additionalProperties: false,
25
+ },
26
+ },
27
+ required: ['selector', 'label', 'region'],
28
+ additionalProperties: false,
29
+ };
30
+ const SYSTEM_PROMPT = `A Cypress test failed. You are given the screenshot at the moment of failure,
31
+ the test's own error message, and a list of candidate elements on the page with their
32
+ tag, visible text, and bounding box in CSS pixels.
33
+
34
+ This is not exploratory bug hunting - the failure is already known and described by the
35
+ error message. Your only job is to say where on screen it is visible, by picking the
36
+ single best-matching element from the list, and to write one short, plain-language
37
+ sentence explaining it for someone triaging CI failures who has not read the error.
38
+
39
+ Prefer an element whose visible text or position plausibly explains the error message
40
+ over one that merely has a similar name. If nothing in the list corresponds to the
41
+ failure - for example the error describes something absent, like a modal that should
42
+ have appeared - set selector to null and give a region instead, as percentages of the
43
+ viewport, for roughly where it was expected.
44
+
45
+ Always call the report tool exactly once.`;
46
+ function renderInventory(inventory) {
47
+ if (!inventory)
48
+ return '(no candidate elements captured)';
49
+ return inventory
50
+ .map((item) => {
51
+ const r = item.rect;
52
+ const box = r ? `${Math.round(r.x)},${Math.round(r.y)} ${Math.round(r.width)}x${Math.round(r.height)}` : '?';
53
+ const text = item.text ? ` "${item.text}"` : '';
54
+ return `[${item.selector}] <${item.tag ?? '?'}>${text} @ ${box}`;
55
+ })
56
+ .join('\n');
57
+ }
58
+ export class ClaudeFailureExplainer {
59
+ client;
60
+ model;
61
+ effort;
62
+ constructor(options = {}) {
63
+ this.client = options.client ?? new Anthropic();
64
+ this.model = options.model ?? 'claude-opus-5';
65
+ this.effort = options.effort ?? 'medium';
66
+ }
67
+ async explain(record) {
68
+ const { readFile } = await import('node:fs/promises');
69
+ const screenshot = await readFile(record.screenshotPath);
70
+ const stream = this.client.messages.stream({
71
+ model: this.model,
72
+ max_tokens: 4096,
73
+ system: SYSTEM_PROMPT,
74
+ thinking: { type: 'adaptive' },
75
+ output_config: { effort: this.effort },
76
+ tools: [
77
+ {
78
+ name: 'report_location',
79
+ description: 'Report where the known failure is visible on screen.',
80
+ input_schema: SCHEMA,
81
+ strict: true,
82
+ },
83
+ ],
84
+ messages: [
85
+ {
86
+ role: 'user',
87
+ content: [
88
+ { type: 'image', source: { type: 'base64', media_type: 'image/png', data: screenshot.toString('base64') } },
89
+ {
90
+ type: 'text',
91
+ text: `Test: ${record.test}\n` +
92
+ `Error: ${record.errMessage}\n\n` +
93
+ `Candidate elements:\n${renderInventory(record.inventory)}`,
94
+ },
95
+ ],
96
+ },
97
+ ],
98
+ });
99
+ const message = await stream.finalMessage();
100
+ if (message.stop_reason === 'refusal') {
101
+ throw new Error(`Model declined (${message.stop_details?.category ?? 'unknown'}).`);
102
+ }
103
+ const call = message.content.find((b) => b.type === 'tool_use' && b.name === 'report_location');
104
+ if (!call)
105
+ throw new Error(`Model did not call report_location (stop_reason: ${message.stop_reason}).`);
106
+ const input = call.input;
107
+ return {
108
+ selector: typeof input.selector === 'string' ? input.selector : null,
109
+ label: typeof input.label === 'string' && input.label ? input.label : record.label,
110
+ region: input.region ?? null,
111
+ };
112
+ }
113
+ }
114
+ /** For tests and offline runs - no API call. */
115
+ export class ReplayFailureExplainer {
116
+ explanation;
117
+ constructor(explanation) {
118
+ this.explanation = explanation;
119
+ }
120
+ async explain() {
121
+ return this.explanation;
122
+ }
123
+ }
@@ -0,0 +1,30 @@
1
+ import type { AnnotationStyle } from '../types.js';
2
+ export interface FailureCaptureOptions {
3
+ /** Where failure records accumulate across the whole run. */
4
+ reportPath?: string;
5
+ style?: AnnotationStyle;
6
+ }
7
+ /**
8
+ * Register once, in cypress/support/e2e.ts:
9
+ *
10
+ * registerFailureCapture();
11
+ *
12
+ * On every failed test, this recovers the selector the failing command was
13
+ * targeting (deterministic, no AI - see failure-selector.ts), measures it live
14
+ * while the page is still in its failed state, and draws a box with a label
15
+ * built from the assertion's own expected/actual values.
16
+ *
17
+ * When no selector can be recovered - an existence check, a `cy.contains()`
18
+ * chain, a generic page-state assertion - there is nothing to box
19
+ * deterministically. Those failures get a plain screenshot plus a live DOM
20
+ * inventory (metrics + candidate elements), written to the same report for a
21
+ * separate, explicit tool to reason about afterwards. That split is
22
+ * deliberate: capturing is free and happens for every failure; calling Claude
23
+ * is a cost decision left to whoever reads the report, not made here.
24
+ *
25
+ * Requires `screenshotOnRunFailure: false` in cypress.config.ts - otherwise
26
+ * Cypress's own automatic failure screenshot and this hook's screenshot race,
27
+ * and it becomes ambiguous which one the DOM measurement actually matches.
28
+ */
29
+ export declare function registerFailureCapture(options?: FailureCaptureOptions): void;
30
+ //# sourceMappingURL=failure-hook.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"failure-hook.d.ts","sourceRoot":"","sources":["../../src/cypress/failure-hook.ts"],"names":[],"mappings":"AAMA,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;AAQD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,qBAA0B,GAAG,IAAI,CA4IhF"}
@@ -0,0 +1,148 @@
1
+ /// <reference types="cypress" />
2
+ import { describeFailure, recoverFailure } from './failure-selector.js';
3
+ import { collectInventory, measureTargets, readMetrics } from './measure-dom.js';
4
+ import { isFullyVisible, scrollIntoViewIfNeeded } from './scroll-into-view.js';
5
+ const DEFAULT_REPORT_PATH = 'out/cypress/failures.json';
6
+ function slugify(text) {
7
+ return text.replace(/[^a-z0-9]+/gi, '-').replace(/^-+|-+$/g, '').toLowerCase().slice(0, 60) || 'failure';
8
+ }
9
+ /**
10
+ * Register once, in cypress/support/e2e.ts:
11
+ *
12
+ * registerFailureCapture();
13
+ *
14
+ * On every failed test, this recovers the selector the failing command was
15
+ * targeting (deterministic, no AI - see failure-selector.ts), measures it live
16
+ * while the page is still in its failed state, and draws a box with a label
17
+ * built from the assertion's own expected/actual values.
18
+ *
19
+ * When no selector can be recovered - an existence check, a `cy.contains()`
20
+ * chain, a generic page-state assertion - there is nothing to box
21
+ * deterministically. Those failures get a plain screenshot plus a live DOM
22
+ * inventory (metrics + candidate elements), written to the same report for a
23
+ * separate, explicit tool to reason about afterwards. That split is
24
+ * deliberate: capturing is free and happens for every failure; calling Claude
25
+ * is a cost decision left to whoever reads the report, not made here.
26
+ *
27
+ * Requires `screenshotOnRunFailure: false` in cypress.config.ts - otherwise
28
+ * Cypress's own automatic failure screenshot and this hook's screenshot race,
29
+ * and it becomes ambiguous which one the DOM measurement actually matches.
30
+ */
31
+ export function registerFailureCapture(options = {}) {
32
+ const reportPath = options.reportPath ?? DEFAULT_REPORT_PATH;
33
+ afterEach(function () {
34
+ if (this.currentTest?.state !== 'failed')
35
+ return;
36
+ // Read failure state before issuing any cy.* command below - those mutate
37
+ // cy.state('current'), so this has to happen first and synchronously.
38
+ const err = this.currentTest.err;
39
+ // cy.state is undocumented Cypress driver internals; guarded because a
40
+ // Cypress upgrade could remove or rename it, and this hook must degrade to
41
+ // "no selector recovered" rather than break the whole afterEach.
42
+ let current = null;
43
+ try {
44
+ current = cy.state('current');
45
+ }
46
+ catch {
47
+ current = null;
48
+ }
49
+ const recovered = recoverFailure(err, current);
50
+ const label = describeFailure(err, recovered);
51
+ const testTitle = this.currentTest.fullTitle();
52
+ const name = `failure-${slugify(testTitle)}`;
53
+ /**
54
+ * Same measure -> scroll-if-needed -> re-measure discipline as cy.annotate().
55
+ * The failing element was found by cy.state, not chosen from the current
56
+ * viewport, so unlike cy.annotate() it may sit well below the fold - the
57
+ * whole reason this exists is to point at a mismatch, so screenshotting a
58
+ * viewport that never contains the mismatch would be a silent no-op box.
59
+ */
60
+ function prepare(win) {
61
+ const initial = recovered.selector && !recovered.elementNotFound ? measureTargets(win, [recovered.selector]) : null;
62
+ const initialTarget = initial?.targets[0];
63
+ const needsScroll = initialTarget?.found === true && initialTarget.rect !== undefined && !isFullyVisible(initialTarget.rect, win);
64
+ if (!needsScroll) {
65
+ const resolved = Boolean(initialTarget?.found && initialTarget.rect);
66
+ return cy.wrap({
67
+ target: initialTarget ?? null,
68
+ resolved,
69
+ inventory: resolved ? null : collectInventory(win),
70
+ metrics: readMetrics(win),
71
+ }, { log: false });
72
+ }
73
+ return scrollIntoViewIfNeeded(recovered.selector)
74
+ .then(() => cy.window({ log: false }))
75
+ .then((w) => {
76
+ const remeasured = measureTargets(w, [recovered.selector]);
77
+ const target = remeasured.targets[0];
78
+ const resolved = Boolean(target?.found && target.rect);
79
+ return {
80
+ target: target ?? null,
81
+ resolved,
82
+ inventory: resolved ? null : collectInventory(w),
83
+ metrics: readMetrics(w),
84
+ };
85
+ });
86
+ }
87
+ cy.window({ log: false })
88
+ .then((win) => prepare(win))
89
+ .then(({ target, resolved, inventory, metrics }) => {
90
+ let screenshotPath;
91
+ return cy
92
+ .screenshot(name, {
93
+ capture: 'viewport',
94
+ overwrite: true,
95
+ log: false,
96
+ onAfterScreenshot(_el, props) {
97
+ screenshotPath = props.path;
98
+ },
99
+ })
100
+ .then(() => {
101
+ if (!screenshotPath) {
102
+ throw new Error('registerFailureCapture: Cypress did not report a screenshot path.');
103
+ }
104
+ if (!resolved) {
105
+ return cy.wrap(null, { log: false });
106
+ }
107
+ return cy.task('annotateScreenshot', {
108
+ screenshotPath,
109
+ measurement: { metrics, targets: [target] },
110
+ labels: [label],
111
+ capture: 'viewport',
112
+ style: options.style,
113
+ });
114
+ })
115
+ .then((annotateResult) => {
116
+ const record = {
117
+ spec: Cypress.spec.relative,
118
+ test: testTitle,
119
+ errMessage: err?.message ?? '',
120
+ errName: err?.name,
121
+ selector: recovered.selector,
122
+ selectorSource: recovered.source,
123
+ expected: recovered.expected,
124
+ actual: recovered.actual,
125
+ elementNotFound: recovered.elementNotFound,
126
+ label,
127
+ resolved,
128
+ screenshotPath: screenshotPath,
129
+ annotatedPath: annotateResult?.outPath ?? null,
130
+ drawnRect: annotateResult?.drawnRects[0] ?? null,
131
+ metrics,
132
+ inventory: inventory
133
+ ? inventory.map((item) => ({
134
+ selector: `[data-annot-ref="${item.ref}"]`,
135
+ found: true,
136
+ tag: item.tag,
137
+ text: item.name,
138
+ rect: item.rect,
139
+ }))
140
+ : null,
141
+ warnings: annotateResult?.warnings ?? [],
142
+ timestamp: new Date().toISOString(),
143
+ };
144
+ return cy.task('appendFailureRecord', { reportPath, record }, { log: false });
145
+ });
146
+ });
147
+ });
148
+ }
@@ -0,0 +1,41 @@
1
+ import type { PageMetrics, PixelRect } from '../types.js';
2
+ import type { DomMeasurement } from './measure-dom.js';
3
+ /**
4
+ * One test failure, captured live and written to disk. The Node-side task
5
+ * appends to this file rather than overwriting it, since a spec run produces
6
+ * many failures across many test files.
7
+ */
8
+ export interface FailureRecord {
9
+ spec: string;
10
+ test: string;
11
+ errMessage: string;
12
+ errName: string | undefined;
13
+ selector: string | null;
14
+ selectorSource: string;
15
+ expected: string | null;
16
+ actual: string | null;
17
+ elementNotFound: boolean;
18
+ label: string;
19
+ /** Set only when a selector resolved to a live, measurable element. */
20
+ resolved: boolean;
21
+ screenshotPath: string;
22
+ annotatedPath: string | null;
23
+ drawnRect: PixelRect | null;
24
+ /** Always captured, so the fallback script can convert inventory rects later. */
25
+ metrics: PageMetrics;
26
+ /**
27
+ * Present only when no selector resolved. A same-shape inventory to the one
28
+ * the MCP skill uses, captured live because a screenshot alone carries no
29
+ * DOM information - this is what lets the Claude fallback reason about the
30
+ * failure after the browser session is long gone.
31
+ */
32
+ inventory: DomMeasurement['targets'] | null;
33
+ warnings: string[];
34
+ timestamp: string;
35
+ }
36
+ export interface AppendFailureArgs {
37
+ reportPath: string;
38
+ record: FailureRecord;
39
+ }
40
+ export declare function appendFailureRecord({ reportPath, record }: AppendFailureArgs): Promise<null>;
41
+ //# sourceMappingURL=failure-report.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"failure-report.d.ts","sourceRoot":"","sources":["../../src/cypress/failure-report.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,eAAe,EAAE,OAAO,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5B,iFAAiF;IACjF,OAAO,EAAE,WAAW,CAAC;IACrB;;;;;OAKG;IACH,SAAS,EAAE,cAAc,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;IAC5C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,wBAAsB,mBAAmB,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUlG"}
@@ -0,0 +1,14 @@
1
+ import { readFile, writeFile } from 'node:fs/promises';
2
+ export async function appendFailureRecord({ reportPath, record }) {
3
+ let existing = [];
4
+ try {
5
+ existing = JSON.parse(await readFile(reportPath, 'utf8'));
6
+ }
7
+ catch (error) {
8
+ if (error.code !== 'ENOENT')
9
+ throw error;
10
+ }
11
+ existing.push(record);
12
+ await writeFile(reportPath, JSON.stringify(existing, null, 2));
13
+ return null;
14
+ }
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Recover the selector a failed Cypress command was operating on, and the
3
+ * expected/actual values, without parsing a guessed error format.
4
+ *
5
+ * Verified empirically against real Cypress 15.19 output (see
6
+ * scripts/test-failure-selector.ts, which replays captured error objects):
7
+ *
8
+ * cy.get('#grand-total-value').should('have.text', 'X') fails with
9
+ * err.expected = 'X', err.actual = '£244.99' (diffable assertions only)
10
+ * err.message = "expected '<span#grand-total-value>' to have text 'X', but the text was '£244.99'"
11
+ * cy.state('current').get('name') = 'get'
12
+ * cy.state('current').get('args') = ['#grand-total-value']
13
+ *
14
+ * cy.get('#promo-apply').should('contain', 'X') fails with
15
+ * err.expected / err.actual absent (chai's contain assertion is not diffable)
16
+ * err.message = "expected '<button#promo-apply>' to contain 'X'"
17
+ *
18
+ * cy.get('#missing').should('be.visible') fails with
19
+ * err.message = "Expected to find element: `#missing`, but never found it."
20
+ */
21
+ export interface CypressLikeError {
22
+ name?: string;
23
+ message?: string;
24
+ expected?: string;
25
+ actual?: string;
26
+ }
27
+ /** Minimal shape of what cy.state('current') exposes, read defensively. */
28
+ export interface CommandLike {
29
+ get(key: 'name'): string | undefined;
30
+ get(key: 'args'): unknown[] | undefined;
31
+ }
32
+ export interface RecoveredFailure {
33
+ /** CSS selector the failing command targeted, if one could be recovered. */
34
+ selector: string | null;
35
+ /** How it was recovered - for diagnostics, not behaviour. */
36
+ source: 'command-state' | 'message-selector' | 'message-not-found' | 'none';
37
+ expected: string | null;
38
+ actual: string | null;
39
+ /** True for "element never existed" failures - there is nothing to box. */
40
+ elementNotFound: boolean;
41
+ }
42
+ export declare function recoverFailure(err: CypressLikeError | undefined, current: CommandLike | null): RecoveredFailure;
43
+ /** One-line label for the annotation, built entirely from what was recovered. */
44
+ export declare function describeFailure(err: CypressLikeError | undefined, recovered: RecoveredFailure): string;
45
+ //# sourceMappingURL=failure-selector.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"failure-selector.d.ts","sourceRoot":"","sources":["../../src/cypress/failure-selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACrC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,EAAE,GAAG,SAAS,CAAC;CACzC;AAED,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,6DAA6D;IAC7D,MAAM,EAAE,eAAe,GAAG,kBAAkB,GAAG,mBAAmB,GAAG,MAAM,CAAC;IAC5E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,2EAA2E;IAC3E,eAAe,EAAE,OAAO,CAAC;CAC1B;AA2CD,wBAAgB,cAAc,CAAC,GAAG,EAAE,gBAAgB,GAAG,SAAS,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,GAAG,gBAAgB,CAuC/G;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,GAAG,EAAE,gBAAgB,GAAG,SAAS,EAAE,SAAS,EAAE,gBAAgB,GAAG,MAAM,CAWtG"}
@@ -0,0 +1,107 @@
1
+ /**
2
+ * Recover the selector a failed Cypress command was operating on, and the
3
+ * expected/actual values, without parsing a guessed error format.
4
+ *
5
+ * Verified empirically against real Cypress 15.19 output (see
6
+ * scripts/test-failure-selector.ts, which replays captured error objects):
7
+ *
8
+ * cy.get('#grand-total-value').should('have.text', 'X') fails with
9
+ * err.expected = 'X', err.actual = '£244.99' (diffable assertions only)
10
+ * err.message = "expected '<span#grand-total-value>' to have text 'X', but the text was '£244.99'"
11
+ * cy.state('current').get('name') = 'get'
12
+ * cy.state('current').get('args') = ['#grand-total-value']
13
+ *
14
+ * cy.get('#promo-apply').should('contain', 'X') fails with
15
+ * err.expected / err.actual absent (chai's contain assertion is not diffable)
16
+ * err.message = "expected '<button#promo-apply>' to contain 'X'"
17
+ *
18
+ * cy.get('#missing').should('be.visible') fails with
19
+ * err.message = "Expected to find element: `#missing`, but never found it."
20
+ */
21
+ /**
22
+ * Chai stores `err.expected`/`err.actual` as chai's own `inspect()` rendering
23
+ * of the value, not the raw value - for a string that means it arrives wrapped
24
+ * in its own single quotes: `err.expected` for `.should('have.text', 'X')` is
25
+ * the string `'X'` with its quote marks, not `X`. Confirmed against a real Cypress
26
+ * 15.19 run (see scripts/test-failure-selector.ts) rather than assumed.
27
+ */
28
+ function unquote(value) {
29
+ if (value === undefined)
30
+ return null;
31
+ const match = value.match(/^'(.*)'$/s);
32
+ return match ? (match[1] ?? '') : value;
33
+ }
34
+ /** Cypress commands whose first argument is a locator. */
35
+ const LOCATOR_COMMANDS = new Set(['get', 'find', 'contains']);
36
+ function firstStringArg(args) {
37
+ if (!args)
38
+ return null;
39
+ const value = args.find((a) => typeof a === 'string');
40
+ return value ?? null;
41
+ }
42
+ /**
43
+ * chai-jquery renders a matched element as `<tag#id>` or `<tag.class>` inside
44
+ * its assertion messages. This is part of chai-jquery's public message format,
45
+ * not an accident of one version, but it is still text-parsing - used only when
46
+ * cy.state('current') did not resolve.
47
+ */
48
+ function selectorFromMessage(message) {
49
+ const match = message.match(/<([a-z][a-z0-9]*)(#[\w-]+|\.[\w-]+)?>/i);
50
+ if (!match)
51
+ return null;
52
+ const [, tag, qualifier] = match;
53
+ return qualifier ? qualifier : (tag ?? null);
54
+ }
55
+ function notFoundSelector(message) {
56
+ // "Expected to find element: `#missing`, but never found it."
57
+ const match = message.match(/Expected to find element:\s*`([^`]+)`/);
58
+ return match?.[1] ?? null;
59
+ }
60
+ export function recoverFailure(err, current) {
61
+ const message = err?.message ?? '';
62
+ const elementNotFound = /but never found it|Expected to find element/.test(message);
63
+ let selector = null;
64
+ let source = 'none';
65
+ const commandName = current?.get('name');
66
+ if (commandName && LOCATOR_COMMANDS.has(commandName)) {
67
+ const fromState = firstStringArg(current?.get('args'));
68
+ if (fromState) {
69
+ selector = fromState;
70
+ source = 'command-state';
71
+ }
72
+ }
73
+ if (!selector && elementNotFound) {
74
+ const found = notFoundSelector(message);
75
+ if (found) {
76
+ selector = found;
77
+ source = 'message-not-found';
78
+ }
79
+ }
80
+ if (!selector) {
81
+ const found = selectorFromMessage(message);
82
+ if (found) {
83
+ selector = found;
84
+ source = 'message-selector';
85
+ }
86
+ }
87
+ return {
88
+ selector,
89
+ source,
90
+ expected: unquote(err?.expected),
91
+ actual: unquote(err?.actual),
92
+ elementNotFound,
93
+ };
94
+ }
95
+ /** One-line label for the annotation, built entirely from what was recovered. */
96
+ export function describeFailure(err, recovered) {
97
+ if (recovered.expected !== null && recovered.actual !== null) {
98
+ return `Expected "${recovered.expected}" but got "${recovered.actual}"`;
99
+ }
100
+ if (recovered.elementNotFound) {
101
+ return `Element never appeared: ${recovered.selector ?? 'unknown selector'}`;
102
+ }
103
+ // No diffable values (e.g. a `contain` assertion) - the message itself
104
+ // already states expected vs. found, just less structured.
105
+ const message = err?.message ?? 'Assertion failed';
106
+ return message.replace(/^Timed out retrying after \d+ms:\s*/, '');
107
+ }
@@ -0,0 +1,52 @@
1
+ import type { PageMetrics } from '../types.js';
2
+ /**
3
+ * Measure elements inside a given window.
4
+ *
5
+ * This is the bundled counterpart to src/browser/measure-target.js, which is the
6
+ * copy-pasteable version for agent MCP sessions. They must stay in agreement:
7
+ * same metrics definitions, same fixed-ancestry rule, same rect shape.
8
+ */
9
+ export interface MeasuredDomTarget {
10
+ selector: string;
11
+ found: boolean;
12
+ error?: string;
13
+ matchCount?: number;
14
+ tag?: string;
15
+ text?: string;
16
+ isFixed?: boolean;
17
+ inViewport?: boolean;
18
+ rect?: {
19
+ x: number;
20
+ y: number;
21
+ width: number;
22
+ height: number;
23
+ };
24
+ }
25
+ export interface DomMeasurement {
26
+ metrics: PageMetrics;
27
+ targets: MeasuredDomTarget[];
28
+ }
29
+ export declare function readMetrics(win: Window): PageMetrics;
30
+ export interface InventoryItem {
31
+ ref: string;
32
+ tag: string;
33
+ name: string;
34
+ rect: {
35
+ x: number;
36
+ y: number;
37
+ width: number;
38
+ height: number;
39
+ };
40
+ }
41
+ /**
42
+ * Collect elements worth showing to Claude, for the case where no single
43
+ * selector could be recovered from the failure. Same "interesting element"
44
+ * heuristic as src/browser/collect-elements.js (the MCP-facing version), but
45
+ * written directly against `Window` rather than serialized as a string: in
46
+ * Cypress there is no eval boundary to cross, so there is nothing to duplicate
47
+ * that trick for.
48
+ */
49
+ export declare function collectInventory(win: Window, limit?: number): InventoryItem[];
50
+ export declare function refSelector(ref: string): string;
51
+ export declare function measureTargets(win: Window, selectors: string[]): DomMeasurement;
52
+ //# sourceMappingURL=measure-dom.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"measure-dom.d.ts","sourceRoot":"","sources":["../../src/cypress/measure-dom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;GAMG;AAEH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAChE;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,WAAW,CAAC;IACrB,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAepD;AAOD,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/D;AAuBD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,SAAM,GAAG,aAAa,EAAE,CAqC1E;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,cAAc,CA2C/E"}