@exactjs/testing

Runner-neutral tools for testing eXact components and server behavior.

Component tests

import { testComponent } from '@exactjs/testing';

const view = await testComponent(Counter).props({ step: 2 }).mount();
await view.getByRole('button').click();

expect(view.root.state()).toMatchObject({ count: 2 });
view.unmount();

The mounted view provides accessible role and text queries, settled user events, component state and context inspection, and DOM-focused matchers.

Tests that exercise compiler-emitted plugin markers can pass the application bundle's local enhancementCatalog through .configure() or mountTest() options. The mount helper activates the enhancement renderer only when that option is present, so ordinary component tests retain the enhancement-free DOM entry point.

Server and client/server tests

Use testServerComponent() with a compiled .exact.server artifact to render and inspect server components. Captures retain settled state, props, context and parent/child relationships after server cleanup, including stateless components and repeated uses of the same component. Use mountClientServerTest() to hydrate generated client islands against an in-memory request handler and record protocol exchanges without depending on generated operation IDs. By default, mount waits for eager lazy islands to finish loading and adopting before returning. Load failures reject mount. Interaction-deferred islands stay dormant until activated. hydratedIslands reflects the current hydration observations.

Pass the production registration's islands to mountClientServerTest() and spread the full registration into hydrate, including generated continuation contracts when they are omitted from SSR HTML. Keep the SSR renderer import in a compiled application or fixture module to retain optional enhancement integration. For multi-stage tasks, poll for the final page state before unmounting.

Pending work and progress

For startup progress, pass settleTasks: false to mountClientServerTest(). It returns without waiting for client tasks or island loads. Wait for the expected control or intermediate state before interacting. Event helpers also accept { settleTasks: false } to observe pending work.

A controlled test service can hold completion until the test has asserted a progress update, then release the result and await view.settle(). Consumed protocol lines appear incrementally in view.protocol.exchanges[n].response.events. Progress snapshots may be coalesced, so assertions should describe meaningful state rather than requiring every producer report to arrive. Always call view.unmount() during cleanup, including when an assertion fails.

Test runners

Most projects should use @exactjs/vitest, @exactjs/jest, or @exactjs/bun-test. These packages configure compilation, DOM globals, and matchers for their runner.

Low-level framework tests may import @exactjs/testing/internal/fixtures to construct low-level native operations. Application tests should compile authored components normally.

Documentation | Source on GitHub