Design Tests
Status: Stable
@qs/design-tests is visual regression testing for any URL. It captures screenshots, compares them against a committed baseline, and generates an HTML report naming every image that moved.
It is framework-agnostic. Storybook stories are discovered automatically, and an arbitrary list of pages works the same way, so the same tool covers a component library and a CMS site.
What it gives you
- Any URL — Storybook, a deployed site, a static build, or a hand-written page list
- Many projects from one config — each with its own URL, viewports, ignore list and stability settings
- Parallel execution — a browser worker pool; 32 workers run roughly 16 times faster than sequential
- Stability controls — network-idle and page-busy waits, disabled animations, reduced motion, element masking, configurable delays and retries
- Deployment attribution — the report names the commit under test and the commit each baseline came from
- Self-hosted — pixelmatch diffs and a reg-cli report, with no external service
Start here
New to the idea, or explaining it to someone who is? Read what design tests are — it covers the concept and its value without assuming a developer reader.
Ready to install? Getting Started takes you from an empty project to a first report:
pnpm add -D @qs/design-tests
pnpm add -D -E playwright@1.32.3
pnpm exec playwright install chromium
Pin Playwright to an exact version and treat that pin as part of the baseline. The browser build determines rendered pixels, so a different Playwright version can render the same page differently and report every image as changed.
Then write a .designTests.js beside your package.json and run:
pnpm exec design-tests run --config .designTests.js --all
The first run finds no baseline and writes one for every test. Review those images before committing them — they become the standard every later run is judged against.
Where to go next
| You want to | Read |
|---|---|
| Install and get a first report | Getting Started |
| Look up a command or flag | CLI Reference |
| Configure several sites or Storybooks | Adding Projects |
| Review, update or regenerate baselines | Baseline Management |
| Stop a flaky test from flapping | Stabilization Playbook |
| Wire it into Jenkins | Jenkins Resource Root URL |
A note on maturity
These pages track the develop branch, not the version you have installed. They are published from the library's development branch, so they can describe behaviour that is not yet in any released package. The library is in its release-candidate phase, which is the point: the documentation runs slightly ahead, and feedback on it is wanted. When a page and the installed package disagree, the package wins — check design-tests --version against what the page assumes.
Every page carries a Status line saying how far along its subject is:
| Status | Meaning |
|---|---|
Stable | Implemented and supported |
Experimental | Implemented, off by default, may still change |
Proposal | Not implemented; a design under discussion |
Superseded | Historical; the work landed differently |
Benchmark record | A dated measurement, not a guide |
Read a Proposal or Superseded page as history or intent, never as instructions for the current release.