init project

test/regressions/README.md

@@ -0,0 +1,56 @@
+# Visual regression testing
+
+Visual regression tests are split into two parts:
+
+1. The rendered UI (short: fixture)
+2. Instrumentation of that UI
+
+## Rendered UI
+
+The composition of all tests happens in `./index.js`.
+The rendered UI is either:
+
+1. located inside a separate file in `./fixtures` and written as a React component.
+
+   Here is an [example](https://github.com/mui/material-ui/blob/814fb60bbd8e500517b2307b6a297a638838ca89/test/regressions/tests/Menu/SimpleMenuList.js#L6-L16) with the `Menu` component.
+
+2. a demo from `docs/data`
+
+   By default all demos are included.
+   We exclude demos if they are redundant or flaky etc.
+   The logic for this exclusion is handled (like the composition) in `./index.js`
+
+If you introduce new behavior, prefer adding a demo to the documentation to solve documentation and testing with one file.
+If you're adding a new test prefer a new component instead of editing existing files since that might unknowingly alter existing tests.
+
+## Instrumentation
+
+### Manual
+
+`pnpm test:regressions:dev` will build all fixtures and render an overview page that lists all fixtures.
+This can be used to debug individual fixtures.
+By default, a devtools-like view is shown that can be disabled by appending `#no-dev` to the URL, for example `http://localhost:5001/docs-customization-typography/CustomResponsiveFontSizes#no-dev` or forced by appending `#dev` to the URL, for example `http://localhost:5001/docs-customization-typography/CustomResponsiveFontSizes#dev`.
+
+### Automatic
+
+We're using [`playwright`](https://playwright.dev) to iterate over each fixture and take a screenshot.
+It allows catching regressions like this one:
+
+![before](/test/docs-regressions-before.png)
+![diff](/test/docs-regressions-diff.png)
+
+Screenshots are saved in `./screenshots/$BROWSER_NAME/`.
+Each test tests only a single fixture.
+A fixture can be loaded with `await renderFixture(fixturePath)`, for example `renderFixture('FocusTrap/OpenFocusTrap')`.
+
+## Commands
+
+For development `pnpm test:regressions:dev` and `pnpm test:regressions:run --watch` in separate terminals is recommended.
+
+| command                        | description                                                                                                           |
+| :----------------------------- | :-------------------------------------------------------------------------------------------------------------------- |
+| `pnpm test:regressions`        | Full run                                                                                                              |
+| `pnpm test:regressions:dev`    | Prepares the fixtures to be able to test in watchmode                                                                 |
+| `pnpm test:regressions:run`    | Runs the tests (requires `pnpm test:regressions:dev` or `pnpm test:regressions:build`+`pnpm test:regressions:server`) |
+| `pnpm test:regressions:build`  | Builds the vite bundle for viewing the fixtures                                                                       |
+| `pnpm test:regressions:server` | Serves the fixture bundle.                                                                                            |