Visual parity
Visual parity checks that every target draws your components the same way, from examples you write once. Think of a button whose padding is two pixels wider in Svelte, a card whose footer wraps in Angular, or a text field that Qwik renders a shade lighter. A spec catches what a component does, and an example catches what it looks like.
unframework visual renders each example on every target your unframework.config.ts names, in Chromium, and compares each target's capture with the reference target's: the boxes and computed styles of every element first, then the pixels. It's the check Unframework runs on its own corpus, on your examples.
This page walks you through it. We'll look at:
- Examples: the files the run renders.
- Running it with
unframework visual. - Modes and baselines: live, the default, or committed files.
- The run directory, with
report.jsonand its images. - The report page that shows them.
- Running it in CI, and keeping its report.
Examples
An example is a *.example.uf.tsx file whose default export is a component with no props. It renders your components the way a page would, with the props, slots and models it shows written into it. Since it takes nothing, every target renders exactly the same thing. The sample design system keeps its examples in examples/, next to src/:
import Button from "../src/Button.uf.tsx";
export default function Buttons() {
return (
<div>
<Button>Save</Button> <Button variant="secondary">Cancel</Button>
</div>
);
}
An example can fill a component's slots, which a test's mount can't:
import Card from "../src/Card.uf.tsx";
export default function CardExample() {
return (
<Card>
{{
header: () => <h2>Release notes</h2>,
default: () => <p>Every example renders on every target.</p>,
footer: () => <small>By Ada</small>,
}}
</Card>
);
}
It can hold state too, like the value a model binds:
import { ref } from "@uxfront/unframework";
import TextField from "../src/TextField.uf.tsx";
export default function TextFieldExample() {
const name = ref("Ada");
return <TextField label="Name" v-model:value={name.value} />;
}
The run finds examples anywhere under your project's root, at any depth, but not in node_modules, dist, a directory whose name starts with a dot, or the run directory. An example's id is its path from the root without the suffix, like examples/Buttons.
A doc comment on an example's default export gives the preview its category, title, description and order. The run doesn't read it, so it changes neither the example's id nor its baselines nor what's captured.
An example whose component declares props fails before anything renders, with UF7011 at its props. An example with no default export fails too, since the run wouldn't know what to mount.
You can keep examples beside your components in src/, since unframework build and unframework check skip every *.example.uf.tsx file. An example is never packaged.
Fonts
Each capture is checked for the fonts its text used, and text drawn in anything but the bundled Inter fails with font-fallback, since another font renders differently on another machine. The page sets Inter as its default font, so text your components don't style renders in it. A component that sets its own font-family, like your design system's typeface, fails on every target by default.
Live captures can take your typeface. Every target renders on one machine in one run there, so they all draw the same text with the same font. List its families in liveFonts in your unframework.config.ts, as this test project does:
export default {
targets: ["vue"],
liveFonts: ["Inkline Sans", "Inkline Mono"],
};
Copy each name from the font-fallback message of a run without it, since Chromium reports a font file's own family name, which can differ from the one your CSS gives it. Text in a listed family passes, and text in any other font still fails, the fallback of a listed font that didn't load included. Baselines ignore the list: with --baseline, a font other than Inter still fails, since the baseline came from another machine. The same field applies to the captures of unframework test.
Run it
unframework visual comes with @uxfront/unframework, and needs @unframework.dev/visual in your project, beside what unframework test needs: @unframework.dev/testing, vitest, @vitest/browser-playwright, playwright and each target's framework and Vite plugin. The sample design system runs it from a script of its package.json:
"visual": "unframework visual"
It prints a line for each example, like ✓ examples/Buttons: passed on 7 targets, then the paths of report.json and report.html, on lines that start with report: and page:. A failed example names each target that differs and why, with the comparison's message below it. These are the command's options:
| Option | What it does |
|---|---|
--target <t> | Runs one target, and can be repeated. The reference target joins every run, since the others compare with its capture. |
--live | Compares every target with the reference's capture in the same run. The default. |
--baseline | Compares every target, the reference included, with the baselines committed beside each example. |
--update | Writes the baselines, with --baseline implied. Only Unframework's baseline image writes them, so it's refused anywhere else. |
--out <dir> | The run directory, .unframework/visual by default. |
The command exits 0 when every example matches on every target, 1 when one differs or declares props, and 2 on a usage or configuration error, like an unknown target, --update outside the baseline image, a project with no example or an invalid unframework.config.ts.
The run builds its browser projects with defineTestConfig() from your unframework.config.ts, as unframework test does without a vitest.config.ts, so your vite config applies to it too. It generates one spec per example under .unframework/specs/, so add .unframework/ to your .gitignore.
Modes and baselines
By default, pixels compare live: the reference target, Vue when your project targets it and your first target otherwise, renders each example first, and every other target is compared with that capture in the same run. It works from the first run, on your machine and in CI alike, and it catches a target that renders differently from the others. It can't catch a change that every target shares, like a padding you changed on purpose or by accident.
Baselines catch that. With --baseline, every target is compared with two files committed beside each example. For examples/Buttons.example.uf.tsx, they're examples/__screenshots__/Buttons-chromium-linux.png and examples/__expected__/geometry.Buttons.json. A missing file fails the example, and names the command that writes it.
Only Unframework's baseline image, Playwright's on linux/amd64, writes them, with --update, as it writes the corpus's own baselines. So baselines need that image in your CI before you opt into them.
The run directory
Each run empties the run directory and writes it again. It holds:
report.json, the run's data.report.html, the page that shows it (The report page).<example id>/<target>.png, each target's capture, a passing one included.<example id>/<target>/for a target whose comparison failed, with what it got to: its capture inactual.pngand its geometry ingeometry.actual.json, then the image it was compared with inreference.png. When the two are the same size,diff.pngmarks every pixel that differs. A font other than Inter fails before the capture, unlessliveFontslists it, so it leaves no image.
Since the run empties it, --out refuses the project's root, a directory above it, .unframework/ and the specs inside it, and a directory with files no earlier run wrote.
report.json lists every example on every target that ran, in your configuration's order:
| Field | What it holds |
|---|---|
version | The report's format, 1. |
pixels | "live" or "baseline". |
update | Whether the run wrote the baselines. |
reference | The reference target. |
targets | The targets that ran. |
passed | Whether every cell passed. |
examples | Each example's id, its file and its cells, one per target: the status, the outcome, the message, the diffPixels, every geometry delta and the images. |
Image paths are relative to report.json. A cell with no capture, because the example didn't compile or mount on that target, fails with the outcome not-captured and its test's error, the compile's own errors first. A cell whose capture matched fails too when its test failed after it, like on a console message the example logged, with the outcome test-failed. The package exports the report's type as VisualReport.
The report page
Each run writes report.html beside report.json. Open it in a browser straight from the run directory: it needs no server, and it loads nothing but the images beside it.
For each example, the page shows a grid with a cell for each target that ran, in your configuration's order. Each cell holds the target's capture, its status and its outcome, and the reference's cell says it's the reference. Seven targets fit in one row on a desktop window, and a phone shows two cells to a row.
Each failed cell gets a section below its grid, with:
- The message that the comparison or the test gave.
- A diff overlay that switches between
reference.png,actual.pnganddiff.pngin one frame. Click an image's name, or use the arrow keys once the switch has focus. It offers only the images the cell left, and the section names the files it didn't leave. - The geometry deltas, a table with each element's path, the property, and its expected and actual values. A long list shows its first 100 rows and names the total.
Run it in CI
A CI job runs unframework visual as you do, and the run directory it leaves is what you'll want to look at when an example fails. The page needs no server, so the job only has to keep that directory. Here's how Unframework's own CI does it. Its Design system job runs the sample design system's examples on GitHub Actions, then this step keeps the run directory:
- name: Upload the visual report
if: ${{ !cancelled() }}
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: design-system-visual
path: /tmp/unframework-e2e/design-system/.unframework/visual
include-hidden-files: true
if-no-files-found: error
overwrite: true
retention-days: 7
Three of its lines are worth knowing on any project:
if: ${{ !cancelled() }}runs the step after a failed one. The command exits 1 when an example fails, and GitHub Actions skips the later steps of a failed job unless theirifsays otherwise, so without it a failed run, the one worth looking at, keeps nothing.!cancelled()skips the step only when the run is cancelled (status check functions).always()works too, and runs it on a cancelled run as well.pathnames the whole run directory, notreport.htmlalone, since the page names its images by paths relative to it. This job installs its copy of the sample design system outside the checkout, so its path starts with/tmp. In your project, it's.unframework/visualunder your project's root, or the directory you pass to--out.include-hidden-files: truematters whenpathgoes through.unframework/, likepath: .unframeworkorpath: .. Unless it's set,actions/upload-artifactskips every file and directory whose name starts with a dot (Uploading hidden files), so such a path would upload nothing from the run directory. The action checks only the names it finds belowpath, though, so withpathnaming the run directory itself, as here, it keeps every file either way. The step sets it anyway, so the upload still works if the path changes.
if-no-files-found: error fails the step when it finds nothing to keep, where the action only warns by default, and retention-days: 7 keeps the artefact for a week. On another CI, the recipe is the same: keep the run directory as the job's artefact, in a step that runs after a failed one.
The job's log names the page on the line that starts with page:. To look at it, open the run's summary page on GitHub, download the artefact from its "Artifacts" section, unzip it and open report.html from disk. The run directory is a static site, so any static host can serve it as it is.
Live pixels, the default, need no baselines, so the run works in CI from its first commit. The job does need Chromium and the system libraries it runs on. Ours runs in Playwright's image, mcr.microsoft.com/playwright:v1.63.0-noble, at the same version as the playwright it installs. On a plain runner, pnpm exec playwright install --with-deps chromium installs the browser and its libraries. --baseline and --update need Unframework's baseline image instead, as Modes and baselines says.
Testing
@unframework.dev/testing runs one spec on all seven targets and compares them with expectParity: the DOM, the ARIA tree, the trace, the pixels and axe.
Preview
unframework preview shows every example and component on every target side by side, with controls for their props, and preview build writes it as a static site.