@zoijs/testing

Tiny first-party testing helpers for Zoijs. Drive the real DOM — no custom renderer, no virtual snapshots, no build step.

@zoijs/testing mounts your real component, lets you query the real DOM and fire real events, and resolves Zoijs's microtask-batched updates for you. It works with any test runner (node:test, Vitest) and any DOM (jsdom, happy-dom, a real browser), and depends only on @zoijs/core.

Install

npm i -D @zoijs/testing

You also need a DOM in your test environment — e.g. jsdom (node --test --import ./setup-dom.js) or Vitest's environment: "jsdom".

Use it

import test from "node:test";
import assert from "node:assert/strict";
import { render, fireEvent, cleanup } from "@zoijs/testing";
import { Counter } from "../src/Counter.js";

test.afterEach(() => cleanup());

test("counts up on click", async () => {
  const { getByRole } = render(Counter);
  const button = getByRole("button");

  await fireEvent.click(button); // dispatches a real event; resolves after the update
  assert.equal(button.textContent.trim(), "count: 1");
});

What you get

Helper	What it does
`render(component, options?)`	Mounts into a fresh container; returns `{ container, unmount, debug, ...queries }`. Tracked for `cleanup()`.
`screen`	The same queries, bound to `document.body`.
`getBy* / queryBy* / getAllBy* / findBy*`	Find elements by Text, Role (with `name`), TestId (`data-testid`), or LabelText. `getBy` throws if none / many; `queryBy` returns `null`; `findBy` retries (async).
`fireEvent(el, type, init?)` + `.click/.input/.change/.submit/…`	Dispatch a real DOM event; `await` it to see the batched update. Pass `{ target: { value } }` to set a property first.
`waitFor(fn, options?)`	Retry `fn` until it stops throwing (for async data / animations).
`tick()`	`await tick()` — yield until Zoijs's reactive flush has run.
`cleanup()`	Unmount everything `render` created and remove its containers (use in `afterEach`).
`mockRouter(init?)`	A controllable stand-in for an `@zoijs/router` instance (`setPath` / `setQuery`).

Philosophy

These helpers wrap the platform; they don't replace it. There's no custom renderer and no snapshot format that re-implements the DOM — you assert on real nodes with textContent, getAttribute, and friends. Learn more at zoijs.dev.

JSPM

@zoijs/testing

Package Exports

Readme

@zoijs/testing

Install

Use it

What you get

Philosophy

License