@opentf/web-test

DOM testing utilities for OTF Web: mount compiled components or page factories, query them with Testing Library, and tear down their lifecycle after each test.

Installation

pnpm add -D @opentf/web-test @opentf/esdev-plugin-web

Install esdev 0.14 or newer. The test runner supplies the DOM; this package does not install a replacement DOM or its own compiler plugin.

Configuration

Create esdev.test.json:

{
  "plugins": [{
    "module": "@opentf/esdev-plugin-web",
    "export": "createOtfwPlugin",
    "options": { "target": "csr", "failOnError": true }
  }],
  "test": { "setup": ["@opentf/web-test/setup"] }
}

The plugin compiles JSX imports. The per-file setup registers afterEach(cleanup). This follows esdev's test configuration.

Usage

import { expect, test } from "runtime:test";
import { render } from "@opentf/web-test";
import Counter from "./Counter.jsx";

test("increments", () => {
  const { getByRole } = render(Counter);
  const button = getByRole("button", { name: "Count: 0" });
  button.click();
  expect(button.textContent).toBe("Count: 1");
});

esdev test --config=esdev.test.json --dom

User interactions

userEvent is re-exported from @testing-library/user-event. Run its session, typing, selection and clipboard workflows in a real browser:

import { userEvent } from "@opentf/web-test";
const user = userEvent.setup();
await user.click(button);
await user.type(input, "Ada");

esdev test --config=esdev.test.json --browser

Install a supported browser and its matching driver as described in esdev browser testing. In esdev 0.14's native DOM, userEvent.setup() cannot replace the frozen navigator's clipboard, and input selection is incomplete. Use native DOM actions for --dom tests, or --browser for full Testing Library interaction sequences.

API

• render(Component, props = {}): mounts a compiled component class using its registered .tag, a page factory, or a tag string. Props are assigned before connection. Returns container, unmount() and bound Testing Library queries.
• unmount(): tears down factory lifecycle and reactive scopes, removes the container, and lets custom-element disconnect run component cleanup. Repeated calls are safe.
• cleanup(): unmounts every view created by render(). The setup module calls it after each test; otherwise import afterEach from runtime:test and register afterEach(cleanup) yourself.
• userEvent: Testing Library's interaction API for browser tests.

DOM custom-element lifecycle reactions can settle asynchronously; await observable cleanup effects when testing teardown.