E2E screenshot testing

This maintainer guide explains how to run the Playwright visual-regression suite for the Material Design 3 demo. The suite covers every entry declared in demo/e2e/screenshot.spec.ts in both light and dark modes. Overlay variants are generated from the shared arrays in demo/src/app/overlay-types.ts.

Run the suite

Install the demo dependencies first:

cd demo
npm install

Then choose the command that matches the task:

npm run test:e2e          # Run the suite
npm run test:e2e:ui       # Open Playwright UI mode
npm run test:e2e:debug    # Run with the Playwright debugger
# For accepted PR baseline changes, comment /update-screenshots on the PR.

To reproduce the Linux environment used by CI, run the Docker variants from demo/:

npm run test:e2e:docker

The Docker commands use the Playwright image pinned in demo/package.json.

Review a failure

A screenshot mismatch can be a regression or an intentional visual change. Before updating a baseline:

1. Inspect the actual, expected, and diff images in demo/test-results/.
2. Check the affected route in both light and dark modes.
3. Confirm that the component change is intentional.
4. Request /update-screenshots on the PR and review the CI-generated commit.
   Local test:e2e:update / test:e2e:docker:update runs may be used for investigation
   in a disposable checkout; do not commit those local images as PR baselines.

The HTML report is written to demo/playwright-report/ and can be opened with:

npx playwright show-report

Add coverage

When adding a demo route or overlay variant, update demo/e2e/screenshot.spec.ts and regenerate the relevant baselines. Use the CI update workflow and review its committed visual diff.

Pull requests run the E2E workflow in .github/workflows/e2e-pull_request.yml; pushes to main run .github/workflows/e2e-main.yml.

Updating PR baselines

For an intentional PR appearance change, post /update-screenshots on that PR.
The workflow checks collaborator permission, generates images in the pinned
Playwright container and commits them to the PR branch. Fetch that commit before
continuing work. Inspect changed images in light/dark mode and keep unexpected
changes out of the baseline. Local screenshots are investigation artifacts, not
replacement baselines for this workflow.

Documentation previews

The demo Docs page is generated from docs/special-markup.md. After editing it,
run npm --prefix demo run docs:generate, commit the generated content and inspect
/main/docs in the running demo. prestart and prebuild also regenerate it.
Keep setup instructions in the linked user guides and preview markup in the source
Markdown; do not edit docs-content.generated.ts by hand.