# Testing

`@tarve/test` gives Testing Library–style tests over `@tarve/headless`, Tarve's native tree compiled to WebAssembly: no window, GPU or native library, so tests run on any CI machine.

## First test

```sh
bun add -d @tarve/test @tarve/headless
```

```tsx title="app.test.tsx"
import { afterEach, expect, test } from "bun:test";
import { cleanup, fireEvent, render } from "@tarve/test";
import { App } from "./app";

afterEach(cleanup);

test("counts clicks", async () => {
  const view = await render(<App />);
  await fireEvent.click(view.getByRole("button", { name: "Increment" }));
  expect(view.getByTestId("count").text).toBe("Count: 1");
});
```

`render` is async: it loads the WebAssembly runtime once per process. A view that is not a `Window` is wrapped in a 640×480 one unless `width`/`height` say otherwise. Queries read the compiled scene tree; input goes through native hit testing, focus and the app's own event dispatch, as in a window.

## Queries

Every query comes as `getBy*`, `getAllBy*`, `queryBy*`, `queryAllBy*`, `findBy*` and `findAllBy*`. The matcher is an exact string after collapsing whitespace, `{ exact: false }` for a case-insensitive substring, a RegExp, or a function. A failed query prints the tree; `within(element)` scopes queries and `view.debug()` returns the printed tree.

| Query | Matches |
| --- | --- |
| `ByText(text)` | What a Text, Button, Markdown or Code shows. |
| `ByRole(role, opts)` | `control.role` or the implicit role (`button`, `textbox`, `searchbox`, `slider`, `img`, `window`); filter by `name`, `checked`, `selected`, `expanded`, `disabled`. |
| `ByLabel(text)` | A control named by `<label htmlFor>`, a `Field` label or its own `control.label`. |
| `ByPlaceholder(text)` | An Input or TextArea placeholder. |
| `ByDisplayValue(text)` | The current value of an Input or TextArea. |
| `ByTestId(id)` | The node `id`; Tarve has no `data-testid`. |

Elements are live: one object per node id whose `text`, `value`, `name`, `role`, `checked`, `disabled`, `parent`, `children` and `node` always read the current tree; `isConnected` turns false once the node is gone.

## Events

Every call waits until the app has handled it and re-rendered.

| Call | Does |
| --- | --- |
| `fireEvent.click(el, { via? })` | Pointer move, down and up at the element's centre. A disabled or covered element gets nothing; `via: "event"` delivers a native `click` instead. |
| `fireEvent.type(el, text, { clear? })` | Focuses and types; `{Enter}`, `{Tab}`, `{Backspace}`, `{ArrowLeft}`… press keys. |
| `fireEvent.clear(el)` | Selects all and deletes. |
| `fireEvent.key(key, el?)` | Presses a key, focusing `el` first when given. |
| `fireEvent.scroll(el, deltaY)` | Mouse wheel over the element. |
| `fireEvent.hover(el)` | Moves the pointer over it. |
| `fireEvent.native(event)` | Any native event, dispatched like the native tree's. |

`rerender(ui?)`, `unmount()`, `cleanup()`, `waitFor(callback, { timeout, interval })`, `waitForElementToBeRemoved`, `box(el)` for the laid-out box, `settle()` and `advance(ms)` for the motion clock complete the render.

## Image snapshots

`view.snapshot()` returns the frame as PNG bytes and `view.pixels()` as RGBA. Captures are deterministic (bundled fonts, frozen clock), so thresholds default to 0. A missing snapshot is written, except on CI; a mismatch writes `app.actual.png` beside it and throws. `TARVE_UPDATE_SNAPSHOTS=1` rewrites stored images.

```tsx title="app.test.tsx"
import { tarveMatchers, toMatchImageSnapshot } from "@tarve/test";

await toMatchImageSnapshot(view, `${import.meta.dirname}/__snapshots__/app.png`, { threshold: 8, maxDifferenceRatio: 0.001 });

// or as a matcher (Bun, Jest, Vitest)
expect.extend(tarveMatchers);
await expect(view).toMatchImageSnapshot("__snapshots__/app.png");
```

## Runners and runtimes

The package depends on no test runner: queries and events throw plain errors and `waitFor` retries on its own timer. `node:test` files run unchanged under `bun test` and Node.js.

| Runtime | Run |
| --- | --- |
| Bun 1.4+ | `bun test` |
| Node.js 26.10+ | `tarve run --runtime node app.test.tsx` bundles the TSX and the WebAssembly and font files, then runs the `node:test` tests. |
| txiki.js | `tarve build --runtime txiki app.test.tsx` and run the executable; there is no runner or `node:assert`, so call tests from a script and throw on failure. |

Limits: dialogs, clipboard, tray, notifications and the OS accessibility tree need a real window, and roles come from Tarve's `control` metadata rather than a platform accessibility API. For tests against the real renderer, use `TestRenderer`.

---

Tarve v0.13.8 · HTML version: https://tarve.dev/docs/testing · Index for agents: https://tarve.dev/llms.txt
