# 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.

Testing lets a design system check that each component works the same in every framework it ships to, from one spec. Think of a menu that opens in Vue but not in Solid, a label that Angular reads with an extra space, or a dark theme that only React renders dark. Seven test suites written by hand drift apart, and none of them compares one target with another.

`@unframework.dev/testing` is the API Unframework's own corpus is written in. A spec is written once and runs in one browser project per target. Each check it makes is compared across the seven targets, so a difference fails the target that differs.

This page walks you through testing your own components. We'll look at:

- **A case:** the unit you test.
- **Writing a spec**, mounting a component, acting like a person and comparing the targets.
- **The matchers**, for a spec's own checks.
- **Running the tests** with `unframework test`, and the configuration behind it.

## A case

Let's start with the unit you test: a case. A case is a directory that holds:

- One spec, `<name>.test.ts`.
- The component it mounts, a `.uf.tsx` file, and any components that file composes.
- An optional `case.json`, which describes the case's scenarios.
- `__expected__/`, the shared expectations the reference target writes and every other target must match.

You never write `__expected__/` by hand. It's generated, and you review it as you would review code. Each scenario a spec checks has its files there: `dom.<name>.html`, `aria.<name>.yaml` and, when the scenario follows steps, `trace.<name>.json`.

`case.json` has five fields a spec relies on:

| Field         | What it does                                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `ssr`         | The scenarios, by name, with the props each renders: `mountScenario` mounts one, and the server render renders the same props. |
| `axe`         | The axe rule ids the case is known to break, exactly. None by default.                                                         |
| `colorScheme` | `"light"` or `"dark"`: the `prefers-color-scheme` the browser emulates before the spec mounts anything. `"light"` by default.  |
| `reference`   | The target that writes the case's expectations, for a case the usual reference renders differently on purpose.                 |
| `main`        | The file the spec and the server render mount, relative to the case: one of its own files, or a component outside it.          |

A case's directory can sit anywhere in your project, and its id is its path from the project's root, like `test/counter`. So a case can test a component where it lives: the sample design system's counter case points `main` at the component in `src/`:

<!-- prettier-ignore -->
```json [test/counter/case.json]
{
  "description": "The counter, which starts at its initial count and adds its step on each click.",
  "main": "../../src/Counter.uf.tsx",
  "ssr": {
    "initial": {
      "props": {
        "initial": 2,
        "step": 3
      }
    }
  }
}
```

A component that needs slots can't be mounted alone, since `mount` takes props but no slots. Its case holds a harness parent instead, a `.uf.tsx` that fills the slots, and that file is the case's main source:

<!-- prettier-ignore -->
```tsx [test/button/SaveButton.uf.tsx]
// A harness parent (ADR-0057): `mount` takes props but no slots, and a button needs its label.
import Button from "../../src/Button.uf.tsx";
import type { ButtonVariant } from "../../src/types";

export default function SaveButton({ variant }: { variant?: ButtonVariant }) {
  return <Button variant={variant}>Save</Button>;
}
```

This is the dark theme's `case.json`, from Unframework's own corpus:

<!-- prettier-ignore -->
```json [case.json]
{
  "description": "The dark colour scheme: Styleframe's stylesheet sets the dark tokens under `prefers-color-scheme: dark`, which the case opts into.",
  "colorScheme": "dark",
  "ssr": {
    "default": {
      "props": {
        "text": "Dark by preference."
      }
    }
  }
}
```

## Write a spec

Now let's look at a spec. This one tests a counter that starts at its `initial` prop, adds its `step` on each click, emits the new count and shows "Big" once double the count passes ten:

<!-- prettier-ignore -->
```ts [counter.test.ts]
import { describeTargets, it, mountScenario } from "@unframework.dev/testing";
import { expect } from "vitest";

import Counter from "./Counter.uf.tsx";

describeTargets("state/counter", () => {
  it("renders the initial count and the step", async () => {
    const view = await mountScenario(Counter, "initial");
    await view.expectParity("initial");
    await expect.element(view.getByRole("status")).toHaveTextContent("2");
    await expect.element(view.getByRole("button", { name: "+3" })).toBeVisible();
  });

  it(
    "increments by the step and emits the new value",
    { requires: ["interactivity"] },
    async () => {
      const view = await mountScenario(Counter, "initial");
      await view.user.click(view.getByRole("button", { name: "+3" }));
      await view.expectParity("after-increment");
      await expect.element(view.getByRole("status")).toHaveTextContent("5");
      expect(view.emitted("change")).toEqual([[5]]);
    },
  );

  it("shows Big once the double passes ten", { requires: ["interactivity"] }, async () => {
    const view = await mountScenario(Counter, "initial");
    await view.user.click(view.getByRole("button", { name: "+3" }));
    await view.user.click(view.getByRole("button", { name: "+3" }));
    await view.expectParity("big");
    await expect.element(view.getByRole("status")).toHaveTextContent("8");
    await expect.element(view.getByText("Big")).toBeVisible();
    expect(view.emitted("change")).toEqual([[5], [8]]);
  });
});
```

`describeTargets` is Vitest's `describe` with the target in the title, so a report tells the seven runs apart. `it` and `test` are Vitest's, with one more option, `requires`: the capabilities a test needs. On a target that lacks one, the test is skipped before it runs, and the reason shows on every check it would have made. Astro runs no client code, so the two tests that click are skipped there.

`it` refuses `skip`, `only`, `todo`, `fails`, `retry`, `repeats`, `concurrent` and `tags`. A test runs on every target, since a known failure belongs in a quarantine with a reason, and a flaky test is a bug.

## Mount a component

Next, let's look at mounting. `mountScenario(component, name)` mounts the component with the props of `case.json`'s `ssr[name]`, so the browser scenario and its server twin render the same thing. `mount(component, { props })` mounts it with props you pass, for a scenario the server can't render, like one that uses the view's clock:

<!-- prettier-ignore -->
```ts [unmount-timers.test.ts]
  // Browser-only: a short interval, on the view's clock.
  it("stops refreshing once unmounted", { requires: ["interactivity"] }, async () => {
    const view = await mount(AutoRefresh, { props: { interval: 500 }, clock: true });
```

A component imported from a `.uf.tsx` file is typed as the function you wrote, so `props` is checked against its props type.

Both return a `View`. Its queries, like `getByRole` and `getByText`, are scoped to the component. Its `container` is the `<div>` the component mounts into, and `locator` points at it.

What the component appends to `<body>`, like a [teleport](/docs/components/teleport)'s dialog, is the view's too. Its queries reach it, and `expectParity` compares it after the container. A test fails if it leaves an element in `<body>` once its views are unmounted, so a component removes what it appends there as it unmounts.

Each capture waits for the page's running transitions and animations to end, for at most 2 seconds, so it never sees a [transition](/docs/components/transitions) half-way. The harness gives every transition and animation no duration, so a capture waits only for one your test gives a duration of its own. One that never ends fails the test.

## Act like a person

A spec acts only through the view, never through Vitest's `userEvent` or a locator's own actions. Each action runs through the target's adapter, waits until the page is quiet and records a step of the view's trace:

- `view.user` clicks, hovers, types, fills, presses keys, tabs, focuses, selects options and scrolls, the way a person does.
- `view.clock.tick(ms)` runs the component's intervals due in the next `ms` milliseconds, for a view mounted with `{ clock: true }`.
- `view.rerender(props)` renders the component again with new props, as a parent would.
- `view.emitted(name)` returns the arguments of each emit of an event, in order.

<!-- prettier-ignore -->
```ts [unmount-timers.test.ts]
    // Past two intervals, short of the third: two refreshes, in this step.
    await view.clock.tick(1250);
    await view.expectParity("refreshed-twice");
    await expect.element(view.getByRole("status")).toHaveTextContent("Refreshing");
    expect(view.emitted("refresh")).toEqual([[1], [2]]);
```

## Compare the targets

`view.expectParity(name)` checks a scenario against the case's shared expectations. It compares:

- The normalised DOM and the ARIA tree.
- The steps since the mount or the previous `expectParity`, against the scenario's trace.
- The geometry, then the pixels.
- What axe-core reports, against `case.json`'s `axe` list.

A failed check doesn't stop the test, so the assertions after it still run, and the test then fails with every check that failed. We recommend calling it once per scenario, after the steps that lead there, and then asserting at least one fact about what rendered.

## Matchers

Finally, let's look at the two matchers, for the checks a spec makes on an element of its own choosing. The setup registers both.

`toHaveNoAxeViolations()` runs axe-core on the element with the same rules as `expectParity`. It passes when axe reports nothing, or exactly the rules you list in `expected`:

<!-- prettier-ignore -->
```ts [matchers.parity.spec.ts]
    await expect.element(view.getByRole("button")).toHaveNoAxeViolations();
```

<!-- prettier-ignore -->
```ts [matchers.parity.spec.ts]
    await expect.element(view.locator).toHaveNoAxeViolations({ expected: ["image-alt"] });
```

`toHaveAriaTree(expected)` compares the element's ARIA tree with one tree that holds on every target. It reads the tree the way `expectParity` does, so Angular's host elements add no space and a generated id reads as `uf-id-1`. The indentation and the blank lines around `expected` don't count, so a template literal can hold it:

<!-- prettier-ignore -->
```ts [matchers.parity.spec.ts]
    await expect.element(view.getByRole("group")).toHaveAriaTree(`
      - group "Actions":
        - button "Save"
        - button "Cancel"
    `);
```

When either fails, its message names the target, and `toHaveAriaTree` shows a diff of the two trees.

Vitest has two ARIA matchers of its own, and they stay as Vitest wrote them. Here's when to use which:

| Matcher                               | Compares                                                                                | Use it when                                                                |
| ------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `toHaveAriaTree(expected)`            | The whole tree, read as `expectParity` reads it, with one string                        | The tree is part of the component's contract on every target.              |
| `toMatchAriaInlineSnapshot(template)` | The target's raw tree, with a template in the spec that may list only some of its nodes | You check a few nodes, and the targets' trees don't differ where you look. |
| `toMatchAriaSnapshot()`               | The target's raw tree, with a snapshot file Vitest writes on the first run              | You want a record of each target's tree, without comparing the targets.    |

## Run the tests

Now let's run them. `unframework test` runs every case on every target your `unframework.config.ts` names, with Vitest: one browser project per target, which runs in Chromium, and one server render project per target. The sample design system runs it from a script of its `package.json`:

<!-- prettier-ignore -->
```json [package.json]
    "parity": "unframework test"
```

These are its options:

| Option             | What it does                                                                                                                            |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `--target <t>`     | Tests one target, and can be repeated. The reference target joins every run, since the others compare with what it renders.             |
| `--update`         | Writes the expectations: the reference writes `__expected__/`, and every other target must match it in the same run.                    |
| `-- <vitest args>` | Hands the rest to Vitest, like `-- --reporter=json` or a file filter. Vitest's own `--update` is refused, so use the command's instead. |

The command exits 0 when every test passes, 1 when one fails, and 2 on a usage or configuration error, like an unknown target or an invalid `unframework.config.ts`.

### Install what it needs

`unframework test` comes with `@uxfront/unframework`, and needs `@unframework.dev/testing`, `vitest`, `@vitest/browser-playwright` and `playwright` in your project. When the testing package, or one it loads as the command starts, like `vitest`, is missing, the command exits 2 and lists every package below. Each target also needs its framework and the framework's Vite plugin, and a missing one exits 2 with a message that names its target:

| Target    | Packages                                                                                                                  |
| --------- | ------------------------------------------------------------------------------------------------------------------------- |
| `react`   | `react`, `react-dom`, `@vitejs/plugin-react`, `@babel/core`, `babel-plugin-react-compiler`                                |
| `vue`     | `vue`, `@vitejs/plugin-vue`                                                                                               |
| `svelte`  | `svelte`, `@sveltejs/vite-plugin-svelte`                                                                                  |
| `solid`   | `solid-js`, `vite-plugin-solid`, `@babel/core`                                                                            |
| `angular` | `@angular/core`, `@angular/common`, `@angular/platform-browser`, `@angular/platform-server` and its compiler stack, below |
| `qwik`    | `@qwik.dev/core`                                                                                                          |
| `astro`   | `astro`                                                                                                                   |

`solid@2`, which is opt-in, takes `solid-js` and `@solidjs/web` 2 and `@solidjs/vite-plugin`, installed where `package.resolveFrom.solid2` points if the project keeps Solid 1 at its root.

Angular's compiler stack is `@angular/compiler`, `@angular/compiler-cli`, `@angular/build` and `@analogjs/vite-plugin-angular`, with TypeScript 6. It resolves from your project's root, or from the directory `package.resolveFrom` names for `angular` in [your configuration](/docs/tooling/configuration), so you can keep it out of your project's own dependencies.

### Configure the run

Without a `vitest.config.ts`, the command builds its configuration with `defineTestConfig()` from `@unframework.dev/testing/config`. With one, it runs yours, so export `defineTestConfig(options)` from it to change these defaults:

| Option          | Default                                               | What it does                                                          |
| --------------- | ----------------------------------------------------- | --------------------------------------------------------------------- |
| `targets`       | The `targets` of `unframework.config.ts`              | The targets the run tests.                                            |
| `include`       | `["**/*.test.ts"]`, never in `node_modules` or `dist` | The test files, relative to the root. Each one's directory is a case. |
| `reference`     | `"vue"` when you test Vue, the first target otherwise | The target that writes `__expected__/`.                               |
| `pixels`        | `"live"`                                              | `"live"` or `"baseline"`, below.                                      |
| `toolchainDirs` | `package.resolveFrom`, then the root                  | Where each target's compiler stack resolves from, by target.          |
| `root`          | The working directory                                 | Where `unframework.config.ts` is, and what case ids are relative to.  |

A run refuses a case it can't tell apart, at startup and with the fix: a directory with two test files, a case with no main source, or a test file at the root.

### Styling engines and other Vite plugins

A component styled through an engine, like Styleframe, imports the `virtual:` modules the engine's Vite plugin serves, and every output keeps those imports as written. So the run needs your engine's plugin, or every import fails to resolve. Give it in your `unframework.config.ts`'s `vite` function, as this test project does for a module only its own plugin serves, and for the runtime that module imports:

<!-- prettier-ignore -->
```ts [unframework.config.ts]
import { ufFixturePlugin } from "../uf-fixture.ts";

export default {
  targets: ["react", "vue", "svelte", "solid", "angular", "qwik", "astro"],
  vite: () => ({
    plugins: [ufFixturePlugin()],
    // The runtime the plugin's module imports, bundled before the run starts.
    optimizeDeps: { include: ["parse5"] },
  }),
  // Angular's compiler stack runs on TypeScript 6, which the workspace keeps in its toolchain.
  package: { resolveFrom: { angular: "../../../../../tests/toolchains/angular" } },
};
```

Every browser and server render project calls `vite` with its target and kind, like `{ target: "vue", mode: "browser" }`, so each gets plugins of its own: a plugin may keep one server's state. Its `plugins`, in any shape Vite's `plugins` takes, are listed before the Unframework plugin. Every other key merges into the project's own config, so `optimizeDeps.include` adds to the run's list, and a dependency your engine's module imports is bundled before the run starts rather than reloading the page when the browser finds it. Astro's render server takes the plugins alone.

Vite orders plugins by their `enforce` first, so yours run before Unframework's only within one group: Unframework's resolver is `enforce: "pre"`, so a plugin with no `enforce` runs after it. An engine's `virtual:` modules resolve either way, since Unframework's plugin never resolves an import that passes through.

The run never lets `vite` replace what it sets for itself: `root`, `base`, `cacheDir`, `test`, `configFile`, `envDir`, `server.host`, `server.port`, `server.strictPort` and `server.hmr` fail the run with a message that names the key, and so does a `server` that isn't an object. Angular's compiler needs no types from you either, since the run declares every `virtual:` module for it. Your own `tsconfig.uf.json` check still reads the real ones.

### Update the expectations

When you add a case, or change what a component renders on purpose, run `unframework test --update`. Then review every file it wrote under `__expected__/` as you would review code, because those files are the contract every target is held to. A run without `--update` fails on a missing or different file, and names the check and the file. CI never writes, so `--update` is refused while `CI` is set.

The run keeps its scratch in `.reports/` and `.live/` at the project's root. Add both to your `.gitignore`.

### Pixels

By default, pixels compare live: each target's screenshot is compared with the reference's from the same run, in Chromium, on your machine and in CI alike. That catches a target that renders differently from the others, though not a change that every target shares. `pixels: "baseline"` compares with committed baselines instead, which only Unframework's baseline image, Playwright's on linux/amd64, writes. So outside that image, `--update` refuses to run with baselines, and `UF_PIXELS=live unframework test --update` updates every other expectation.

Every capture's text must be drawn in the bundled Inter, or it fails with `font-fallback`. When pixels compare live, the families `liveFonts` lists in your `unframework.config.ts` pass too, as [`unframework visual`'s fonts](/docs/tooling/visual#fonts) explains. Baselines ignore the list.

## What the package exports

The root entry, `@unframework.dev/testing`, is the public API:

- The functions `describeTargets`, `it`, `test`, `mount`, `mountScenario`, `allowConsole`, `capturedConsole` and `currentTarget`.
- The types a spec writes, like `View`, `ViewUser`, `ViewClock`, `SpecOptions`, `CaseConfig`, `SsrScenario` and `NoAxeViolationsOptions`.

`@unframework.dev/testing/config` exports `defineTestConfig`, for a project's `vitest.config.ts`. The other subpaths, `./harness`, `./setup`, `./node`, `./normalize`, `./ssr`, `./cli` and one per target, are internal: the test configuration loads them, and a spec never imports them. In Unframework's own corpus, a lint rule fails a spec that imports one of them, another `@unframework.dev` package or the harness's own files.
