# Visual parity

> unframework visual renders every example on every target and compares its geometry and pixels with the reference's, live or against committed baselines.

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.json` and 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/`:

<!-- prettier-ignore -->
```tsx [examples/Buttons.example.uf.tsx]
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:

<!-- prettier-ignore -->
```tsx [examples/Card.example.uf.tsx]
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:

<!-- prettier-ignore -->
```tsx [examples/TextField.example.uf.tsx]
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](/docs/tooling/preview#example-metadata) 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](/docs/reference/diagnostics#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:

<!-- prettier-ignore -->
```ts [unframework.config.ts]
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`](/docs/tooling/testing#pixels).

## Run it

`unframework visual` comes with `@uxfront/unframework`, and needs `@unframework.dev/visual` in your project, beside what [`unframework test`](/docs/tooling/testing#install-what-it-needs) 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`:

<!-- prettier-ignore -->
```json [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](/docs/tooling/testing#styling-engines-and-other-vite-plugins) 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](#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 in `actual.png` and its geometry in `geometry.actual.json`, then the image it was compared with in `reference.png`. When the two are the same size, `diff.png` marks every pixel that differs. A font other than Inter fails before the capture, unless `liveFonts` lists 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.png` and `diff.png` in 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:

<!-- prettier-ignore -->
```yaml [.github/workflows/ci.yml]
- 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 their `if` says 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](https://docs.github.com/en/actions/reference/workflows-and-actions/expressions#status-check-functions)). `always()` works too, and runs it on a cancelled run as well.
- **`path`** names the whole run directory, not `report.html` alone, 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/visual` under your project's root, or the directory you pass to `--out`.
- **`include-hidden-files: true`** matters when `path` goes through `.unframework/`, like `path: .unframework` or `path: .`. Unless it's set, `actions/upload-artifact` skips every file and directory whose name starts with a dot ([Uploading hidden files](https://github.com/actions/upload-artifact/tree/v7.0.2#uploading-hidden-files)), so such a path would upload nothing from the run directory. The action checks only the names it finds below `path`, though, so with `path` naming 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](#modes-and-baselines) says.
