Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
57 changes: 57 additions & 0 deletions .github/workflows/visual.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
name: Visual

on:
pull_request:
types: [opened, synchronize, reopened, labeled, unlabeled]
push:
branches: [main]

permissions:
contents: read

concurrency:
group: visual-${{ github.ref }}
cancel-in-progress: true

jobs:
screenshots:
runs-on: ubuntu-latest
container:
image: mcr.microsoft.com/playwright:v1.65.0-noble
options: --ipc=host
strategy:
fail-fast: false
matrix:
shard: [1, 2, 3, 4]
env:
CI: "1"
HOME: /root
steps:
- uses: actions/checkout@v4
- run: npm ci --no-audit --no-fund
- run: npx playwright test --shard=${{ matrix.shard }}/4
- if: failure()
uses: actions/upload-artifact@v4
with:
name: visual-diffs-${{ matrix.shard }}
path: visual/results
retention-days: 14

baseline-label:
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Baseline changes need the visual-change label
env:
BASE: ${{ github.event.pull_request.base.sha }}
LABELED: ${{ contains(github.event.pull_request.labels.*.name, 'visual-change') }}
run: |
changed=$(git diff --name-only "$BASE"...HEAD -- visual/baselines | wc -l)
if [ "$changed" -gt 0 ] && [ "$LABELED" != "true" ]; then
echo "::error::This PR changes $changed baseline image(s). Review them, then add the visual-change label."
exit 1
fi
echo "$changed baseline image(s) changed; label present: $LABELED"
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
node_modules/
dist/
*.tgz
visual/results/
site/dist-visual/
visual/rc/
20 changes: 20 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,8 +124,28 @@ After changing `src/tokens.json`, run `npm run tokens`. After changing anything

To try local changes in an app, run `npm run build && npm pack` here and `npm install <path to the .tgz>` in the app. A tarball keeps one copy of React; a linked checkout resolves React from its own `node_modules` and renders a second copy.

## Visual tests

The Visual workflow screenshots every example block on every showcase page in Light and Dark, at 1706px and 390px wide, at device scale factor 2. It fails a pull request when any screenshot differs from its baseline in `visual/baselines/`, and uploads the expected, actual and diff images as an artifact.

```bash
$ npm run visual # compare against the baselines
$ npm run visual:update # rewrite the baselines that changed
$ VISUAL_PAGES=card,button npm run visual # only these showcase pages
```

Both run in the pinned Playwright image through Docker, so local screenshots match CI pixel for pixel. A pull request that changes how something looks commits its updated baselines, and the workflow requires the `visual-change` label on any pull request that touches `visual/baselines/`, so every visual change is reviewed as an image diff.

## Release

Before a release, run the release candidate check. It renders the previous tag, main, and main plus each PR in order, and reports every example that changed at each step with before, after and diff images. A change is explained when that step's PR updated the example's baseline, or when the explanations file names it. Any other change fails the check and blocks the release.

```bash
$ scripts/visual-rc.sh --base v0.1.12 --version 0.1.13 --explain explanations.json 95 99 103
```

The report is `visual/rc/<version>/report.md`.

1. Bump `version` in `package.json` in a pull request and merge it.
2. Run the Release workflow. It builds main and pushes a `vX.Y.Z` tag on a commit that adds `dist/` to it, so the tag pins both the registry URL and the package.
3. Bump the tag in the app's `package.json`.
Expand Down
70 changes: 70 additions & 0 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

7 changes: 6 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,11 @@
"check": "tsx scripts/tokens.ts --check && tsx scripts/registry.ts --check && tsx scripts/lint-css.ts",
"build": "npm run tokens && vite build && tsc -p tsconfig.build.json && tsx scripts/finish-build.ts",
"site": "vite --config site/vite.config.ts",
"site:build": "vite build --config site/vite.config.ts"
"site:build": "vite build --config site/vite.config.ts",
"visual:build": "vite build --config site/vite.visual.config.ts",
"visual:serve": "npm run visual:build && vite preview --config site/vite.visual.config.ts --host 127.0.0.1",
"visual": "bash scripts/visual.sh",
"visual:update": "bash scripts/visual.sh --update-snapshots=changed"
},
"peerDependencies": {
"@xterm/addon-fit": "^0.10.0 || ^0.11.0",
Expand Down Expand Up @@ -121,6 +125,7 @@
"@codemirror/state": "^6.7.6",
"@codemirror/view": "^6.43.15",
"@lezer/highlight": "^1.2.5",
"@playwright/test": "1.65.0",
"@tailwindcss/vite": "^4.1.14",
"@types/node": "^24.0.0",
"@types/react": "^19.3.0",
Expand Down
42 changes: 42 additions & 0 deletions playwright.config.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
import { defineConfig } from "@playwright/test";

const url = process.env.VISUAL_URL;

export default defineConfig({
testDir: "visual",
snapshotPathTemplate: `${process.env.VISUAL_SNAPSHOTS ?? "visual/baselines"}/{projectName}/{arg}{ext}`,
outputDir: "visual/results",
fullyParallel: true,
workers: process.env.CI ? 2 : undefined,
retries: 0,
reporter: process.env.CI ? [["github"], ["list"]] : [["list"]],
timeout: 120_000,
expect: {
toHaveScreenshot: {
animations: "disabled",
caret: "hide",
scale: "device",
threshold: 0.1,
maxDiffPixelRatio: 0.0005
}
},
use: {
baseURL: url ?? "http://127.0.0.1:4173/",
timezoneId: "UTC",
locale: "en-US",
deviceScaleFactor: 2,
colorScheme: "light"
},
projects: [
{ name: "desktop", use: { viewport: { width: 1706, height: 971 } } },
{ name: "mobile", use: { viewport: { width: 390, height: 844 } } }
],
webServer: url
? undefined
: {
command: "npm run visual:serve",
url: "http://127.0.0.1:4173/visual.html",
reuseExistingServer: !process.env.CI,
timeout: 180_000
}
});
54 changes: 54 additions & 0 deletions scripts/visual-compare.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
// Compares two snapshot trees from scripts/visual-rc.sh and writes before, after and diff images.
// Usage: node scripts/visual-compare.mjs <before-dir> <after-dir> <out-dir>
// Prints JSON: { changed: [key], added: [key], removed: [key] }, where key is <project>/<file>.
import {
copyFileSync,
existsSync,
mkdirSync,
readdirSync,
readFileSync,
writeFileSync
} from "node:fs";
import { createRequire } from "node:module";
import path from "node:path";

const [before, after, out] = process.argv.slice(2);
const require = createRequire(import.meta.url);
const comparator = require("playwright-core/lib/coreBundle").utils.getComparator("image/png");

const list = (root) =>
existsSync(root)
? readdirSync(root, { withFileTypes: true })
.filter((entry) => entry.isDirectory())
.flatMap((project) =>
readdirSync(path.join(root, project.name)).map((file) => `${project.name}/${file}`)
)
: [];

const a = new Set(list(before));
const b = new Set(list(after));
const result = { changed: [], added: [], removed: [] };
const save = (key, name, buffer) => {
const file = path.join(out, key.replace(".png", `.${name}.png`));
mkdirSync(path.dirname(file), { recursive: true });
if (Buffer.isBuffer(buffer)) writeFileSync(file, buffer);
else copyFileSync(buffer, file);
};
for (const key of b) {
if (!a.has(key)) {
result.added.push(key);
save(key, "after", path.join(after, key));
continue;
}
const x = readFileSync(path.join(before, key));
const y = readFileSync(path.join(after, key));
if (x.equals(y)) continue;
const diff = comparator(y, x, { threshold: 0.1, maxDiffPixelRatio: 0.0005 });
if (!diff) continue;
result.changed.push(key);
save(key, "before", path.join(before, key));
save(key, "after", path.join(after, key));
if (diff.diff) save(key, "diff", diff.diff);
}
for (const key of a) if (!b.has(key)) result.removed.push(key);
console.log(JSON.stringify(result));
Loading
Loading