cypress-annotate 0.4.0 → 1.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 +40 -28
- package/CHANGELOG.md +174 -0
- package/DOCS/images/crop.png +0 -0
- package/DOCS/images/failure-hook.png +0 -0
- package/DOCS/internals.md +151 -0
- package/README.md +104 -352
- package/dist/annotate-image.d.ts +19 -2
- package/dist/annotate-image.d.ts.map +1 -1
- package/dist/annotate-image.js +55 -12
- package/dist/cypress/commands.d.ts +6 -1
- package/dist/cypress/commands.d.ts.map +1 -1
- package/dist/cypress/commands.js +20 -6
- package/dist/cypress/config.d.ts +42 -0
- package/dist/cypress/config.d.ts.map +1 -0
- package/dist/cypress/config.js +102 -0
- package/dist/cypress/failure-hook.d.ts.map +1 -1
- package/dist/cypress/failure-hook.js +17 -3
- package/dist/cypress/failure-report.d.ts +6 -0
- package/dist/cypress/failure-report.d.ts.map +1 -1
- package/dist/cypress/failure-report.js +14 -4
- package/dist/cypress/task.d.ts +39 -3
- package/dist/cypress/task.d.ts.map +1 -1
- package/dist/cypress/task.js +61 -5
- package/dist/draw.d.ts +4 -0
- package/dist/draw.d.ts.map +1 -1
- package/dist/draw.js +7 -4
- package/dist/index.d.ts +9 -20
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7 -57
- package/dist/types.d.ts +13 -69
- package/dist/types.d.ts.map +1 -1
- package/package.json +11 -43
- package/skills/cypress-annotate/SKILL.md +62 -9
- package/DOCS/pipeline.md +0 -308
- package/dist/annotate.d.ts +0 -9
- package/dist/annotate.d.ts.map +0 -1
- package/dist/annotate.js +0 -82
- package/dist/browser/collect-elements.js +0 -158
- package/dist/browser/measure-target.js +0 -69
- package/dist/claude-reasoner.d.ts +0 -17
- package/dist/claude-reasoner.d.ts.map +0 -1
- package/dist/claude-reasoner.js +0 -192
- package/dist/cli.d.ts +0 -3
- package/dist/cli.d.ts.map +0 -1
- package/dist/cli.js +0 -84
- package/dist/cypress/failure-explainer.d.ts +0 -45
- package/dist/cypress/failure-explainer.d.ts.map +0 -1
- package/dist/cypress/failure-explainer.js +0 -123
- package/dist/finder.d.ts +0 -68
- package/dist/finder.d.ts.map +0 -1
- package/dist/finder.js +0 -64
- package/dist/inventory.d.ts +0 -33
- package/dist/inventory.d.ts.map +0 -1
- package/dist/inventory.js +0 -88
- package/dist/measure.d.ts +0 -11
- package/dist/measure.d.ts.map +0 -1
- package/dist/measure.js +0 -145
- package/dist/pipeline.d.ts +0 -60
- package/dist/pipeline.d.ts.map +0 -1
- package/dist/pipeline.js +0 -115
- package/skills/annotate-bug/SKILL.md +0 -121
- package/src/browser/collect-elements.js +0 -158
- package/src/browser/measure-target.js +0 -69
package/dist/cypress/task.js
CHANGED
|
@@ -1,6 +1,40 @@
|
|
|
1
|
-
import { readFile, writeFile } from 'node:fs/promises';
|
|
1
|
+
import { appendFile, readFile, rm, writeFile } from 'node:fs/promises';
|
|
2
|
+
import { relative } from 'node:path';
|
|
2
3
|
import { annotateImage } from '../annotate-image.js';
|
|
3
|
-
import { appendFailureRecord } from './failure-report.js';
|
|
4
|
+
import { appendFailureRecord, appendRecord } from './failure-report.js';
|
|
5
|
+
import { DEFAULT_MANIFEST_PATH } from './config.js';
|
|
6
|
+
/**
|
|
7
|
+
* Manifest paths already written to by this process. Cypress runs the whole of
|
|
8
|
+
* `cypress run` in one Node process, so "first write of the process" is the
|
|
9
|
+
* run boundary, and using it means no before:run handler is needed to clear
|
|
10
|
+
* last run's records.
|
|
11
|
+
*/
|
|
12
|
+
const manifestsStarted = new Set();
|
|
13
|
+
/** Whether the job summary's table header has been written yet this process. */
|
|
14
|
+
let summaryStarted = false;
|
|
15
|
+
async function appendStepSummary(record) {
|
|
16
|
+
const summaryPath = process.env.GITHUB_STEP_SUMMARY;
|
|
17
|
+
if (!summaryPath)
|
|
18
|
+
return;
|
|
19
|
+
const label = record.labels.join('; ') || '-';
|
|
20
|
+
const warnings = record.warnings.length > 0 ? ` (${record.warnings.length} warning(s))` : '';
|
|
21
|
+
const row = `| ${record.test ?? record.spec ?? '-'} ` +
|
|
22
|
+
`| ${label.replace(/\|/g, '\\|')} ` +
|
|
23
|
+
`| \`${relative(process.cwd(), record.outPath)}\`${warnings} |\n`;
|
|
24
|
+
const header = summaryStarted
|
|
25
|
+
? ''
|
|
26
|
+
: '### Annotated screenshots\n\n| Test | Label | Image |\n| --- | --- | --- |\n';
|
|
27
|
+
summaryStarted = true;
|
|
28
|
+
await appendFile(summaryPath, header + row);
|
|
29
|
+
}
|
|
30
|
+
async function recordAnnotation(manifestPath, record) {
|
|
31
|
+
if (!manifestsStarted.has(manifestPath)) {
|
|
32
|
+
manifestsStarted.add(manifestPath);
|
|
33
|
+
await rm(manifestPath, { force: true });
|
|
34
|
+
}
|
|
35
|
+
await appendRecord(manifestPath, record);
|
|
36
|
+
await appendStepSummary(record);
|
|
37
|
+
}
|
|
4
38
|
export async function annotateScreenshot(args) {
|
|
5
39
|
const { screenshotPath, measurement } = args;
|
|
6
40
|
if (!screenshotPath)
|
|
@@ -38,6 +72,7 @@ export async function annotateScreenshot(args) {
|
|
|
38
72
|
crop: args.crop,
|
|
39
73
|
cropPadding: args.cropPadding,
|
|
40
74
|
style: args.style,
|
|
75
|
+
captureReport: args.captureReport,
|
|
41
76
|
});
|
|
42
77
|
const outPath = args.outPath ?? screenshotPath;
|
|
43
78
|
let rawPath = null;
|
|
@@ -46,6 +81,19 @@ export async function annotateScreenshot(args) {
|
|
|
46
81
|
await writeFile(rawPath, result.rawImage);
|
|
47
82
|
}
|
|
48
83
|
await writeFile(outPath, result.image);
|
|
84
|
+
const warningsOut = [...warnings, ...result.warnings];
|
|
85
|
+
await recordAnnotation(args.manifestPath ?? DEFAULT_MANIFEST_PATH, {
|
|
86
|
+
spec: args.spec ?? null,
|
|
87
|
+
test: args.test ?? null,
|
|
88
|
+
labels: (args.labels ?? []).filter((label) => Boolean(label)),
|
|
89
|
+
outPath,
|
|
90
|
+
rawPath,
|
|
91
|
+
width: result.width,
|
|
92
|
+
height: result.height,
|
|
93
|
+
drawnRects: result.drawnRects,
|
|
94
|
+
warnings: warningsOut,
|
|
95
|
+
timestamp: new Date().toISOString(),
|
|
96
|
+
});
|
|
49
97
|
return {
|
|
50
98
|
outPath,
|
|
51
99
|
rawPath,
|
|
@@ -53,15 +101,23 @@ export async function annotateScreenshot(args) {
|
|
|
53
101
|
height: result.height,
|
|
54
102
|
scale: result.scale,
|
|
55
103
|
drawnRects: result.drawnRects,
|
|
56
|
-
warnings:
|
|
104
|
+
warnings: warningsOut,
|
|
57
105
|
};
|
|
58
106
|
}
|
|
59
107
|
/**
|
|
60
108
|
* Register in cypress.config setupNodeEvents:
|
|
61
109
|
*
|
|
62
|
-
* setupNodeEvents(on) { registerAnnotateTasks(on); }
|
|
110
|
+
* setupNodeEvents(on, config) { registerAnnotateTasks(on, config); }
|
|
111
|
+
*
|
|
112
|
+
* Deliberately registers nothing but tasks. Cypress allows one handler per run
|
|
113
|
+
* event and silently keeps the last one registered, so taking `before:run` or
|
|
114
|
+
* `after:run` here would quietly stop a project's own handler from firing. The
|
|
115
|
+
* manifest and the job summary are driven from the task instead, which can be
|
|
116
|
+
* registered alongside anything.
|
|
117
|
+
*
|
|
118
|
+
* `config` is optional and currently unused.
|
|
63
119
|
*/
|
|
64
|
-
export function registerAnnotateTasks(on) {
|
|
120
|
+
export function registerAnnotateTasks(on, _config) {
|
|
65
121
|
on('task', {
|
|
66
122
|
annotateScreenshot: ((args) => annotateScreenshot(args)),
|
|
67
123
|
appendFailureRecord: ((args) => appendFailureRecord(args)),
|
package/dist/draw.d.ts
CHANGED
|
@@ -7,6 +7,9 @@ export interface ResolvedStyle {
|
|
|
7
7
|
dimOutside: number;
|
|
8
8
|
labelFontSize: number;
|
|
9
9
|
labelColor: string;
|
|
10
|
+
labelBackground: string;
|
|
11
|
+
labelFontFamily: string;
|
|
12
|
+
labelFontWeight: string | number;
|
|
10
13
|
}
|
|
11
14
|
export interface DrawSpec {
|
|
12
15
|
rect: PixelRect;
|
|
@@ -14,6 +17,7 @@ export interface DrawSpec {
|
|
|
14
17
|
shape: ShapeKind;
|
|
15
18
|
style: ResolvedStyle;
|
|
16
19
|
}
|
|
20
|
+
export declare const DEFAULT_FONT_STACK = "-apple-system, 'Helvetica Neue', Helvetica, Arial, sans-serif";
|
|
17
21
|
export declare function buildOverlaySvg(width: number, height: number, specs: DrawSpec[]): string;
|
|
18
22
|
export declare function compositeOverlay(screenshot: Buffer, svg: string): Promise<Buffer>;
|
|
19
23
|
//# sourceMappingURL=draw.d.ts.map
|
package/dist/draw.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"draw.d.ts","sourceRoot":"","sources":["../src/draw.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvD,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;
|
|
1
|
+
{"version":3,"file":"draw.d.ts","sourceRoot":"","sources":["../src/draw.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvD,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,GAAG,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,eAAO,MAAM,kBAAkB,kEACkC,CAAC;AAwLlE,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,CAsCxF;AAED,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAKvF"}
|
package/dist/draw.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import sharp from 'sharp';
|
|
2
|
-
const
|
|
2
|
+
export const DEFAULT_FONT_STACK = "-apple-system, 'Helvetica Neue', Helvetica, Arial, sans-serif";
|
|
3
3
|
function escapeXml(text) {
|
|
4
4
|
return text.replace(/[<>&'"]/g, (c) => {
|
|
5
5
|
switch (c) {
|
|
@@ -16,7 +16,9 @@ function round(n) {
|
|
|
16
16
|
}
|
|
17
17
|
/**
|
|
18
18
|
* Approximate rendered text width. librsvg gives us no measurement API, so the
|
|
19
|
-
* label pill is sized from an average glyph ratio and generous padding.
|
|
19
|
+
* label pill is sized from an average glyph ratio and generous padding. The
|
|
20
|
+
* ratio is tuned for the default sans stack, so a very wide or very narrow
|
|
21
|
+
* custom family will wrap a little early or a little late.
|
|
20
22
|
*/
|
|
21
23
|
function estimateTextWidth(text, fontSize) {
|
|
22
24
|
return text.length * fontSize * 0.58;
|
|
@@ -102,8 +104,9 @@ function labelShape(text, rect, style, imageWidth, imageHeight, centerOnAnchor =
|
|
|
102
104
|
.map((line, i) => `<tspan x="${round(pillX + padX)}" y="${round(firstBaseline + i * lineHeight)}">${escapeXml(line)}</tspan>`)
|
|
103
105
|
.join('');
|
|
104
106
|
return (`<rect x="${round(pillX)}" y="${round(pillY)}" width="${round(pillWidth)}" height="${round(pillHeight)}" ` +
|
|
105
|
-
`rx="${round(Math.min(pillHeight / 2, fontSize * 0.5))}" fill="${escapeXml(style.
|
|
106
|
-
`<text font-family="${
|
|
107
|
+
`rx="${round(Math.min(pillHeight / 2, fontSize * 0.5))}" fill="${escapeXml(style.labelBackground)}" />` +
|
|
108
|
+
`<text font-family="${escapeXml(style.labelFontFamily)}" font-size="${round(fontSize)}" ` +
|
|
109
|
+
`font-weight="${escapeXml(String(style.labelFontWeight))}" ` +
|
|
107
110
|
`fill="${escapeXml(style.labelColor)}" xml:space="preserve">${tspans}</text>`);
|
|
108
111
|
}
|
|
109
112
|
/** Greedy word wrap against the same glyph-ratio estimate used for the pill. */
|
package/dist/index.d.ts
CHANGED
|
@@ -1,23 +1,12 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
1
|
+
/**
|
|
2
|
+
* The driver-agnostic half of the plugin.
|
|
3
|
+
*
|
|
4
|
+
* Everything here works on a PNG somebody else captured, so it never opens a
|
|
5
|
+
* browser and never touches Cypress. The Cypress task goes through it, and so
|
|
6
|
+
* can anything else that can produce a screenshot, the page metrics that were
|
|
7
|
+
* true when it was taken, and rectangles in CSS pixels.
|
|
8
|
+
*/
|
|
9
|
+
export { annotateImage, resolveScale, resolveStyle, type AnnotateImageOptions, type AnnotateImageResult, type MeasuredTarget, } from './annotate-image.js';
|
|
6
10
|
export { buildOverlaySvg, compositeOverlay } from './draw.js';
|
|
7
|
-
export { collectInventory, renderInventory, type InventoryItem } from './inventory.js';
|
|
8
|
-
export { findingsToAnnotations, gatherReasonerInput, ReplayReasoner, SEVERITY_COLORS, type BugFinding, type Reasoner, type ReasonerInput, type ResolvedFinding, type ResolvedFindings, type Severity, } from './finder.js';
|
|
9
|
-
export { runBugHunt, type BugHuntOptions, type BugHuntResult } from './pipeline.js';
|
|
10
11
|
export type * from './types.js';
|
|
11
|
-
export interface CaptureOptions extends AnnotateOptions {
|
|
12
|
-
viewport?: {
|
|
13
|
-
width: number;
|
|
14
|
-
height: number;
|
|
15
|
-
};
|
|
16
|
-
deviceScaleFactor?: number;
|
|
17
|
-
headless?: boolean;
|
|
18
|
-
/** Extra settling time after load, in ms, for pages that animate in. */
|
|
19
|
-
settleMs?: number;
|
|
20
|
-
launch?: LaunchOptions;
|
|
21
|
-
}
|
|
22
|
-
export declare function captureAnnotated(url: string, annotations: Annotation[], options?: CaptureOptions): Promise<AnnotateResult>;
|
|
23
12
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC9D,mBAAmB,YAAY,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -1,60 +1,10 @@
|
|
|
1
|
-
import { annotate } from './annotate.js';
|
|
2
|
-
export { annotate } from './annotate.js';
|
|
3
|
-
export { annotateImage, resolveScale, } from './annotate-image.js';
|
|
4
|
-
export { measureElement, measureRegion, readPageMetrics } from './measure.js';
|
|
5
|
-
export { buildOverlaySvg, compositeOverlay } from './draw.js';
|
|
6
|
-
export { collectInventory, renderInventory } from './inventory.js';
|
|
7
|
-
// ClaudeReasoner is not re-exported here - import it from 'cypress-annotate/reasoner'
|
|
8
|
-
// instead. It is the only piece of this package with a real (non-type-only)
|
|
9
|
-
// dependency on @anthropic-ai/sdk; keeping it out of this barrel means every
|
|
10
|
-
// other export here stays usable with neither the SDK nor a peer install of it.
|
|
11
|
-
export { findingsToAnnotations, gatherReasonerInput, ReplayReasoner, SEVERITY_COLORS, } from './finder.js';
|
|
12
|
-
export { runBugHunt } from './pipeline.js';
|
|
13
1
|
/**
|
|
14
|
-
*
|
|
2
|
+
* The driver-agnostic half of the plugin.
|
|
15
3
|
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
* this function exists somewhere else in the same package.
|
|
21
|
-
*/
|
|
22
|
-
/**
|
|
23
|
-
* playwright is an optional peer, so a consumer who only uses the Cypress
|
|
24
|
-
* plugin or annotateImage never installs it. Reaching this without it is an
|
|
25
|
-
* ordinary mistake, and the bare ERR_MODULE_NOT_FOUND names an internal dist
|
|
26
|
-
* path rather than the two commands that fix it.
|
|
4
|
+
* Everything here works on a PNG somebody else captured, so it never opens a
|
|
5
|
+
* browser and never touches Cypress. The Cypress task goes through it, and so
|
|
6
|
+
* can anything else that can produce a screenshot, the page metrics that were
|
|
7
|
+
* true when it was taken, and rectangles in CSS pixels.
|
|
27
8
|
*/
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
return await import('playwright');
|
|
31
|
-
}
|
|
32
|
-
catch (error) {
|
|
33
|
-
if (error?.code === 'ERR_MODULE_NOT_FOUND') {
|
|
34
|
-
throw new Error('captureAnnotated() needs playwright, which is an optional peer dependency.\n' +
|
|
35
|
-
' npm install playwright\n' +
|
|
36
|
-
' npx playwright install chromium\n' +
|
|
37
|
-
'The Cypress plugin and annotateImage() do not need it.', { cause: error });
|
|
38
|
-
}
|
|
39
|
-
throw error;
|
|
40
|
-
}
|
|
41
|
-
}
|
|
42
|
-
export async function captureAnnotated(url, annotations, options = {}) {
|
|
43
|
-
let browser;
|
|
44
|
-
try {
|
|
45
|
-
const { chromium } = await loadChromium();
|
|
46
|
-
browser = await chromium.launch({ headless: options.headless ?? true, ...options.launch });
|
|
47
|
-
const context = await browser.newContext({
|
|
48
|
-
viewport: options.viewport ?? { width: 1280, height: 800 },
|
|
49
|
-
deviceScaleFactor: options.deviceScaleFactor ?? 2,
|
|
50
|
-
});
|
|
51
|
-
const page = await context.newPage();
|
|
52
|
-
await page.goto(url, { waitUntil: 'networkidle' });
|
|
53
|
-
if (options.settleMs)
|
|
54
|
-
await page.waitForTimeout(options.settleMs);
|
|
55
|
-
return await annotate(page, annotations, options);
|
|
56
|
-
}
|
|
57
|
-
finally {
|
|
58
|
-
await browser?.close();
|
|
59
|
-
}
|
|
60
|
-
}
|
|
9
|
+
export { annotateImage, resolveScale, resolveStyle, } from './annotate-image.js';
|
|
10
|
+
export { buildOverlaySvg, compositeOverlay } from './draw.js';
|
package/dist/types.d.ts
CHANGED
|
@@ -26,35 +26,14 @@ export interface PageMetrics {
|
|
|
26
26
|
documentHeight: number;
|
|
27
27
|
}
|
|
28
28
|
/**
|
|
29
|
-
*
|
|
30
|
-
*
|
|
29
|
+
* What the tool that took the screenshot says about it. Cypress hands this to
|
|
30
|
+
* `onAfterScreenshot` as `props.pixelRatio` and `props.scaled`.
|
|
31
31
|
*/
|
|
32
|
-
export interface
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
/** Percentages of the viewport (default) or of the whole document. */
|
|
38
|
-
basis?: 'viewport' | 'document';
|
|
39
|
-
}
|
|
40
|
-
export interface MeasuredElement {
|
|
41
|
-
/** Human-readable description of what was targeted. */
|
|
42
|
-
selector: string;
|
|
43
|
-
/** Whether this came from a selector match or a percentage region. */
|
|
44
|
-
source: 'selector' | 'region';
|
|
45
|
-
/** Viewport-relative, CSS px, including any ancestor-iframe offsets. */
|
|
46
|
-
viewportRect: CssRect;
|
|
47
|
-
/** Document-relative, CSS px (viewportRect + scroll, except for fixed elements). */
|
|
48
|
-
documentRect: CssRect;
|
|
49
|
-
/** True if the element or an ancestor is position:fixed, so it does not scroll. */
|
|
50
|
-
isFixed: boolean;
|
|
51
|
-
/** True if any part of the element is inside the current viewport. */
|
|
52
|
-
inViewport: boolean;
|
|
53
|
-
/** Extra frames the element was found inside, outermost first. */
|
|
54
|
-
framePath: string[];
|
|
55
|
-
tagName: string;
|
|
56
|
-
/** How many elements the selector matched. Anything above 1 is ambiguous. */
|
|
57
|
-
matchCount: number;
|
|
32
|
+
export interface CaptureReport {
|
|
33
|
+
/** Image pixels per CSS pixel at capture time. */
|
|
34
|
+
pixelRatio: number;
|
|
35
|
+
/** Whether the image was resized after capture. */
|
|
36
|
+
scaled: boolean;
|
|
58
37
|
}
|
|
59
38
|
export type ShapeKind = 'box' | 'circle' | 'arrow';
|
|
60
39
|
export interface AnnotationStyle {
|
|
@@ -70,46 +49,11 @@ export interface AnnotationStyle {
|
|
|
70
49
|
dimOutside?: number;
|
|
71
50
|
labelFontSize?: number;
|
|
72
51
|
labelColor?: string;
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
/**
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
selector?: string | string[];
|
|
80
|
-
/** Percentage-based fallback when no selector is available. */
|
|
81
|
-
region?: Region;
|
|
82
|
-
label?: string;
|
|
83
|
-
shape?: ShapeKind;
|
|
84
|
-
style?: AnnotationStyle;
|
|
85
|
-
}
|
|
86
|
-
export type ScreenshotMode = 'viewport' | 'fullPage' | 'element';
|
|
87
|
-
export interface AnnotateOptions {
|
|
88
|
-
/** Where to screenshot: the viewport, the whole document, or a crop around the element. */
|
|
89
|
-
mode?: ScreenshotMode;
|
|
90
|
-
/** For mode 'element', how much context to keep around the element, in CSS px. */
|
|
91
|
-
cropPadding?: number;
|
|
92
|
-
/**
|
|
93
|
-
* Scroll to the top before capturing a full-page screenshot. Chromium renders
|
|
94
|
-
* fixed elements once, at whatever scroll offset the capture starts from, so
|
|
95
|
-
* starting at the top is the only offset where fixed and static elements agree.
|
|
96
|
-
*/
|
|
97
|
-
scrollToTop?: boolean;
|
|
98
|
-
/** Bring the first annotated element into view before a viewport capture. */
|
|
99
|
-
scrollIntoView?: boolean;
|
|
100
|
-
style?: AnnotationStyle;
|
|
101
|
-
}
|
|
102
|
-
export interface AnnotateResult {
|
|
103
|
-
image: Buffer;
|
|
104
|
-
/** The same capture without the overlay, cropped identically. For verification. */
|
|
105
|
-
rawImage: Buffer;
|
|
106
|
-
/** Pixel dimensions of the returned image. */
|
|
107
|
-
width: number;
|
|
108
|
-
height: number;
|
|
109
|
-
metrics: PageMetrics;
|
|
110
|
-
elements: MeasuredElement[];
|
|
111
|
-
/** Final drawn rectangles, in image pixels. Useful for asserting alignment. */
|
|
112
|
-
drawnRects: PixelRect[];
|
|
113
|
-
warnings: string[];
|
|
52
|
+
/** Label pill background. Defaults to `color`, so one value themes both. */
|
|
53
|
+
labelBackground?: string;
|
|
54
|
+
/** CSS font-family for the label. */
|
|
55
|
+
labelFontFamily?: string;
|
|
56
|
+
/** CSS font-weight for the label. */
|
|
57
|
+
labelFontWeight?: string | number;
|
|
114
58
|
}
|
|
115
59
|
//# sourceMappingURL=types.d.ts.map
|
package/dist/types.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,MAAM,WAAW,OAAO;IACtB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,iFAAiF;AACjF,MAAM,WAAW,SAAS;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,8DAA8D;IAC9D,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,MAAM,WAAW,OAAO;IACtB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,iFAAiF;AACjF,MAAM,WAAW,SAAS;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,8DAA8D;IAC9D,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEnD,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4FAA4F;IAC5F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qCAAqC;IACrC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qCAAqC;IACrC,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACnC"}
|
package/package.json
CHANGED
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cypress-annotate",
|
|
3
|
-
"version": "
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "1.1.0",
|
|
4
|
+
"description": "Draw a box on exactly what failed. Every failed Cypress test gets an annotated screenshot, in CI, with no AI and no browser download.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"cypress",
|
|
7
7
|
"cypress-plugin",
|
|
8
8
|
"cypress-screenshot",
|
|
9
9
|
"screenshot",
|
|
10
|
+
"screenshot-annotation",
|
|
10
11
|
"annotate",
|
|
11
12
|
"annotation",
|
|
12
13
|
"test-failure",
|
|
@@ -16,15 +17,12 @@
|
|
|
16
17
|
"e2e-testing",
|
|
17
18
|
"visual-testing",
|
|
18
19
|
"test-reporting",
|
|
20
|
+
"test-artifacts",
|
|
19
21
|
"ci",
|
|
22
|
+
"github-actions",
|
|
20
23
|
"cypress-cloud",
|
|
21
24
|
"bounding-box",
|
|
22
|
-
"pixel-accurate"
|
|
23
|
-
"playwright",
|
|
24
|
-
"ai",
|
|
25
|
-
"llm",
|
|
26
|
-
"claude",
|
|
27
|
-
"agent"
|
|
25
|
+
"pixel-accurate"
|
|
28
26
|
],
|
|
29
27
|
"license": "MIT",
|
|
30
28
|
"author": "bidemiajala",
|
|
@@ -42,9 +40,6 @@
|
|
|
42
40
|
"type": "module",
|
|
43
41
|
"main": "dist/index.js",
|
|
44
42
|
"types": "dist/index.d.ts",
|
|
45
|
-
"bin": {
|
|
46
|
-
"cypress-annotate": "./dist/cli.js"
|
|
47
|
-
},
|
|
48
43
|
"exports": {
|
|
49
44
|
".": {
|
|
50
45
|
"types": "./dist/index.d.ts",
|
|
@@ -52,12 +47,6 @@
|
|
|
52
47
|
"require": "./dist/index.js",
|
|
53
48
|
"default": "./dist/index.js"
|
|
54
49
|
},
|
|
55
|
-
"./reasoner": {
|
|
56
|
-
"types": "./dist/claude-reasoner.d.ts",
|
|
57
|
-
"import": "./dist/claude-reasoner.js",
|
|
58
|
-
"require": "./dist/claude-reasoner.js",
|
|
59
|
-
"default": "./dist/claude-reasoner.js"
|
|
60
|
-
},
|
|
61
50
|
"./cypress/task": {
|
|
62
51
|
"types": "./dist/cypress/task.d.ts",
|
|
63
52
|
"import": "./dist/cypress/task.js",
|
|
@@ -80,9 +69,6 @@
|
|
|
80
69
|
},
|
|
81
70
|
"typesVersions": {
|
|
82
71
|
"*": {
|
|
83
|
-
"reasoner": [
|
|
84
|
-
"./dist/claude-reasoner.d.ts"
|
|
85
|
-
],
|
|
86
72
|
"cypress/task": [
|
|
87
73
|
"./dist/cypress/task.d.ts"
|
|
88
74
|
],
|
|
@@ -96,55 +82,37 @@
|
|
|
96
82
|
},
|
|
97
83
|
"files": [
|
|
98
84
|
"dist",
|
|
99
|
-
"src/browser",
|
|
100
85
|
"skills",
|
|
101
86
|
"DOCS",
|
|
102
87
|
"AGENTS.md",
|
|
88
|
+
"CHANGELOG.md",
|
|
103
89
|
"README.md",
|
|
104
90
|
"LICENSE"
|
|
105
91
|
],
|
|
106
92
|
"scripts": {
|
|
107
|
-
"build": "tsc -p tsconfig.build.json
|
|
93
|
+
"build": "tsc -p tsconfig.build.json",
|
|
108
94
|
"prepare": "npm run build",
|
|
109
|
-
"annotate": "tsx src/cli.ts",
|
|
110
|
-
"verify": "tsx scripts/verify.ts",
|
|
111
|
-
"verify:image": "tsx scripts/verify-image.ts",
|
|
112
|
-
"annotate-shot": "tsx scripts/annotate-shot.ts",
|
|
113
|
-
"test:reasoner": "tsx scripts/test-reasoner.ts",
|
|
114
95
|
"test:failure-selector": "tsx scripts/test-failure-selector.ts",
|
|
115
96
|
"test:svg-escaping": "tsx scripts/test-svg-escaping.ts",
|
|
116
|
-
"test:cypress": "tsx scripts/run-cypress.ts run --e2e --spec cypress/e2e/annotate.cy.ts",
|
|
97
|
+
"test:cypress": "tsx scripts/run-cypress.ts run --e2e --spec 'cypress/e2e/annotate.cy.ts,cypress/e2e/theme.cy.ts'",
|
|
117
98
|
"test:cypress-failures": "tsx scripts/test-cypress-failures.ts",
|
|
118
|
-
"explain-failures": "tsx scripts/explain-failures.ts",
|
|
119
99
|
"cypress:open": "tsx scripts/run-cypress.ts open",
|
|
120
|
-
"find-bugs": "tsx scripts/find-bugs.ts",
|
|
121
|
-
"demo": "tsx scripts/find-bugs.ts --url fixtures/buggy-checkout.html --replay fixtures/buggy-checkout.expected.json --out-dir out/bugs",
|
|
122
100
|
"typecheck": "tsc --noEmit"
|
|
123
101
|
},
|
|
124
102
|
"dependencies": {
|
|
125
|
-
"sharp": "^0.35.
|
|
103
|
+
"sharp": "^0.35.5"
|
|
126
104
|
},
|
|
127
105
|
"peerDependencies": {
|
|
128
|
-
"
|
|
129
|
-
"cypress": ">=13",
|
|
130
|
-
"playwright": "^1.56.1"
|
|
106
|
+
"cypress": ">=13"
|
|
131
107
|
},
|
|
132
108
|
"peerDependenciesMeta": {
|
|
133
|
-
"@anthropic-ai/sdk": {
|
|
134
|
-
"optional": true
|
|
135
|
-
},
|
|
136
109
|
"cypress": {
|
|
137
110
|
"optional": true
|
|
138
|
-
},
|
|
139
|
-
"playwright": {
|
|
140
|
-
"optional": true
|
|
141
111
|
}
|
|
142
112
|
},
|
|
143
113
|
"devDependencies": {
|
|
144
|
-
"@anthropic-ai/sdk": "^0.120.0",
|
|
145
114
|
"@types/node": "^24.10.1",
|
|
146
115
|
"cypress": "^15.19.0",
|
|
147
|
-
"playwright": "^1.56.1",
|
|
148
116
|
"tsx": "^4.20.7",
|
|
149
117
|
"typescript": "^5.9.3"
|
|
150
118
|
}
|
|
@@ -23,8 +23,8 @@ import { registerAnnotateTasks } from 'cypress-annotate/cypress/task';
|
|
|
23
23
|
|
|
24
24
|
export default defineConfig({
|
|
25
25
|
e2e: {
|
|
26
|
-
setupNodeEvents(on) {
|
|
27
|
-
registerAnnotateTasks(on);
|
|
26
|
+
setupNodeEvents(on, config) {
|
|
27
|
+
registerAnnotateTasks(on, config);
|
|
28
28
|
},
|
|
29
29
|
},
|
|
30
30
|
});
|
|
@@ -64,10 +64,17 @@ The offset used is the frame's content origin, so frames with their own border
|
|
|
64
64
|
and padding land correctly and a frame's internal scroll needs no correction.
|
|
65
65
|
Cross-origin frames cannot be measured and fail loudly.
|
|
66
66
|
|
|
67
|
-
Crop tight
|
|
67
|
+
Crop tight, which is what to use for a ticket attachment. Dimming the
|
|
68
|
+
surroundings is a separate `style` setting, since `crop` alone leaves them at
|
|
69
|
+
full brightness:
|
|
68
70
|
|
|
69
71
|
```ts
|
|
70
|
-
cy.annotate('#promo-apply', {
|
|
72
|
+
cy.annotate('#promo-apply', {
|
|
73
|
+
label: 'Escapes its card',
|
|
74
|
+
crop: true,
|
|
75
|
+
cropPadding: 220,
|
|
76
|
+
style: { dimOutside: 0.45 },
|
|
77
|
+
});
|
|
71
78
|
```
|
|
72
79
|
|
|
73
80
|
It overwrites the screenshot Cypress just recorded, so the annotated image is
|
|
@@ -88,7 +95,7 @@ cy.annotate('#grand-total-value', { label: 'Wrong total' }).then((result) => {
|
|
|
88
95
|
| --- | --- | --- |
|
|
89
96
|
| `label` | none | Box text. One string, or one per selector in order. |
|
|
90
97
|
| `name` | slug of first selector | Screenshot filename. |
|
|
91
|
-
| `crop` | `false` | Crop to the element,
|
|
98
|
+
| `crop` | `false` | Crop to the element, keeping `cropPadding` of context. |
|
|
92
99
|
| `cropPadding` | pipeline default | CSS px of context kept around the crop. |
|
|
93
100
|
| `shape` | `box` | Shape drawn around the target. |
|
|
94
101
|
| `style` | none | Colours, stroke width, label colour, dim strength. |
|
|
@@ -149,6 +156,17 @@ genuinely needed.
|
|
|
149
156
|
scroll, or click. A rectangle is only valid for the scroll position it was
|
|
150
157
|
measured at. Using `cy.annotate()` rather than hand-rolling this is the point.
|
|
151
158
|
|
|
159
|
+
**A viewport bigger than the headless window is captured only up to the
|
|
160
|
+
window's edge.** Headless browsers open at 1280x720, so `viewportWidth: 1920`
|
|
161
|
+
gets a screenshot of the viewport's top-left 1280x720 corner. The box still lands
|
|
162
|
+
in the right place, but anything past that corner has no box and a warning in
|
|
163
|
+
`annotations.json`. Size the window to match in `before:browser:launch`, with
|
|
164
|
+
`--window-size=1920,1080` for Chrome or `launchOptions.preferences.width` and
|
|
165
|
+
`height` for Electron. Headless Chrome also keeps 87px of its window height for
|
|
166
|
+
UI it never draws, so its default 1280x720 window captures only 1280x633, which
|
|
167
|
+
cuts the bottom off even Cypress's default 1000x660 viewport. Make the Chrome
|
|
168
|
+
window 87px taller than the viewport.
|
|
169
|
+
|
|
152
170
|
**Exact-colour assertions fail on macOS Electron.** Its capture applies a
|
|
153
171
|
colour-profile shift, so `#FF00E4` comes back as `rgb(234,51,221)`. Sample the
|
|
154
172
|
colour from the image rather than trusting the stylesheet.
|
|
@@ -157,9 +175,44 @@ colour from the image rather than trusting the stylesheet.
|
|
|
157
175
|
`ELECTRON_RUN_AS_NODE=1`, which VS Code's extension host does. Unset it before
|
|
158
176
|
running Cypress.
|
|
159
177
|
|
|
178
|
+
## Project-wide defaults
|
|
179
|
+
|
|
180
|
+
Colours and the other options are settable once, in cypress.config, so a team
|
|
181
|
+
does not repeat them at every call:
|
|
182
|
+
|
|
183
|
+
```ts
|
|
184
|
+
export default defineConfig({
|
|
185
|
+
env: {
|
|
186
|
+
annotate: {
|
|
187
|
+
style: { color: '#7C3AED', strokeWidth: 4, labelBackground: '#1F1F23' },
|
|
188
|
+
keepRaw: true,
|
|
189
|
+
},
|
|
190
|
+
},
|
|
191
|
+
});
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
Cypress serialises `env` into the browser, so the block reaches `cy.annotate()`
|
|
195
|
+
and the failure hook alike, and `CYPRESS_annotate='{"style":{...}}'` overrides it
|
|
196
|
+
for one CI job. Layers merge lowest first: built-in defaults, this block, the
|
|
197
|
+
options passed to a single call, then a per-target style. A misspelled key warns
|
|
198
|
+
rather than being silently ignored.
|
|
199
|
+
|
|
200
|
+
Style fields: `color`, `strokeWidth`, `padding`, `radius`, `dimOutside`,
|
|
201
|
+
`labelFontSize`, `labelColor`, `labelBackground`, `labelFontFamily`,
|
|
202
|
+
`labelFontWeight`. Run fields: `shape`, `crop`, `cropPadding`, `keepRaw`,
|
|
203
|
+
`scrollOffset`, `manifestPath`, `reportPath`.
|
|
204
|
+
|
|
205
|
+
## In CI
|
|
206
|
+
|
|
207
|
+
The annotated PNG overwrites the screenshot Cypress took, so it is what
|
|
208
|
+
`upload-artifact` collects and what `cypress run --record` sends to Cypress
|
|
209
|
+
Cloud. There is no Cloud API involved and nothing extra to configure.
|
|
210
|
+
|
|
211
|
+
Each run also writes `out/cypress/annotations.json`, one record per annotated
|
|
212
|
+
screenshot, and on GitHub Actions appends a table of it to the job summary.
|
|
213
|
+
|
|
160
214
|
## What this does not do
|
|
161
215
|
|
|
162
|
-
No LLM is involved in either path above, and no API key is needed.
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
install nothing by default. See `DOCS/pipeline.md` in the package.
|
|
216
|
+
No LLM is involved in either path above, and no API key is needed. For pointing
|
|
217
|
+
a model at a page so it works out what is wrong before anything gets drawn, see
|
|
218
|
+
the separate `annotate-agent` package.
|