cypress-annotate 0.3.0 → 1.0.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 +142 -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 -329
- package/dist/annotate-image.d.ts +5 -0
- package/dist/annotate-image.d.ts.map +1 -1
- package/dist/annotate-image.js +16 -2
- package/dist/cypress/commands.d.ts +6 -1
- package/dist/cypress/commands.d.ts.map +1 -1
- package/dist/cypress/commands.js +13 -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 +10 -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 +36 -2
- package/dist/cypress/task.d.ts.map +1 -1
- package/dist/cypress/task.js +60 -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 +8 -28
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7 -37
- package/dist/types.d.ts +6 -72
- package/dist/types.d.ts.map +1 -1
- package/package.json +10 -39
- package/skills/cypress-annotate/SKILL.md +51 -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 -2
- package/dist/cli.d.ts.map +0 -1
- package/dist/cli.js +0 -74
- 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/AGENTS.md
CHANGED
|
@@ -17,23 +17,30 @@ else in the pipeline can recover from being wrong. This it cannot.
|
|
|
17
17
|
|
|
18
18
|
| Path | What it is |
|
|
19
19
|
| --- | --- |
|
|
20
|
-
| `src/cypress/` | The Cypress plugin.
|
|
21
|
-
| `src/annotate-image.ts`, `src/draw.ts` | The
|
|
22
|
-
| `src/
|
|
23
|
-
| `
|
|
24
|
-
| `scripts/` |
|
|
25
|
-
| `fixtures/` | Flat-coloured targets the
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
`./cypress
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
20
|
+
| `src/cypress/` | The Cypress plugin. Browser-side measurement plus the Node task. |
|
|
21
|
+
| `src/annotate-image.ts`, `src/draw.ts` | The engine. sharp and SVG, no browser, no Cypress. |
|
|
22
|
+
| `src/cypress/config.ts` | The `env.annotate` block. One place to add a new option. |
|
|
23
|
+
| `cypress/e2e/` | The suites that assert pixels. `theme.cy.ts` covers the config block. |
|
|
24
|
+
| `scripts/` | The non-browser suites and the Cypress runner. No test framework, plain scripts. |
|
|
25
|
+
| `fixtures/` | Flat-coloured targets the suites scan for. |
|
|
26
|
+
|
|
27
|
+
Four entry points: the root, and `./cypress/task`, `./cypress/commands`,
|
|
28
|
+
`./cypress/failure-hook`. They are listed one by one rather than wildcarded, so
|
|
29
|
+
the five other modules under `dist/cypress` stay internal, and the `package
|
|
30
|
+
install` CI job asserts that.
|
|
31
|
+
|
|
32
|
+
`sharp` is the only dependency. `cypress` is an optional peer.
|
|
33
|
+
|
|
34
|
+
**Do not put a top-level import of an optional peer beside anything the root
|
|
35
|
+
barrel re-exports.** That already shipped as a bug once, when `ClaudeReasoner`
|
|
36
|
+
sat next to a re-exported utility and made every root import throw
|
|
37
|
+
`ERR_MODULE_NOT_FOUND` for the Anthropic SDK, even for callers who never touched
|
|
38
|
+
it. An ES module evaluates a whole file's top-level code the moment anything is
|
|
39
|
+
imported from it.
|
|
40
|
+
|
|
41
|
+
The Playwright pipeline and the Claude reasoning layer used to live here. They
|
|
42
|
+
are now in the `annotate-agent` repo, which also owns the wider alignment
|
|
43
|
+
suites.
|
|
37
44
|
|
|
38
45
|
## Before you claim something works
|
|
39
46
|
|
|
@@ -42,24 +49,29 @@ say so explicitly, and they mean it.
|
|
|
42
49
|
|
|
43
50
|
```bash
|
|
44
51
|
npm run typecheck
|
|
45
|
-
npm run test:cypress #
|
|
46
|
-
npm run test:failure-selector # 12 cases, no browser
|
|
52
|
+
npm run test:cypress # 12 cases, real Cypress
|
|
47
53
|
npm run test:cypress-failures # 4 cases end to end, real Cypress
|
|
48
|
-
npm run test:
|
|
49
|
-
npm run
|
|
50
|
-
npm run verify:image # 10 cases, needs playwright chromium
|
|
54
|
+
npm run test:failure-selector # 12 cases, no browser
|
|
55
|
+
npm run test:svg-escaping # 9 cases
|
|
51
56
|
```
|
|
52
57
|
|
|
53
|
-
Eyeballing a screenshot does not prove pixel accuracy.
|
|
54
|
-
for a target's flat colour,
|
|
55
|
-
against the computed rect. Add a case there rather than looking at
|
|
58
|
+
Eyeballing a screenshot does not prove pixel accuracy. The Cypress suites scan
|
|
59
|
+
the image for a target's flat colour, recover its true pixel footprint, and
|
|
60
|
+
compare that against the computed rect. Add a case there rather than looking at
|
|
61
|
+
an image. The same trick proves the theme reaches the pixels: `theme.cy.ts`
|
|
62
|
+
samples the drawn stroke and fails if the config block did nothing.
|
|
63
|
+
|
|
64
|
+
## Releasing
|
|
65
|
+
|
|
66
|
+
Bump the version and add its `## <version>` section to `CHANGELOG.md` in the same
|
|
67
|
+
commit. The publish job uses that section as the GitHub release body and fails
|
|
68
|
+
the release if it is missing.
|
|
56
69
|
|
|
57
70
|
## Writing
|
|
58
71
|
|
|
59
72
|
No em dashes or en dashes, in code comments, docs, or commit messages. Use a
|
|
60
|
-
spaced hyphen, a comma, or parentheses. CI fails the build on one
|
|
61
|
-
|
|
62
|
-
program output that goes into a model's prompt.
|
|
73
|
+
spaced hyphen, a comma, or parentheses. CI fails the build on one, with no
|
|
74
|
+
exemptions.
|
|
63
75
|
|
|
64
76
|
Avoid the "it's not X, it's Y" construction, including the compressed trailing
|
|
65
77
|
form ("a mechanical pass, no rewording required").
|
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Notable changes to `cypress-annotate`. Each release's section here becomes the
|
|
4
|
+
body of its GitHub release.
|
|
5
|
+
|
|
6
|
+
## 1.0.0
|
|
7
|
+
|
|
8
|
+
The package shipped two products under one name. `cy.annotate()` and the failure
|
|
9
|
+
hook measure in the browser and composite in Node, with `sharp` as the only
|
|
10
|
+
thing that installs. Alongside them sat a Playwright-driven bug hunt with a
|
|
11
|
+
Claude reasoning layer, two optional peers and its own CLI, none of which ever
|
|
12
|
+
touched Cypress. Someone arriving from npm saw `playwright`, `ai`, `llm` and
|
|
13
|
+
`claude` in the keywords of a Cypress screenshot plugin.
|
|
14
|
+
|
|
15
|
+
That half now lives in
|
|
16
|
+
[annotate-agent](https://github.com/bidemiajala/annotate-agent), under the same
|
|
17
|
+
names. An install of this package is `sharp` and nothing else.
|
|
18
|
+
|
|
19
|
+
### Breaking
|
|
20
|
+
|
|
21
|
+
Everything here fails at import time rather than misbehaving at runtime.
|
|
22
|
+
|
|
23
|
+
- The `cypress-annotate` binary is gone. It drove the Playwright pipeline.
|
|
24
|
+
- `cypress-annotate/reasoner` is no longer exported.
|
|
25
|
+
- Twelve root exports moved out: `annotate`, `captureAnnotated`, `runBugHunt`,
|
|
26
|
+
`measureElement`, `measureRegion`, `readPageMetrics`, `collectInventory`,
|
|
27
|
+
`renderInventory`, `findingsToAnnotations`, `gatherReasonerInput`,
|
|
28
|
+
`ReplayReasoner`, `SEVERITY_COLORS`. What remains is `annotateImage`,
|
|
29
|
+
`resolveScale`, `resolveStyle`, `buildOverlaySvg` and `compositeOverlay`.
|
|
30
|
+
- These types moved out with them: `Annotation`, `Region`, `ScreenshotMode`,
|
|
31
|
+
`AnnotateOptions`, `AnnotateResult`, `MeasuredElement`.
|
|
32
|
+
- `src/browser/*.js`, the copy-pasteable MCP snippets, no longer ship here.
|
|
33
|
+
- `playwright` and `@anthropic-ai/sdk` are no longer peer dependencies.
|
|
34
|
+
|
|
35
|
+
**Migrating.** If you only use `cy.annotate()`, the failure hook, or
|
|
36
|
+
`annotateImage()`, upgrade and change nothing. If you use anything in the list
|
|
37
|
+
above, `npm install annotate-agent` and change the import path.
|
|
38
|
+
|
|
39
|
+
### Added
|
|
40
|
+
|
|
41
|
+
- **Theming from `cypress.config`.** An `env.annotate` block sets colours and
|
|
42
|
+
everything else once for the project, instead of repeating them at every call.
|
|
43
|
+
Cypress serialises `env` into the browser, so the one block reaches
|
|
44
|
+
`cy.annotate()` and the failure hook alike, and
|
|
45
|
+
`CYPRESS_annotate='{"style":{...}}'` overrides it for a single CI job. Layers
|
|
46
|
+
merge lowest first: built-in defaults, the config block, the options passed to
|
|
47
|
+
one call, then a per-target style. A misspelled key warns once per run rather
|
|
48
|
+
than being silently ignored.
|
|
49
|
+
- **Three style fields** that were hardcoded in `draw.ts`: `labelFontFamily`,
|
|
50
|
+
`labelFontWeight`, and `labelBackground`, which falls back to `color` so one
|
|
51
|
+
value still themes the outline and the label pill together.
|
|
52
|
+
- **A run manifest** at `out/cypress/annotations.json`, one record per annotated
|
|
53
|
+
screenshot with the spec and test it came from, the labels, the image paths,
|
|
54
|
+
the drawn rects and any warnings. `manifestPath` moves it.
|
|
55
|
+
- **A GitHub Actions job summary.** When `GITHUB_STEP_SUMMARY` is set, a table
|
|
56
|
+
of the manifest is appended to it, so what a run produced is readable on the
|
|
57
|
+
job page without downloading the artifact.
|
|
58
|
+
- `registerAnnotateTasks(on, config)` takes the Cypress config as an optional
|
|
59
|
+
second argument. The single-argument form still works.
|
|
60
|
+
|
|
61
|
+
### Changed
|
|
62
|
+
|
|
63
|
+
- Default appearance is unchanged, and `AnnotationStyle`'s new fields are
|
|
64
|
+
additive, so nothing that worked before looks different.
|
|
65
|
+
- The docs split. The README is half its previous length and leads with the
|
|
66
|
+
failure hook; the coordinate rules, the traps and the verification notes moved
|
|
67
|
+
to [DOCS/internals.md](DOCS/internals.md).
|
|
68
|
+
|
|
69
|
+
### Fixed
|
|
70
|
+
|
|
71
|
+
- `registerAnnotateTasks` no longer registers `before:run` or `after:run`.
|
|
72
|
+
Cypress allows one handler per run event and silently keeps the last one
|
|
73
|
+
registered, so taking them would have stopped a project's own handler from
|
|
74
|
+
firing, with no error and nothing in the output to explain it. Caught before
|
|
75
|
+
release by testing both registration orderings against a real run. The
|
|
76
|
+
manifest and the summary are driven from the task instead, which composes with
|
|
77
|
+
anything already in `setupNodeEvents`.
|
|
78
|
+
- `appendFailureRecord` creates the report's parent directory instead of failing
|
|
79
|
+
when it does not exist.
|
|
80
|
+
|
|
81
|
+
## 0.4.0
|
|
82
|
+
|
|
83
|
+
Shipped `src/cli.ts` as a `bin`, so it was reachable from an install rather than
|
|
84
|
+
only from inside the repo.
|
|
85
|
+
|
|
86
|
+
Running it without `playwright`, an optional peer nobody installing the Cypress
|
|
87
|
+
plugin would have, printed `ERR_MODULE_NOT_FOUND` naming an internal dist path,
|
|
88
|
+
which tells the reader nothing. `captureAnnotated` now catches that specific case
|
|
89
|
+
and names the two commands that fix it, so library callers get the better message
|
|
90
|
+
too. Both halves are covered in CI: `--help` works with no peers at all, and a
|
|
91
|
+
real invocation without playwright exits non-zero and explains itself.
|
|
92
|
+
|
|
93
|
+
## 0.3.0
|
|
94
|
+
|
|
95
|
+
`cy.annotate()` on an element inside an iframe measured against the wrong origin
|
|
96
|
+
and drew the box somewhere else on the page. The core engine had handled frames
|
|
97
|
+
from the beginning, with a documented rule about content origins, but
|
|
98
|
+
`src/cypress/measure-dom.ts` had no iframe handling at all. Cypress apps embed
|
|
99
|
+
checkout and payment frames constantly, so this was the most likely next bug
|
|
100
|
+
report.
|
|
101
|
+
|
|
102
|
+
A target can now be `{ frame, selector }`, with `frame` a single selector or an
|
|
103
|
+
array for nesting, outermost first. A bare string still means the top document
|
|
104
|
+
and an array of targets still means several at once, so nothing existing changed.
|
|
105
|
+
The offset used is the frame's content origin, `rect.left + borderLeftWidth +
|
|
106
|
+
paddingLeft`, so a frame with its own border and padding lands correctly, and a
|
|
107
|
+
frame scrolled internally needs no correction.
|
|
108
|
+
|
|
109
|
+
## 0.2.0
|
|
110
|
+
|
|
111
|
+
The `./cypress/*` wildcard made all eight files in `dist/cypress` public API when
|
|
112
|
+
only three are documented. Renaming any internal would technically have been a
|
|
113
|
+
breaking change. Replaced with three explicit subpaths, so the public surface is
|
|
114
|
+
now the three things the README tells people to import.
|
|
115
|
+
|
|
116
|
+
That also made the entry points visible to tooling, which uncovered a second
|
|
117
|
+
problem: node10 type resolution failed for every subpath. That is TypeScript's
|
|
118
|
+
older `moduleResolution: "node"`, which ignores exports maps entirely, and plenty
|
|
119
|
+
of Cypress projects still use it. `typesVersions` fixes it.
|
|
120
|
+
|
|
121
|
+
## 0.1.2
|
|
122
|
+
|
|
123
|
+
The exports map declared only an `import` condition, so `require()` of any entry
|
|
124
|
+
point failed with `ERR_PACKAGE_PATH_NOT_EXPORTED`. That breaks the documented
|
|
125
|
+
Cypress setup outright, because Cypress's stock webpack and Babel preprocessor
|
|
126
|
+
compiles the static import in `cypress/support/e2e.js` down to a `require`.
|
|
127
|
+
Reported from real use, and it affected the root and `./reasoner` as well as
|
|
128
|
+
`./cypress/*`.
|
|
129
|
+
|
|
130
|
+
## 0.1.1
|
|
131
|
+
|
|
132
|
+
Documented `annotateImage()`, which was the only export with no example anywhere.
|
|
133
|
+
The type names alone are not enough to call it: the arguments are positional
|
|
134
|
+
rather than an options bag, targets take `viewportRect` rather than `rect`, and
|
|
135
|
+
`PageMetrics` wants `viewportWidth`/`viewportHeight`/`documentWidth`/
|
|
136
|
+
`documentHeight` rather than a width and a height. All three were easy to get
|
|
137
|
+
wrong, which is what prompted the example.
|
|
138
|
+
|
|
139
|
+
## 0.1.0
|
|
140
|
+
|
|
141
|
+
First release. `cy.annotate()`, the automatic failure hook, and the coordinate
|
|
142
|
+
engine behind both.
|
|
Binary file
|
|
Binary file
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
# How this works underneath
|
|
2
|
+
|
|
3
|
+
The rules the coordinate engine follows, how they are verified, and what to know
|
|
4
|
+
before working on the repo. For using the plugin, see the
|
|
5
|
+
[README](../README.md).
|
|
6
|
+
|
|
7
|
+
## The coordinate rules
|
|
8
|
+
|
|
9
|
+
Four things have to line up, and each one is a separate opportunity to be a few
|
|
10
|
+
pixels off.
|
|
11
|
+
|
|
12
|
+
**1. `getBoundingClientRect()` is viewport-relative and post-transform.**
|
|
13
|
+
It already accounts for CSS transforms, internally scrolled ancestors, and
|
|
14
|
+
sub-pixel layout. It does *not* account for page scroll or iframes.
|
|
15
|
+
|
|
16
|
+
**2. Scroll offset applies only to a full-page capture, and only for elements
|
|
17
|
+
that scroll.** A viewport screenshot is in the same space the rect is already in,
|
|
18
|
+
so adding scroll there is the classic off-by-a-scroll bug. A full-page screenshot
|
|
19
|
+
is document space, so `rect + scrollX/scrollY`. A `position: fixed` element has
|
|
20
|
+
no document position at all, which the trap below covers.
|
|
21
|
+
|
|
22
|
+
**3. Device pixel ratio scales CSS px to image px, but verify it rather than
|
|
23
|
+
trusting it.** `resolveScale()` in
|
|
24
|
+
[src/annotate-image.ts](../src/annotate-image.ts) checks the produced image
|
|
25
|
+
against `cssWidth × devicePixelRatio`; if they disagree by more than 2px it
|
|
26
|
+
derives the real scale from the image and records a warning. Stroke widths, font
|
|
27
|
+
sizes and padding are all specified in CSS px and multiplied by that same scale,
|
|
28
|
+
so annotations look identical at dpr 1, 2 and 3.
|
|
29
|
+
|
|
30
|
+
**4. Iframes add their content origin, not their border box.** The offset is
|
|
31
|
+
`iframeRect.left + borderLeftWidth + paddingLeft`. A frame's own internal scroll
|
|
32
|
+
needs no correction, since a rect measured inside the frame is already relative
|
|
33
|
+
to that frame's viewport.
|
|
34
|
+
|
|
35
|
+
### The fixed-element trap
|
|
36
|
+
|
|
37
|
+
Chromium's full-page capture paints `position: fixed` elements **once**, at
|
|
38
|
+
whatever scroll offset the capture started from. So for a fixed element there is
|
|
39
|
+
no correct "document position", and adding scroll to it puts the box thousands of
|
|
40
|
+
pixels away from the thing it should mark.
|
|
41
|
+
|
|
42
|
+
The engine detects fixed ancestry during measurement, skips the scroll correction
|
|
43
|
+
for those elements, and emits a warning so the caller knows why. Capturing the
|
|
44
|
+
viewport, which is the default, sidesteps the problem entirely.
|
|
45
|
+
|
|
46
|
+
## How alignment is verified
|
|
47
|
+
|
|
48
|
+
Eyeballing a screenshot does not prove pixel accuracy, so nothing here relies on
|
|
49
|
+
it.
|
|
50
|
+
|
|
51
|
+
Every target in [fixtures/test-page.html](../fixtures/test-page.html) is painted a
|
|
52
|
+
flat, unique colour with no radius, border or shadow, so the pixels it paints are
|
|
53
|
+
exactly its border box. The Cypress suite scans the un-annotated capture for that
|
|
54
|
+
colour, recovers the element's true pixel footprint, and compares it against the
|
|
55
|
+
rect the engine computed. Three checks close the loop on every case: the box
|
|
56
|
+
centre must not be page background, the painted region must match the drawn rect,
|
|
57
|
+
and the painted region's CSS size must match the element's own
|
|
58
|
+
`getBoundingClientRect()` read independently through jQuery. Tolerance is 2px.
|
|
59
|
+
|
|
60
|
+
The same technique proves theming reaches the pixels.
|
|
61
|
+
[cypress/e2e/theme.cy.ts](../cypress/e2e/theme.cy.ts) samples the drawn stroke
|
|
62
|
+
out of the finished image rather than trusting the options object it was built
|
|
63
|
+
from, so a config block that silently does nothing fails the suite.
|
|
64
|
+
|
|
65
|
+
Residual drift is sub-pixel and comes from scanner quantisation. `#target-top`
|
|
66
|
+
sits at y=147.375 CSS px, so its top edge falls on device pixel 294.75 and the
|
|
67
|
+
partially covered row 294 fails the colour test. Its x is an integer and the
|
|
68
|
+
horizontal delta is exactly 0.00. That 0.5-device-pixel signature shows up on
|
|
69
|
+
every case, always on the axis with a fractional coordinate.
|
|
70
|
+
|
|
71
|
+
The wider alignment suites, which drive a browser directly and cover dpr 1/2/3,
|
|
72
|
+
rescaled captures and the percentage-region fallback, live in
|
|
73
|
+
[annotate-agent](https://github.com/bidemiajala/annotate-agent) along with the
|
|
74
|
+
Playwright pipeline they were written for.
|
|
75
|
+
|
|
76
|
+
## Working on this repo
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
npm install
|
|
80
|
+
npm run test:cypress # cy.annotate and theming, 12 cases, real Cypress 15
|
|
81
|
+
npm run test:cypress-failures # failed-test capture end to end, 4 cases, real Cypress 15
|
|
82
|
+
npm run test:failure-selector # failed-test selector recovery, 12 cases, no browser
|
|
83
|
+
npm run test:svg-escaping # SVG injection regression suite, 9 cases
|
|
84
|
+
npm run typecheck
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
CI runs the two Cypress suites on Electron, Chrome and Firefox. Firefox is the
|
|
88
|
+
one that can falsify the Chromium-specific claims in the coordinate rules, which
|
|
89
|
+
is why it is there.
|
|
90
|
+
|
|
91
|
+
**A pitfall if you write your own chai assertions against `err.expected` and
|
|
92
|
+
`err.actual`:** they hold chai's own quoted rendering of the value rather than
|
|
93
|
+
the raw value. `.should('have.text', 'X')` puts `'X'` into `err.expected` with
|
|
94
|
+
the quote marks included. An early version of the failure hook got that wrong,
|
|
95
|
+
and it was fixed by running a real Cypress failure and inspecting the field.
|
|
96
|
+
|
|
97
|
+
**If Cypress fails to start with "bad option: --no-sandbox"**, something in your
|
|
98
|
+
environment has set `ELECTRON_RUN_AS_NODE=1`, which VS Code's extension host
|
|
99
|
+
does. Cypress's binary is Electron, so it starts as plain Node and rejects
|
|
100
|
+
Chromium flags. `npm run test:cypress` goes through
|
|
101
|
+
[scripts/run-cypress.ts](../scripts/run-cypress.ts), which strips that variable.
|
|
102
|
+
|
|
103
|
+
**Worth knowing for any visual assertion in Cypress:** Electron's macOS capture
|
|
104
|
+
applies a colour-profile shift. A fixture painted `#FF00E4` comes back as
|
|
105
|
+
`rgb(234,51,221)`. Exact-colour assertions against your stylesheet will fail, so
|
|
106
|
+
the suite samples the rendered colour out of the image and compares by distance.
|
|
107
|
+
|
|
108
|
+
## Why the plugin registers no run events
|
|
109
|
+
|
|
110
|
+
Cypress allows one handler per run event and silently keeps the last one
|
|
111
|
+
registered. So `on('after:run', ...)` inside `registerAnnotateTasks` would stop
|
|
112
|
+
a project's own `after:run` from ever firing, with no error and nothing in the
|
|
113
|
+
output to explain it. Verified both directions against a real run before this
|
|
114
|
+
was ruled out.
|
|
115
|
+
|
|
116
|
+
The manifest and the GitHub job summary are therefore driven from the task.
|
|
117
|
+
`cypress run` is one Node process, so the first write to a manifest path in that
|
|
118
|
+
process is the run boundary: it truncates, and everything after it appends. The
|
|
119
|
+
job summary gets its table header on the same first write and a row per
|
|
120
|
+
annotation after that. Neither needs an event, so `registerAnnotateTasks` only
|
|
121
|
+
ever registers tasks and composes with whatever else is in `setupNodeEvents`.
|
|
122
|
+
|
|
123
|
+
In `cypress open` each spec run reuses the same process, so the manifest keeps
|
|
124
|
+
appending until the runner is restarted.
|
|
125
|
+
|
|
126
|
+
## Publishing and packaging
|
|
127
|
+
|
|
128
|
+
**The build runs automatically on install.** This repo ships TypeScript source
|
|
129
|
+
and `dist/` is gitignored, so npm's `prepare` script runs `tsc` on install.
|
|
130
|
+
Confirmed by installing the packed tarball into an empty project and importing
|
|
131
|
+
each entry point, which is what the `package install` CI job does on every run.
|
|
132
|
+
|
|
133
|
+
`cypress` is an optional peer, so npm installs nothing for you and stays quiet
|
|
134
|
+
about it. `sharp` is the only hard dependency.
|
|
135
|
+
|
|
136
|
+
That separation was worth proving. An early version put `ClaudeReasoner` in the
|
|
137
|
+
same file as several utility functions the root barrel re-exported, so importing
|
|
138
|
+
anything at all from `'cypress-annotate'`, even `annotateImage`, threw
|
|
139
|
+
`ERR_MODULE_NOT_FOUND` for `@anthropic-ai/sdk` whether or not you ever touched
|
|
140
|
+
the reasoner. Reading the code would never have shown it, because an ES module
|
|
141
|
+
evaluates a whole file's top-level code the moment anything is imported from it,
|
|
142
|
+
peer-optional or otherwise. What caught it was installing the built package into
|
|
143
|
+
an isolated scratch project with no peers present and importing each entry point
|
|
144
|
+
for real. CI now does that on every push, and the `./cypress/*` exports are
|
|
145
|
+
listed one by one rather than wildcarded, so the five internal modules under
|
|
146
|
+
`dist/cypress` stay unreachable.
|
|
147
|
+
|
|
148
|
+
Publishing is npm trusted publishing over OIDC, guarded on the version in
|
|
149
|
+
`package.json` being new, so an ordinary merge that does not bump the version is
|
|
150
|
+
a no-op. The trusted publisher names this repo and this workflow file, `ci.yml`,
|
|
151
|
+
so renaming that file breaks publishing until the npm setting is updated.
|