u

README.md

@@ -42,7 +42,39 @@ npm run build    # bundle the dev harness (dist/)
 npm run lint
 ```
 
+## Screenshot testing
+
+Variations of the GUI elements are covered by **reference screenshot tests**
+(Playwright). Each variation is rendered by the static harness at
+[`/screenshots.html`](screenshots.html) (`src/dev/screenshots/ScreenshotHarness.jsx`)
+inside a `data-shot` section, and every section is compared against a committed
+reference image in `tests/screenshots/reference/`.
+
+```sh
+npm run test:screenshots           # compare against references
+npm run test:screenshots:update    # regenerate references (after intentional changes)
+```
+
+Notes:
+
+- The tests reuse the running dev server (`npm run dev` on port 5199) or start
+  it automatically.
+- Reference images are committed so visual regressions fail the run; the
+  actual + diff images land in `test-results/` (gitignored).
+- Animations are frozen during capture so spinners/transitions render
+  deterministically.
+- Interactive states (e.g. the `EditablePanelTile` edit/dirty rings) are driven
+  from the test itself, on top of the static sections.
+
+### Adding a new variation
+
+1. Add a `<Section id="…">` block to `ScreenshotHarness.jsx`.
+2. Add the id to the test in `tests/screenshot.spec.js` (or write a dedicated
+   interaction test).
+3. Run `npm run test:screenshots:update` to generate the new reference, review
+   it, and commit it.
+
 ## Future
 
-- Test cases (unit + component tests) with mock pages will be added under
-  `dev/` / `src/__tests__/` as they are written.
+- Unit + component tests with mock pages will be added under `dev/` /
+  `src/__tests__/` as they are written.