@opentf/afw-test

Render, query and interact with AFW components in tests

Docs | API | Changelog | GitHub

An Open Tech Foundation project

Mount a compiled component or a page, query it the way a user would with Testing Library, and let the setup module tear it down after each test, lifecycle and reactive scopes included.

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

test("increments on click", async () => {
  const { getByRole } = render(Counter);
  const button = getByRole("button", { name: "Count: 0" });

  await userEvent.setup().click(button);

  expect(button.textContent).toBe("Count: 1");
});

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

[!NOTE] Alpha. The API can change between minor versions; see the changelog.

Install

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

Requires esdev 0.17 or newer. The test runner supplies the DOM; this package adds no DOM library and no compiler of its own.

Configure

Create esdev.test.json, which compiles JSX imports for tests and registers automatic cleanup:

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

With Vitest

In the Vite + Node workflow, run the same tests under Vitest. @opentf/vite-plugin-afw compiles components for the test's DOM, and the @opentf/afw-test/vitest setup file registers cleanup after each test:

pnpm add -D @opentf/afw-test @opentf/vite-plugin-afw vite vitest happy-dom

// vite.config.js
import afw from "@opentf/vite-plugin-afw";

export default {
  plugins: [afw()],
  test: {
    environment: "happy-dom", // or "jsdom"
    setupFiles: ["@opentf/afw-test/vitest"],
  },
};

Import test and expect from vitest; render and userEvent work as above.

Two engines

| Command | Runs in | Use for | | --- | --- | --- | | esdev test --config=esdev.test.json --dom | esdev's native DOM | Most component tests: fast, no browser needed | | esdev test --config=esdev.test.json --browser | A real browser engine | Layout, CSS and real event timing |

--browser needs a supported browser and its matching driver; see esdev browser testing.

API

| Export | Purpose | | --- | --- | | render(Component, props?) | Mount a compiled component, a page factory or a tag name; props are set before connection. Returns container, unmount() and bound Testing Library queries | | cleanup() | Unmount everything render() created; the setup module runs it after each test | | userEvent | @testing-library/user-event: clicks, typing, keyboard and selection | | @opentf/afw-test/setup | Registers afterEach(cleanup) for every test file |

unmount() disposes the view's lifecycle hooks and reactive scopes and removes its container; calling it twice is safe. Custom-element disconnect callbacks can settle asynchronously, so await the effect you assert on when testing teardown.

Documentation

| Doc | Purpose | | --- | --- | | Setup | Configuration in detail | | Writing tests | Structure, props and async updates | | Queries | Finding elements by role, label and text | | User events | Simulating real interaction | | Strategies | When to use the native DOM or a real browser |

License

MIT — see LICENSE.