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
bun add -d @tarve/test @tarve/headlessimport { 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.
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.