# qain

> Semantic style-regression testing for Chromium. qain captures the browser’s *used values* — resolved computed styles, layout boxes, paint order, composited colors — as a JSON snapshot, and diffs two snapshots semantically: it reports what changed and what merely moved, attributing each change to the CSS declaration behind it. Not pixels.

qain is built for humans and coding agents alike: the diff is plain text, the exit code is 1 when the diff is non-empty (so CI and agents can gate on it), and the snapshot is stable, documented JSON that scripts can consume without qain on the other end. It suppresses noise structurally — elements are keyed not positioned, class strings are captured but never compared, and every change is labelled primary or derived so collateral movement folds away. Chromium-only by design: it is built on DOMSnapshot.captureSnapshot and CSS.forcePseudoState, which have no Firefox or WebKit equivalent.

## Documentation

- [Documentation overview](https://shinyaigeek.github.io/qain/docs/): Index of the usage docs and links to the test-runner integrations.
- [Getting started](https://shinyaigeek.github.io/qain/docs/getting-started.html): Install, capture your first snapshot, and read your first diff.
- [CLI reference](https://shinyaigeek.github.io/qain/docs/cli.html): Every command and flag: snap, diff, view, shot — and the exit codes.
- [Recipes](https://shinyaigeek.github.io/qain/docs/recipes.html): Snapshot a dev server, scope to one element, point at a Storybook story, extract computed styles as data, and gate CI or a coding agent on the exit code.
- [GitHub Action](https://shinyaigeek.github.io/qain/docs/github-action.html): The qain-diff action: a sticky PR comment with the semantic diff and before/after/diff screenshots whenever a committed baseline changes.
- [Snapshot & diff format](https://shinyaigeek.github.io/qain/docs/snapshot-format.html): The stable, documented JSON the CLI reads and writes.
- [Library API (@qain/core)](https://shinyaigeek.github.io/qain/docs/library.html): Capture and diff from your own code, with Playwright, Puppeteer, or a raw CDP socket.

## Test-runner integrations

- [@qain/playwright](https://github.com/Shinyaigeek/qain/blob/main/packages/playwright/README.md): `toMatchStyleSnapshot` for Playwright tests.
- [@qain/vitest](https://github.com/Shinyaigeek/qain/blob/main/packages/vitest/README.md): the same matcher for Vitest browser mode — component VRT without booting Storybook.
- [@qain/storybook](https://github.com/Shinyaigeek/qain/blob/main/packages/storybook/README.md): `matchStyleSnapshot` for the Storybook test runner — every story becomes a style test.

## Try it

- [Live demo](https://shinyaigeek.github.io/qain/): a billing page broken four ways at once, with the replay diff, HTML report, terminal output, and raw snapshots — regenerated by CI.
- [In-browser playground](https://shinyaigeek.github.io/qain/playground/): edit a self-contained HTML page and watch qain diff it live, entirely in the browser — no server, no CDP.

## Optional

- [Design story (main README)](https://github.com/Shinyaigeek/qain/blob/main/README.md): why the diff stays quiet, how rule attribution works, what replay does, and what qain deliberately does not do.
- [All documentation as one file](https://shinyaigeek.github.io/qain/llms-full.txt): every doc concatenated for one-fetch consumption.
- [Source repository](https://github.com/Shinyaigeek/qain)