Tooling

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:

FieldWhat it does
ssrThe scenarios, by name, with the props each renders: mountScenario mounts one, and the server render renders the same props.
axeThe 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.
referenceThe target that writes the case's expectations, for a case the usual reference renders differently on purpose.
mainThe 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/:

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:

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:

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:

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:

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'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 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.
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:

matchers.parity.spec.ts
    await expect.element(view.getByRole("button")).toHaveNoAxeViolations();
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:

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:

MatcherComparesUse it when
toHaveAriaTree(expected)The whole tree, read as expectParity reads it, with one stringThe 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 nodesYou 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 runYou 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:

package.json
    "parity": "unframework test"

These are its options:

OptionWhat 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.
--updateWrites 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:

TargetPackages
reactreact, react-dom, @vitejs/plugin-react, @babel/core, babel-plugin-react-compiler
vuevue, @vitejs/plugin-vue
sveltesvelte, @sveltejs/vite-plugin-svelte
solidsolid-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
astroastro

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, 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:

OptionDefaultWhat it does
targetsThe targets of unframework.config.tsThe targets the run tests.
include["**/*.test.ts"], never in node_modules or distThe test files, relative to the root. Each one's directory is a case.
reference"vue" when you test Vue, the first target otherwiseThe target that writes __expected__/.
pixels"live""live" or "baseline", below.
toolchainDirspackage.resolveFrom, then the rootWhere each target's compiler stack resolves from, by target.
rootThe working directoryWhere 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:

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

Copyright © 2026