e2e-screenshots

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                              # or npm install
npx playwright install chromium     # browsers are NOT vendored

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

# 1. Clear the old set so folders for renamed/deleted tests disappear
#    instead of lingering as stale, never-updated documentation.
rm -rf e2e/screenshots/*/

# 2. Run the whole suite with capture on. Serial, single worker.
E2E_SCREENSHOTS=1 npm run test:e2e

# 3. Stage: -f because e2e/screenshots/*/ is gitignored (so ordinary
#    local runs never dirty the tree), -A so step 1's deletions of
#    now-obsolete folders are staged too.
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*/          # optional, for renames
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

1. npm run test — unit suite green.
2. npm run build — tsc -b + Vite clean.
3. npm run lint — no new problems.
4. 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).