Marcos Paulo
48c31dc1b3
Ten git worktrees each carried their own 225 MB node_modules (1.1 GB across five) and paid 11s per `npm ci`. pnpm hardlinks from a shared store: the same five worktrees cost ~250 MB total, and a fresh install is 4s. What changed beyond the mechanical rename: - `overrides` moved to `pnpm-workspace.yaml`. pnpm 11 does not read the `pnpm` field in package.json *or* npm's top-level `overrides`, and it fails silently — the vite/defu/language-server pins would have quietly stopped applying. - Build scripts are blocked by default in pnpm; esbuild and sharp are allowed explicitly via `allowBuilds` (renamed from `onlyBuiltDependencies` in 11). - `packageManager` + `engines` pin the toolchain. - gate.sh rejects a package-lock.json/yarn.lock/bun.lock outright, so an agent running `npm install` out of habit fails loudly instead of building a second, divergent dependency tree. - CI bootstraps pnpm with `npm install --global pnpm@11.25.0` rather than corepack (unbundled as of Node 25) or pnpm/action-setup (this self-hosted act-runner has never run a job; fetching a third-party action is not something to discover on the first one). Two pre-existing CI bugs fixed while in the file: - the gate installed with `npm install --package-lock=false`, which discarded the lockfile the previous session had just fixed. - the visual-regression step imported `playwright`, which is not a dependency, and `visual-regression.mjs` has no compare mode anyway — in CI it overwrote its own baselines and passed unconditionally. Removed with a comment; it comes back when it can diff. The `publish` job is now manual (`workflow_dispatch`). During the migration dist/ holds three HTML files against the live pages branch's ten, so publishing on every push to main would take the site down to a stub. Restore at task 20. HANDOVER.md's incident log still says npm where it describes what happened at the time; that is history, not a missed rename. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
74 lines
2.4 KiB
Markdown
74 lines
2.4 KiB
Markdown
---
|
|
name: visual-regression
|
|
description:
|
|
Prove a refactor did not change how the site looks. Use before and after any
|
|
page migration, token consolidation, or breakpoint change on ai-for-dummies.
|
|
---
|
|
|
|
# Visual regression
|
|
|
|
"Maintain the same styles" is a testable claim. Test it.
|
|
|
|
## Capture
|
|
|
|
The repo already has a Playwright pattern (`scripts/inspect.py`). Extend it
|
|
rather than inventing one.
|
|
|
|
```python
|
|
from playwright.sync_api import sync_playwright
|
|
ROUTES = ['/', '/full-guide/', '/summary/', '/models/', '/agents/',
|
|
'/skills/', '/rules/', '/skills-review/',
|
|
'/hands-on/starter/', '/hands-on/rules/']
|
|
WIDTHS = [560, 800, 1100, 1600]
|
|
|
|
with sync_playwright() as p:
|
|
browser = p.chromium.launch(headless=True)
|
|
for route in ROUTES:
|
|
for w in WIDTHS:
|
|
page = browser.new_page(viewport={'width': w, 'height': 900})
|
|
page.goto(f'{BASE}{route}', wait_until='networkidle')
|
|
page.screenshot(path=f'{OUT}/{route.strip("/").replace("/","_") or "index"}-{w}.png',
|
|
full_page=True)
|
|
page.close()
|
|
browser.close()
|
|
```
|
|
|
|
Run once against the vanilla site (`pnpm run serve`), once against
|
|
`pnpm run preview`. Keep both sets.
|
|
|
|
## Compare
|
|
|
|
```bash
|
|
for f in before/*.png; do
|
|
compare -metric AE "$f" "after/$(basename $f)" null: 2>&1 # ImageMagick
|
|
echo " <- $(basename $f)"
|
|
done
|
|
```
|
|
|
|
Pixel-exact is not the bar — antialiasing differs. Judge by eye where the metric
|
|
is non-trivial, and attach the pair to the task report.
|
|
|
|
## The three widths that catch the most
|
|
|
|
- **560px** — where the 16 ad-hoc breakpoints collapse to `--bp-sm`. Highest
|
|
risk in the whole migration.
|
|
- **800px** — the most common existing breakpoint; layout flips here.
|
|
- **1600px** — `min-width` rules that only fire on large screens are the ones
|
|
nobody notices are broken.
|
|
|
|
Also screenshot at the **old** breakpoint values you removed (520, 530, 600,
|
|
620, 720, 850, 880, 900), not just the new ones. Regressions hide exactly there.
|
|
|
|
## What a real difference looks like
|
|
|
|
Expect and accept: sub-pixel text shifts, antialiasing.
|
|
|
|
Investigate: anything that moves by more than ~2px, any colour change (that is a
|
|
token bug), any element that appears or disappears (that is content loss — stop
|
|
and check the snapshot diff).
|
|
|
|
## Reduced motion
|
|
|
|
Capture one pass with `prefers_reduced_motion='reduce'`. Animations must land in
|
|
their correct end state, not vanish.
|