cypress-annotate 1.1.0 → 1.2.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 CHANGED
@@ -50,7 +50,7 @@ say so explicitly, and they mean it.
50
50
  ```bash
51
51
  npm run typecheck
52
52
  npm run test:cypress # 14 cases, real Cypress
53
- npm run test:cypress-failures # 4 cases end to end, real Cypress
53
+ npm run test:cypress-failures # 8 cases end to end, real Cypress
54
54
  npm run test:failure-selector # 12 cases, no browser
55
55
  npm run test:svg-escaping # 9 cases
56
56
  ```
package/CHANGELOG.md CHANGED
@@ -3,6 +3,29 @@
3
3
  Notable changes to `cypress-annotate`. Each release's section here becomes the
4
4
  body of its GitHub release.
5
5
 
6
+ ## 1.2.0
7
+
8
+ ### Fixed
9
+
10
+ - The failure hook could fail its own `afterEach`, and Cypress then skips every
11
+ remaining test in the spec. A failing `cy.task` did it, whether annotating
12
+ threw or the report could not be written, and so did a `cy.get` that waited
13
+ out the whole command timeout when the page re-rendered between measuring and
14
+ scrolling. Each step now fails softly: the plain screenshot is kept, the
15
+ reason goes into the Cypress log and the record's `warnings`, and the next
16
+ test runs. A `fail` handler scoped to the hook catches anything else.
17
+ - The hook scrolls a below-the-fold element synchronously, on the element it
18
+ just measured, instead of querying for it again. It also honours
19
+ `scrollOffset` from `env.annotate` now, which it used to ignore.
20
+
21
+ ### Added
22
+
23
+ - A task named `annotateScreenshotSoft`, registered by `registerAnnotateTasks`
24
+ alongside the existing one. It returns `{ result }` or `{ error }` and never
25
+ throws. `appendFailureRecord` now returns the same shape. `cy.annotate()`
26
+ still uses `annotateScreenshot`, which throws, because an explicit call should
27
+ fail loudly.
28
+
6
29
  ## 1.1.0
7
30
 
8
31
  ### Fixed
package/DOCS/internals.md CHANGED
@@ -78,7 +78,7 @@ Playwright pipeline they were written for.
78
78
  ```bash
79
79
  npm install
80
80
  npm run test:cypress # cy.annotate and theming, 14 cases, real Cypress 15
81
- npm run test:cypress-failures # failed-test capture end to end, 4 cases, real Cypress 15
81
+ npm run test:cypress-failures # failed-test capture end to end, 8 cases, real Cypress 15
82
82
  npm run test:failure-selector # failed-test selector recovery, 12 cases, no browser
83
83
  npm run test:svg-escaping # SVG injection regression suite, 9 cases
84
84
  npm run typecheck
@@ -25,6 +25,11 @@ export interface FailureCaptureOptions {
25
25
  * Requires `screenshotOnRunFailure: false` in cypress.config.ts - otherwise
26
26
  * Cypress's own automatic failure screenshot and this hook's screenshot race,
27
27
  * and it becomes ambiguous which one the DOM measurement actually matches.
28
+ *
29
+ * The hook must never fail the run. A failing afterEach makes Cypress skip
30
+ * every remaining test in the spec, which is far worse than a missing box. So
31
+ * every step that can fail does so softly and leaves a warning, and a `fail`
32
+ * handler catches anything that still gets through.
28
33
  */
29
34
  export declare function registerFailureCapture(options?: FailureCaptureOptions): void;
30
35
  //# sourceMappingURL=failure-hook.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"failure-hook.d.ts","sourceRoot":"","sources":["../../src/cypress/failure-hook.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAA8B,MAAM,aAAa,CAAC;AAG/E,MAAM,WAAW,qBAAqB;IACpC,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,qBAA0B,GAAG,IAAI,CAyJhF"}
1
+ {"version":3,"file":"failure-hook.d.ts","sourceRoot":"","sources":["../../src/cypress/failure-hook.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAA8B,MAAM,aAAa,CAAC;AAG/E,MAAM,WAAW,qBAAqB;IACpC,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,qBAA0B,GAAG,IAAI,CAwKhF"}
@@ -1,7 +1,7 @@
1
1
  /// <reference types="cypress" />
2
2
  import { describeFailure, recoverFailure } from './failure-selector.js';
3
3
  import { collectInventory, measureTargets, readMetrics } from './measure-dom.js';
4
- import { isFullyVisible, scrollIntoViewIfNeeded } from './scroll-into-view.js';
4
+ import { isFullyVisible } from './scroll-into-view.js';
5
5
  import { readAnnotateConfig, DEFAULT_REPORT_PATH } from './config.js';
6
6
  function slugify(text) {
7
7
  return text.replace(/[^a-z0-9]+/gi, '-').replace(/^-+|-+$/g, '').toLowerCase().slice(0, 60) || 'failure';
@@ -27,11 +27,23 @@ function slugify(text) {
27
27
  * Requires `screenshotOnRunFailure: false` in cypress.config.ts - otherwise
28
28
  * Cypress's own automatic failure screenshot and this hook's screenshot race,
29
29
  * and it becomes ambiguous which one the DOM measurement actually matches.
30
+ *
31
+ * The hook must never fail the run. A failing afterEach makes Cypress skip
32
+ * every remaining test in the spec, which is far worse than a missing box. So
33
+ * every step that can fail does so softly and leaves a warning, and a `fail`
34
+ * handler catches anything that still gets through.
30
35
  */
31
36
  export function registerFailureCapture(options = {}) {
32
37
  afterEach(function () {
33
38
  if (this.currentTest?.state !== 'failed')
34
39
  return;
40
+ // cy.on binds to the current runnable, so this covers the hook and is gone
41
+ // by the next test. Returning false abandons the hook's remaining commands,
42
+ // which is why it is only the backstop.
43
+ cy.on('fail', (error) => {
44
+ Cypress.log({ name: 'annotate', message: `! Failure capture gave up: ${error.message}` });
45
+ return false;
46
+ });
35
47
  // Read inside the hook rather than at registration: the support file is
36
48
  // evaluated before Cypress has finished setting up env for the spec.
37
49
  const defaults = readAnnotateConfig();
@@ -59,36 +71,34 @@ export function registerFailureCapture(options = {}) {
59
71
  * viewport, so unlike cy.annotate() it may sit well below the fold - the
60
72
  * whole reason this exists is to point at a mismatch, so screenshotting a
61
73
  * viewport that never contains the mismatch would be a silent no-op box.
74
+ *
75
+ * The scroll is done synchronously on the element just measured. A cy.get
76
+ * here would re-query, and if the page re-rendered in between it would
77
+ * wait out the whole command timeout and then fail the hook.
62
78
  */
63
79
  function prepare(win) {
64
- const initial = recovered.selector && !recovered.elementNotFound ? measureTargets(win, [recovered.selector]) : null;
65
- const initialTarget = initial?.targets[0];
66
- const needsScroll = initialTarget?.found === true && initialTarget.rect !== undefined && !isFullyVisible(initialTarget.rect, win);
67
- if (!needsScroll) {
68
- const resolved = Boolean(initialTarget?.found && initialTarget.rect);
69
- return cy.wrap({
70
- target: initialTarget ?? null,
71
- resolved,
72
- inventory: resolved ? null : collectInventory(win),
73
- metrics: readMetrics(win),
74
- }, { log: false });
80
+ const selector = recovered.selector && !recovered.elementNotFound ? recovered.selector : null;
81
+ let target = selector ? measureTargets(win, [selector]).targets[0] : undefined;
82
+ if (selector && target?.found && target.rect && !isFullyVisible(target.rect, win)) {
83
+ const el = win.document.querySelector(selector);
84
+ if (el) {
85
+ const offset = defaults.scrollOffset ?? 120;
86
+ el.scrollIntoView({ block: 'start', inline: 'nearest', behavior: 'instant' });
87
+ win.scrollBy({ top: -offset, behavior: 'instant' });
88
+ // The rect from before the scroll is meaningless now.
89
+ target = measureTargets(win, [selector]).targets[0];
90
+ }
75
91
  }
76
- return scrollIntoViewIfNeeded(recovered.selector)
77
- .then(() => cy.window({ log: false }))
78
- .then((w) => {
79
- const remeasured = measureTargets(w, [recovered.selector]);
80
- const target = remeasured.targets[0];
81
- const resolved = Boolean(target?.found && target.rect);
82
- return {
83
- target: target ?? null,
84
- resolved,
85
- inventory: resolved ? null : collectInventory(w),
86
- metrics: readMetrics(w),
87
- };
88
- });
92
+ const resolved = Boolean(target?.found && target.rect);
93
+ return {
94
+ target: target ?? null,
95
+ resolved,
96
+ inventory: resolved ? null : collectInventory(win),
97
+ metrics: readMetrics(win),
98
+ };
89
99
  }
90
100
  cy.window({ log: false })
91
- .then((win) => prepare(win))
101
+ .then((win) => cy.wrap(prepare(win), { log: false }))
92
102
  .then(({ target, resolved, inventory, metrics }) => {
93
103
  let screenshotPath;
94
104
  let captureReport;
@@ -113,7 +123,7 @@ export function registerFailureCapture(options = {}) {
113
123
  if (!resolved) {
114
124
  return cy.wrap(null, { log: false });
115
125
  }
116
- return cy.task('annotateScreenshot', {
126
+ return cy.task('annotateScreenshotSoft', {
117
127
  screenshotPath,
118
128
  measurement: { metrics, targets: [target] },
119
129
  captureReport,
@@ -124,9 +134,17 @@ export function registerFailureCapture(options = {}) {
124
134
  manifestPath: defaults.manifestPath,
125
135
  spec: Cypress.spec.relative,
126
136
  test: testTitle,
127
- });
137
+ }, { log: false });
128
138
  })
129
- .then((annotateResult) => {
139
+ .then((soft) => {
140
+ const annotateResult = soft && 'result' in soft ? soft.result : null;
141
+ const warnings = [...(annotateResult?.warnings ?? [])];
142
+ if (soft && 'error' in soft) {
143
+ warnings.push(`Annotating the screenshot failed, so it was kept as it was: ${soft.error}`);
144
+ }
145
+ for (const warning of warnings) {
146
+ Cypress.log({ name: 'annotate', message: `! ${warning}` });
147
+ }
130
148
  const record = {
131
149
  spec: Cypress.spec.relative,
132
150
  test: testTitle,
@@ -152,10 +170,16 @@ export function registerFailureCapture(options = {}) {
152
170
  rect: item.rect,
153
171
  }))
154
172
  : null,
155
- warnings: annotateResult?.warnings ?? [],
173
+ warnings,
156
174
  timestamp: new Date().toISOString(),
157
175
  };
158
- return cy.task('appendFailureRecord', { reportPath, record }, { log: false });
176
+ return cy
177
+ .task('appendFailureRecord', { reportPath, record }, { log: false })
178
+ .then((written) => {
179
+ if ('error' in written) {
180
+ Cypress.log({ name: 'annotate', message: `! Could not write ${reportPath}: ${written.error}` });
181
+ }
182
+ });
159
183
  });
160
184
  });
161
185
  });
@@ -54,6 +54,16 @@ export interface AnnotateTaskResult {
54
54
  drawnRects: PixelRect[];
55
55
  warnings: string[];
56
56
  }
57
+ /**
58
+ * What the failure hook's tasks return in place of throwing. A task that throws
59
+ * fails the cy.task that called it, and inside the hook's afterEach that skips
60
+ * the rest of the spec.
61
+ */
62
+ export type SoftResult<T> = {
63
+ result: T;
64
+ } | {
65
+ error: string;
66
+ };
57
67
  export declare function annotateScreenshot(args: AnnotateTaskArgs): Promise<AnnotateTaskResult>;
58
68
  /**
59
69
  * Cypress's `on` is a set of overloads, one per event. Naming it precisely
@@ -1 +1 @@
1
- {"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/cypress/task.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAIvD;;;;;;GAMG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,cAAc,CAAC;IAC5B,0EAA0E;IAC1E,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,MAAM,CAAC,EAAE,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAClC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAwCD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA6E5F;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;AAI5D,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAQ9F"}
1
+ {"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/cypress/task.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAIvD;;;;;;GAMG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,cAAc,CAAC;IAC5B,0EAA0E;IAC1E,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,MAAM,CAAC,EAAE,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAClC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI;IAAE,MAAM,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAgD9D,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA6E5F;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;AAI5D,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAa9F"}
@@ -3,6 +3,14 @@ import { relative } from 'node:path';
3
3
  import { annotateImage } from '../annotate-image.js';
4
4
  import { appendFailureRecord, appendRecord } from './failure-report.js';
5
5
  import { DEFAULT_MANIFEST_PATH } from './config.js';
6
+ async function soft(work) {
7
+ try {
8
+ return { result: await work() };
9
+ }
10
+ catch (error) {
11
+ return { error: error instanceof Error ? error.message : String(error) };
12
+ }
13
+ }
6
14
  /**
7
15
  * Manifest paths already written to by this process. Cypress runs the whole of
8
16
  * `cypress run` in one Node process, so "first write of the process" is the
@@ -120,6 +128,9 @@ export async function annotateScreenshot(args) {
120
128
  export function registerAnnotateTasks(on, _config) {
121
129
  on('task', {
122
130
  annotateScreenshot: ((args) => annotateScreenshot(args)),
123
- appendFailureRecord: ((args) => appendFailureRecord(args)),
131
+ // The failure hook's two tasks never throw. cy.annotate() keeps the one
132
+ // above, which does, because an explicit call should fail loudly.
133
+ annotateScreenshotSoft: ((args) => soft(() => annotateScreenshot(args))),
134
+ appendFailureRecord: ((args) => soft(() => appendFailureRecord(args))),
124
135
  });
125
136
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cypress-annotate",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
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",
@@ -141,6 +141,10 @@ Where no selector can be recovered, such as an existence check or a
141
141
  of candidate elements, since the browser session is gone by the time anyone reads
142
142
  the report.
143
143
 
144
+ The hook can't fail the run. If annotating or writing the report goes wrong, the
145
+ plain screenshot is kept, the reason goes into the Cypress log and the record's
146
+ `warnings`, and the next test runs as normal.
147
+
144
148
  ## Traps
145
149
 
146
150
  **Don't use `fullPage: true` casually.** Cypress builds a full-page screenshot by