| name | e2e-screenshots |
| description | Run the Solid.Drive Playwright end-to-end suite locally (offline, against the bundled Community Solid Server) with documentation screenshot capture turned on, then refresh and stage e2e/screenshots/ before a commit. Use whenever the UI changed and the committed workflow screenshots need to catch up, or when asked to run the e2e tests, regenerate screenshots, or check e2e before committing. CI no longer captures or commits screenshots — this is the only place they are produced. |
e2e screenshots — run the suite offline and refresh the docs
e2e/screenshots/<test-name>/NN-label.png is the picture-by-picture
documentation of every user workflow, captured straight from the
Playwright suite. It used to be regenerated by the Playwright Tests
GitHub Action, which committed it back to main; that roughly doubled
the job and burned a lot of Actions minutes for output that only changes
when the UI does. CI now runs the suite with capture off, and never
touches e2e/screenshots/. Refreshing it is a local pre-commit step —
this skill.
When to run it
Run the capture pass before committing when the change can alter what a
user sees: components, CSS/themes, layout, routing, locale strings, or
the e2e specs themselves (test titles decide folder names). A pure
refactor, a docs edit, or a change behind a flag needs nothing.
If in doubt, run the affected specs only (see "Targeted refresh") — a
full pass is ~20–40 minutes.
Prerequisites (one-time, needs network)
npm ci
npx playwright install chromium
Everything after this is offline: playwright.config.ts boots Vite on
:5173 and a local Community Solid Server on :3001, seeded from
e2e/fixtures/seed.json. No external identity provider, no CDN, no
network egress — the suite is fully self-contained.
Full refresh
rm -rf e2e/screenshots/*/
E2E_SCREENSHOTS=1 npm run test:e2e
git add -A -f e2e/screenshots
git status --short e2e/screenshots | head -50
Then commit the screenshots with the change they document — same commit
if the diff is small, otherwise a companion
docs(e2e): refresh workflow screenshots commit.
Run step 2 in the background and poll it; do not block a foreground
tool call on a 20–40 minute run.
Targeted refresh
Faster, and the right default when one flow changed:
rm -rf e2e/screenshots/*onedrive-layout*/
E2E_SCREENSHOTS=1 npx playwright test e2e/tests/onedrive-layout.spec.ts
git add -A -f e2e/screenshots
-g "<test title>" narrows further. Folder names are the spec file plus
the test title, slugified (e2e/helpers/screenshots.ts → testFolderName).
Gotchas
E2E_SCREENSHOTS=1 is the only switch. Capture is off otherwise —
CI is deliberately ignored, so no workflow can turn the expensive
capture back on by accident.- Stale dev servers get reused.
reuseExistingServer is on locally,
so a Vite or CSS instance you already have running on :5173 / :3001
serves the run — possibly with pre-change code or a dirty pod. Stop
them first if the screenshots look wrong.
- Never commit a red run. Failures leave a half-written set; fix the
test first, then recapture.
- Binary churn. Fonts and antialiasing differ per machine, so the
first refresh on a given machine rewrites every PNG it touches even
where the UI is unchanged (the committed set was originally rendered
on GitHub's runners). Expect one large transition diff; after that,
if
git status shows dozens of touched files for a one-screen change,
stage only the folders that genuinely moved rather than the whole tree.
- Failure debris is separate:
test-results/ and
playwright-report/ are gitignored and never staged here.
Pre-commit checklist
npm run test — unit suite green.npm run build — tsc -b + Vite clean.npm run lint — no new problems.E2E_SCREENSHOTS=1 npm run test:e2e — e2e green and screenshots
refreshed, staged with git add -A -f e2e/screenshots.
Reference
e2e/README.adoc — suite layout, helpers, seeded accounts.e2e/screenshots/README.adoc — naming and capture mechanics.e2e/helpers/screenshots.ts — screenshotsEnabled, shot, step..github/workflows/playwright.yml — what CI does (and no longer does).
