Version v2.1.0 Size 1.5 KB gzip Dependencies Zero dependencies
ore
refineWhy Assay?
Assay provides focused DOM test primitives that work with vanilla elements, custom elements, and framework-rendered output. It scopes queries, dispatches exact browser event classes, and waits on explicit conditions without imposing a renderer or browser automation stack.
ts
// Before
button.dispatchEvent(new MouseEvent('click', { bubbles: true }));
await new Promise((resolve) => setTimeout(resolve, 100));
// After
fireClick(view.get('button.submit'));
await waitUntil(() => view.queryByText('Saved') !== null);| Feature | Assay | Testing Library DOM | Browser automation |
|---|---|---|---|
| Bundle size | 1.5 KB | Larger query layer | Browser runtime required |
| Zero dependencies | |||
| Scoped DOM queries | within() and shadow helpers | Renderer-oriented queries | Manual selectors |
| Deterministic waits | waitUntil() and waitForEvent() | Framework-dependent | Full browser timing |
Use Assay when a DOM unit test needs readable queries, dispatched events, or a bounded async wait without adopting a rendering framework.
Consider browser integration tests when correctness depends on browser default actions, focus behavior, pointer capture, layout, or accessibility-tree behavior.
Installation
sh
pnpm add -D @vielzeug/assaysh
npm install -D @vielzeug/assaysh
yarn add -D @vielzeug/assayQuick Start
Scope a test fixture, dispatch an event, and wait for resulting DOM state.
ts
import { fireClick, waitUntil, within } from '@vielzeug/assay';
const panel = document.createElement('section');
panel.innerHTML = '<button>Save</button><output></output>';
panel.querySelector('button')!.addEventListener('click', () => {
panel.querySelector('output')!.textContent = 'Saved';
});
const view = within(panel);
fireClick(view.get('button'));
await waitUntil(() => view.queryByText('Saved') !== null);Features
within(root)scopes nullable and required DOM queries.queryInShadow,queryPart, andgetSlottedcross custom-element boundaries explicitly.fireClick,fireInput,fireKeyDown, and peers dispatch exact synchronous events.waitUntil,retry, andwaitForEventprovide bounded, abortable async waiting.delayandnextTickmodel explicit timer and microtask scheduling.AssayError,AssayQueryError, andAssayTimeoutErrorprovide typed failures.