@uniflowed/react-testing 0.0.0-alpha.2

package/index.js

@@ -0,0 +1,32 @@
+// @flow
+//
+// `@uniflowed/react-testing`: React Testing Library's surface, over a real DOM.
+//
+// The library's premise is that a test should reach for an element the way a
+// person does — by the text on it, by the role it plays, by the label next to
+// it — so a test keeps passing when the markup is refactored and stops passing
+// when the thing a user relies on breaks. That premise is worth keeping, so
+// this is the same shape: `render`, `screen`, `fireEvent`, `userEvent`,
+// `waitFor`.
+//
+// It used to be a declaration whose every function threw. `uf test` runs on
+// Node.js, Bun or Deno and none of them has a DOM, so one is installed on
+// first render — which is why a component test needs nothing configured.
+//
+// # Queries
+//
+// Every query is `getBy`, `queryBy`, `findBy`, `getAllBy`, `queryAllBy` or
+// `findAllBy` over the same matcher, and the choice says what the test means:
+// `getBy` asserts presence now, `queryBy` is for asking about absence, and
+// `findBy` waits. They are on `screen`, which searches the whole document so a
+// portal is found, and on the result of `render`, which searches only what it
+// mounted.
+
+export type { Matcher, MatcherOptions } from "./internal/queries.js";
+export type { RenderResult } from "./internal/render.js";
+export type { Queries } from "./internal/screen.js";
+
+export { normalize, accessibleName, roleOf } from "./internal/queries.js";
+export { actively as act, cleanup, render, waitFor } from "./internal/render.js";
+export { dispatch, fireEvent, userEvent } from "./internal/events.js";
+export { screen, within } from "./internal/screen.js";

package/internal/dom.js

@@ -0,0 +1,135 @@
+// @flow
+//
+// A document for a test process that has none.
+//
+// `uf test` runs on Node.js, Bun or Deno, and none of them has a DOM. React
+// needs one before `react-dom` is imported, not after: `react-dom/client`
+// reads `document` while it is being evaluated, so installing the globals has
+// to happen first and exactly once per process.
+//
+// The window is created lazily rather than at import time, because a test file
+// that imports this module and never renders should not pay for a DOM, and
+// because `@uniflowed/lib`'s invariants forbid a package from doing work while
+// it is being imported.
+
+import { Window } from "happy-dom";
+
+/**
+ * The document's own classes, which always replace whatever the host had.
+ *
+ * A document rejects an event built by a different implementation, and Node
+ * defines `Event` and `CustomEvent` itself — `dispatchEvent` refused them with
+ * "parameter 1 is not of type 'Event'" for every event this module had no more
+ * specific constructor for. Whatever the host already had, the document's own
+ * classes are the ones that work with the document.
+ */
+const CLASSES = [
+  "Node",
+  "Element",
+  "HTMLElement",
+  "HTMLInputElement",
+  "HTMLTextAreaElement",
+  "HTMLSelectElement",
+  "HTMLButtonElement",
+  "HTMLAnchorElement",
+  "SVGElement",
+  "Event",
+  "CustomEvent",
+  "MouseEvent",
+  "KeyboardEvent",
+  "InputEvent",
+  "FocusEvent",
+  "PointerEvent",
+  "SubmitEvent",
+  "DOMParser",
+  "MutationObserver",
+  "ResizeObserver",
+  "IntersectionObserver",
+];
+
+/**
+ * Functions that read the window they came from, so they are bound to it.
+ */
+const FUNCTIONS = ["getComputedStyle", "requestAnimationFrame", "cancelAnimationFrame"];
+
+/**
+ * Objects a page has, installed only where the host has none.
+ *
+ * `navigator` is the reason for the distinction: on Node it is an accessor
+ * with no setter, and assigning to it throws. A test does not need it
+ * replaced — it needs it to exist.
+ */
+const OBJECTS = ["location", "history", "localStorage", "sessionStorage", "navigator"];
+
+let installed: mixed = null;
+
+/**
+ * Install a DOM on the global object, once.
+ *
+ * Returns the window, so a caller that wants the document can have it without
+ * reaching through `globalThis`. Calling this a second time is free and does
+ * not replace the document — replacing it mid-process would strand every React
+ * root already mounted in the old one.
+ */
+export function installDom(): mixed {
+  if (installed != null) {
+    return installed;
+  }
+
+  // A real browser is not required to be absent — a project may already be
+  // running these tests in one, and then the page's own DOM is the right one.
+  if (typeof globalThis.document !== "undefined") {
+    installed = globalThis.window ?? globalThis;
+    return installed;
+  }
+
+  const win = new Window({ url: "http://localhost/" });
+
+  for (const name of CLASSES) {
+    const value = (win as any)[name];
+    if (value !== undefined) {
+      define(name, value);
+    }
+  }
+  for (const name of FUNCTIONS) {
+    const value = (win as any)[name];
+    if (typeof value === "function") {
+      define(name, value.bind(win));
+    }
+  }
+  for (const name of OBJECTS) {
+    const value = (win as any)[name];
+    if (value !== undefined && globalThis[name] === undefined) {
+      define(name, value);
+    }
+  }
+
+  // React reads these to decide it is in a browser and to pick its event
+  // system, and they must be the objects the elements belong to.
+  define("window", win as any);
+  define("document", (win as any).document);
+
+  installed = win;
+  return installed;
+}
+
+/**
+ * Assign a global, even where the host declared it as a getter.
+ *
+ * `navigator` on Node is an accessor with no setter, so a plain assignment
+ * throws; anything installed here has to be defined rather than assigned.
+ */
+function define(name: string, value: mixed): void {
+  Object.defineProperty(globalThis, name, {
+    value,
+    writable: true,
+    configurable: true,
+    enumerable: true,
+  });
+}
+
+/** The document tests query, installing one if the process has none. */
+export function documentOf(): Document {
+  installDom();
+  return globalThis.document as any;
+}

package/internal/events.js

@@ -0,0 +1,338 @@
+// @flow
+//
+// Making things happen to the page.
+//
+// Two layers, because tests want two different things.
+//
+// `fireEvent` dispatches one event. It is the right tool when the test is
+// about the handler: "clicking calls onSelect once".
+//
+// `userEvent` performs what a person did, which is almost never one event.
+// Clicking a button is pointerdown, mousedown, focus, pointerup, mouseup and
+// click; typing is a keydown, an input and a keyup per character, with the
+// value updated in between. A component that listens for `mousedown` — a menu
+// that closes on outside press, say — behaves correctly under a real click and
+// not at all under a bare `click` event, and a test that only fires `click`
+// would pass while the feature was broken.
+
+import { actively } from "./render.js";
+
+/** Event constructors by DOM event name, with the right interface for each. */
+const EVENT_TYPES: { readonly [string]: string } = {
+  click: "MouseEvent",
+  dblclick: "MouseEvent",
+  mousedown: "MouseEvent",
+  mouseup: "MouseEvent",
+  mouseover: "MouseEvent",
+  mouseout: "MouseEvent",
+  mouseenter: "MouseEvent",
+  mouseleave: "MouseEvent",
+  mousemove: "MouseEvent",
+  contextmenu: "MouseEvent",
+  keydown: "KeyboardEvent",
+  keyup: "KeyboardEvent",
+  keypress: "KeyboardEvent",
+  focus: "FocusEvent",
+  blur: "FocusEvent",
+  focusin: "FocusEvent",
+  focusout: "FocusEvent",
+  input: "InputEvent",
+  pointerdown: "PointerEvent",
+  pointerup: "PointerEvent",
+  pointermove: "PointerEvent",
+};
+
+/** Events that do not bubble, whatever else is said about them. */
+const NON_BUBBLING = new Set(["focus", "blur", "mouseenter", "mouseleave"]);
+
+/**
+ * The bubbling event React actually listens for, for each one that does not
+ * bubble.
+ *
+ * React attaches every listener to the root container rather than to the
+ * element, so it can only hear events that reach the root. `focus` and `blur`
+ * never do. React's answer is to listen for `focusin` and `focusout` — which
+ * are the same moments and do bubble — and surface them to a component as
+ * `onFocus` and `onBlur`.
+ *
+ * So dispatching a bare `focus` calls nothing: the element's own listener, if
+ * a test added one directly, and no React handler at all. The test then
+ * asserts on a component that never re-rendered and reads as a component bug.
+ * Firing the pair is what a browser does anyway — a real focus is a `focus`
+ * and a `focusin` — so this is less a workaround than the missing half.
+ */
+const ALSO_BUBBLES: { readonly [string]: string } = {
+  focus: "focusin",
+  blur: "focusout",
+};
+
+function construct(name: string, init: { readonly [string]: mixed }): Event {
+  const interfaceName = EVENT_TYPES[name] ?? "Event";
+  const Constructor = (globalThis as any)[interfaceName] ?? globalThis.Event;
+  const options = {
+    bubbles: !NON_BUBBLING.has(name),
+    cancelable: true,
+    ...init,
+  };
+  try {
+    return new Constructor(name, options);
+  } catch {
+    // A host whose constructor is stricter than the init we were handed.
+    return new globalThis.Event(name, options);
+  }
+}
+
+/**
+ * Dispatch one event, inside `act`.
+ *
+ * Returns whether the event ran to completion — `false` when a handler called
+ * `preventDefault`, which is what `dispatchEvent` reports and what a test
+ * asserting "the form did not submit" needs.
+ */
+export function dispatch(
+  target: EventTarget,
+  name: string,
+  init?: { readonly [string]: mixed },
+): boolean {
+  const event = construct(name, init ?? {});
+  const paired = ALSO_BUBBLES[name];
+  let ran = true;
+  actively(() => {
+    ran = target.dispatchEvent(event);
+    if (paired != null) {
+      // Both, in the order a browser sends them, and inside the same `act` so
+      // the component re-renders once rather than twice.
+      target.dispatchEvent(construct(paired, init ?? {}));
+    }
+  });
+  return ran;
+}
+
+/**
+ * `fireEvent.click(element)`, and one entry per event name.
+ *
+ * A proxy rather than a written-out table: the set of DOM events is long,
+ * grows, and every entry would be the same line. `fireEvent(target, name)`
+ * also works, for an event whose name is computed.
+ */
+export const fireEvent: any = new Proxy(
+  (target: EventTarget, name: string, init?: { readonly [string]: mixed }) =>
+    dispatch(target, name, init),
+  {
+    get(base, property) {
+      if (typeof property !== "string") {
+        return (base as any)[property];
+      }
+      if (property in base) {
+        return (base as any)[property];
+      }
+      return (target: EventTarget, init?: { readonly [string]: mixed }) =>
+        dispatch(target, property.toLowerCase(), init);
+    },
+  },
+);
+
+/** Set a control's value the way a browser does, so React sees the change. */
+function setValue(element: HTMLElement, value: string): void {
+  const target: any = element;
+  // React tracks the last value it wrote on the node and skips an `input`
+  // event whose value it believes it already knows. Writing through the
+  // prototype's setter is what a browser does and what clears that.
+  const prototype = Object.getPrototypeOf(target);
+  const descriptor = Object.getOwnPropertyDescriptor(prototype, "value");
+  if (descriptor?.set != null) {
+    descriptor.set.call(target, value);
+  } else {
+    target.value = value;
+  }
+}
+
+/** A key's `key`, `code` and printable text. */
+function describeKey(key: string): {| key: string, code: string, text: string | null |} {
+  const named: { readonly [string]: {| code: string, text: string | null |} } = {
+    Enter: { code: "Enter", text: "\n" },
+    Tab: { code: "Tab", text: null },
+    Escape: { code: "Escape", text: null },
+    Backspace: { code: "Backspace", text: null },
+    Delete: { code: "Delete", text: null },
+    ArrowUp: { code: "ArrowUp", text: null },
+    ArrowDown: { code: "ArrowDown", text: null },
+    ArrowLeft: { code: "ArrowLeft", text: null },
+    ArrowRight: { code: "ArrowRight", text: null },
+    Home: { code: "Home", text: null },
+    End: { code: "End", text: null },
+    " ": { code: "Space", text: " " },
+  };
+  const entry = named[key];
+  if (entry != null) {
+    return { key, code: entry.code, text: entry.text };
+  }
+  return { key, code: `Key${key.toUpperCase()}`, text: key };
+}
+
+/** Elements the tab order includes, in document order. */
+function tabbable(): Array<HTMLElement> {
+  const selector =
+    'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+  return Array.from(globalThis.document.querySelectorAll(selector)).filter(
+    (element: any) => element.getAttribute("aria-hidden") !== "true",
+  );
+}
+
+/**
+ * What a person did, rather than what the DOM emitted.
+ *
+ * Every method is async because that is what makes a test written with it
+ * correct as it grows: the moment an interaction leads to something awaited —
+ * a fetch, a transition, a lazily loaded panel — a synchronous helper would
+ * return before the result existed, and the test would need a sleep. Awaiting
+ * from the start means adding that behaviour later changes nothing.
+ */
+export const userEvent = {
+  /** Press and release, with the events a real click produces, in order. */
+  async click(element: HTMLElement, init?: { readonly [string]: mixed }): Promise<void> {
+    if ((element as any).disabled === true) {
+      return;
+    }
+    dispatch(element, "pointerdown", init);
+    dispatch(element, "mousedown", init);
+    focus(element);
+    dispatch(element, "pointerup", init);
+    dispatch(element, "mouseup", init);
+    dispatch(element, "click", init);
+    await settle();
+  },
+
+  /** Two clicks and a dblclick. */
+  async dblClick(element: HTMLElement): Promise<void> {
+    await userEvent.click(element);
+    await userEvent.click(element);
+    dispatch(element, "dblclick");
+    await settle();
+  },
+
+  /**
+   * Type into a control, one character at a time.
+   *
+   * Per character rather than setting the value once, because a component
+   * that reacts to each keystroke — a search box that filters, a field that
+   * rejects a character — behaves differently, and the difference is the thing
+   * usually being tested.
+   */
+  async type(element: HTMLElement, text: string): Promise<void> {
+    focus(element);
+    for (const character of text) {
+      const { key, code, text: printable } = describeKey(character);
+      dispatch(element, "keydown", { key, code });
+      if (printable != null && printable !== "\n") {
+        setValue(element, `${(element as any).value ?? ""}${printable}`);
+        dispatch(element, "input", { data: printable });
+      }
+      dispatch(element, "keyup", { key, code });
+    }
+    await settle();
+  },
+
+  /** Empty a control, the way selecting everything and deleting would. */
+  async clear(element: HTMLElement): Promise<void> {
+    focus(element);
+    setValue(element, "");
+    dispatch(element, "input", {});
+    await settle();
+  },
+
+  /** Press keys at whatever has focus. Named keys go in braces: `{Enter}`. */
+  async keyboard(sequence: string): Promise<void> {
+    const target: any = globalThis.document.activeElement ?? globalThis.document.body;
+    for (const token of parseKeys(sequence)) {
+      const { key, code, text } = describeKey(token);
+      dispatch(target, "keydown", { key, code });
+      if (text != null && text !== "\n" && target.value !== undefined) {
+        setValue(target, `${target.value ?? ""}${text}`);
+        dispatch(target, "input", { data: text });
+      }
+      dispatch(target, "keyup", { key, code });
+    }
+    await settle();
+  },
+
+  /** Move focus the way the Tab key does. */
+  async tab(options?: {| readonly shift?: boolean |}): Promise<void> {
+    const order = tabbable();
+    if (order.length === 0) {
+      return;
+    }
+    const active: any = globalThis.document.activeElement;
+    const at = order.indexOf(active);
+    const shift = options?.shift ?? false;
+    const next =
+      at < 0
+        ? shift
+          ? order[order.length - 1]
+          : order[0]
+        : order[(at + (shift ? -1 : 1) + order.length) % order.length];
+    focus(next);
+    await settle();
+  },
+
+  /** Choose options in a select. */
+  async selectOptions(
+    element: HTMLElement,
+    values: string | $ReadOnlyArray<string>,
+  ): Promise<void> {
+    const wanted = typeof values === "string" ? [values] : values;
+    const select: any = element;
+    for (const option of Array.from(select.options ?? [])) {
+      (option as any).selected = wanted.includes((option as any).value);
+    }
+    dispatch(element, "input");
+    dispatch(element, "change");
+    await settle();
+  },
+
+  /** Move focus away, which is what makes a blur-validated field validate. */
+  async tabAway(element: HTMLElement): Promise<void> {
+    dispatch(element, "blur");
+    (element as any).blur?.();
+    await settle();
+  },
+};
+
+function focus(element: HTMLElement): void {
+  const previous: any = globalThis.document.activeElement;
+  if (previous === element) {
+    return;
+  }
+  actively(() => {
+    (element as any).focus?.();
+  });
+  if (globalThis.document.activeElement !== element) {
+    // A host whose `focus` does not move `activeElement`; the events are what
+    // components listen for, so dispatch them regardless.
+    dispatch(element, "focus");
+  }
+}
+
+/** `{Enter}` and `{Escape}` as single tokens; everything else per character. */
+function parseKeys(sequence: string): Array<string> {
+  const keys = [];
+  let index = 0;
+  while (index < sequence.length) {
+    if (sequence[index] === "{") {
+      const close = sequence.indexOf("}", index);
+      if (close > index) {
+        keys.push(sequence.slice(index + 1, close));
+        index = close + 1;
+        continue;
+      }
+    }
+    keys.push(sequence[index]);
+    index += 1;
+  }
+  return keys;
+}
+
+/** Let React finish anything the interaction started. */
+async function settle(): Promise<void> {
+  await actively(() => Promise.resolve());
+}

package/internal/queries.js

@@ -0,0 +1,311 @@
+// @flow
+//
+// Finding an element the way a person would.
+//
+// Every query takes a *matcher* — a string, a regular expression, or a
+// predicate — and every one comes in four forms, because those are the four
+// different questions a test asks:
+//
+//   getBy…     it is there now, and there is one. Anything else is a failure.
+//   queryBy…   it may not be there, and its absence is the thing being asked.
+//   findBy…    it will be there shortly. Waits.
+//   getAllBy…  there are several, and how many matters.
+//
+// The distinction matters because `getBy` failing with "found none" is a much
+// better test failure than `queryBy` returning null and the assertion failing
+// three lines later on `null.textContent`.
+
+/** What a query will accept as a description of the thing to find. */
+export type Matcher = string | RegExp | ((content: string, element: Element) => boolean);
+
+/** How exactly a string matcher has to match. */
+export type MatcherOptions = {|
+  /** `false` matches a substring, case-insensitively. Defaults to `true`. */
+  readonly exact?: boolean,
+|};
+
+/**
+ * Collapse whitespace the way a browser does when it lays text out.
+ *
+ * A test asks for "Save changes"; the markup may hold a newline and eleven
+ * spaces between the two words because that is how the JSX was indented. The
+ * reader sees one space, so the query matches one space.
+ */
+export function normalize(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+function matches(
+  content: string,
+  element: Element,
+  matcher: Matcher,
+  options?: MatcherOptions,
+): boolean {
+  if (typeof matcher === "function") {
+    return matcher(content, element);
+  }
+  if (matcher instanceof RegExp) {
+    return matcher.test(content);
+  }
+  const exact = options?.exact ?? true;
+  return exact
+    ? content === normalize(matcher)
+    : content.toLowerCase().includes(normalize(matcher).toLowerCase());
+}
+
+/** The text a reader would see in this element, whitespace collapsed. */
+export function textOf(element: Element): string {
+  return normalize(element.textContent ?? "");
+}
+
+function candidates(root: ParentNode, selector: string): Array<Element> {
+  return Array.from(root.querySelectorAll(selector));
+}
+
+/** Elements whose own visible text matches. */
+export function allByText(
+  root: ParentNode,
+  matcher: Matcher,
+  options?: MatcherOptions,
+): Array<Element> {
+  // Only the element closest to the text, not every ancestor that contains it:
+  // asking for "Save" should find the button, not the button and the form and
+  // the body.
+  return candidates(root, "*").filter((element) => {
+    if (!matches(textOf(element), element, matcher, options)) {
+      return false;
+    }
+    return !Array.from(element.children).some((child) =>
+      matches(textOf(child), child, matcher, options),
+    );
+  });
+}
+
+/** Elements with this ARIA role, whether written down or implied by the tag. */
+export function allByRole(
+  root: ParentNode,
+  role: string,
+  options?: {| readonly name?: Matcher, readonly exact?: boolean |},
+): Array<Element> {
+  const found = candidates(root, "*").filter((element) => roleOf(element) === role);
+  const name = options?.name;
+  if (name == null) {
+    return found;
+  }
+  return found.filter((element) =>
+    matches(accessibleName(element), element, name, { exact: options?.exact ?? true }),
+  );
+}
+
+/** Form controls labelled by this text. */
+export function allByLabelText(
+  root: ParentNode,
+  matcher: Matcher,
+  options?: MatcherOptions,
+): Array<Element> {
+  const found = [];
+  for (const label of candidates(root, "label")) {
+    if (!matches(textOf(label), label, matcher, options)) {
+      continue;
+    }
+    const control = controlFor(root, label);
+    if (control != null) {
+      found.push(control);
+    }
+  }
+  // `aria-label` names a control with no label element of its own.
+  for (const element of candidates(root, "[aria-label]")) {
+    const label = element.getAttribute("aria-label") ?? "";
+    if (matches(normalize(label), element, matcher, options) && !found.includes(element)) {
+      found.push(element);
+    }
+  }
+  return found;
+}
+
+/** Elements with this placeholder. */
+export function allByPlaceholderText(
+  root: ParentNode,
+  matcher: Matcher,
+  options?: MatcherOptions,
+): Array<Element> {
+  return candidates(root, "[placeholder]").filter((element) =>
+    matches(normalize(element.getAttribute("placeholder") ?? ""), element, matcher, options),
+  );
+}
+
+/** Elements marked for tests, which is the query of last resort. */
+export function allByTestId(
+  root: ParentNode,
+  matcher: Matcher,
+  options?: MatcherOptions,
+): Array<Element> {
+  return candidates(root, "[data-testid]").filter((element) =>
+    matches(normalize(element.getAttribute("data-testid") ?? ""), element, matcher, options),
+  );
+}
+
+/** Elements whose value matches, for inputs and selects. */
+export function allByDisplayValue(
+  root: ParentNode,
+  matcher: Matcher,
+  options?: MatcherOptions,
+): Array<Element> {
+  return candidates(root, "input, textarea, select").filter((element) =>
+    matches(normalize((element as any).value ?? ""), element, matcher, options),
+  );
+}
+
+/**
+ * The control a label labels.
+ *
+ * `for` first, because it is explicit; then a control nested inside the label,
+ * which is the other way HTML allows it.
+ */
+function controlFor(root: ParentNode, label: Element): Element | null {
+  const id = label.getAttribute("for");
+  if (id != null && id !== "") {
+    const byId = (root as any).querySelector?.(`#${cssEscape(id)}`);
+    if (byId != null) {
+      return byId;
+    }
+  }
+  return label.querySelector("input, textarea, select, button, [role]");
+}
+
+/** Escape an id for use in a selector, since an id may contain anything. */
+function cssEscape(value: string): string {
+  return value.replace(/([^\w-])/g, "\\$1");
+}
+
+/** Roles a tag has without being told. */
+const IMPLICIT_ROLES: { readonly [string]: string } = {
+  a: "link",
+  article: "article",
+  aside: "complementary",
+  button: "button",
+  dialog: "dialog",
+  footer: "contentinfo",
+  form: "form",
+  h1: "heading",
+  h2: "heading",
+  h3: "heading",
+  h4: "heading",
+  h5: "heading",
+  h6: "heading",
+  header: "banner",
+  hr: "separator",
+  img: "img",
+  li: "listitem",
+  main: "main",
+  nav: "navigation",
+  ol: "list",
+  option: "option",
+  progress: "progressbar",
+  section: "region",
+  select: "combobox",
+  table: "table",
+  tbody: "rowgroup",
+  td: "cell",
+  textarea: "textbox",
+  th: "columnheader",
+  tr: "row",
+  ul: "list",
+};
+
+/** The input types that are not a textbox. */
+const INPUT_ROLES: { readonly [string]: string } = {
+  button: "button",
+  checkbox: "checkbox",
+  email: "textbox",
+  image: "button",
+  number: "spinbutton",
+  radio: "radio",
+  range: "slider",
+  reset: "button",
+  search: "searchbox",
+  submit: "button",
+  tel: "textbox",
+  text: "textbox",
+  url: "textbox",
+};
+
+/** This element's role: what it says, or what its tag implies. */
+export function roleOf(element: Element): string | null {
+  const explicit = element.getAttribute("role");
+  if (explicit != null && explicit !== "") {
+    return explicit.trim().split(/\s+/)[0];
+  }
+  const tag = element.tagName.toLowerCase();
+  if (tag === "input") {
+    const type = (element.getAttribute("type") ?? "text").toLowerCase();
+    return INPUT_ROLES[type] ?? "textbox";
+  }
+  if (tag === "a" && element.getAttribute("href") == null) {
+    // A link without a destination is not a link.
+    return "generic";
+  }
+  return IMPLICIT_ROLES[tag] ?? null;
+}
+
+/**
+ * The name a screen reader would announce.
+ *
+ * `aria-label`, then the element `aria-labelledby` points at, then a label
+ * element, then the element's own text. Not the whole specification — that is
+ * a document of its own — but the order that decides almost every real case.
+ */
+export function accessibleName(element: Element): string {
+  const label = element.getAttribute("aria-label");
+  if (label != null && label !== "") {
+    return normalize(label);
+  }
+
+  const labelledBy = element.getAttribute("aria-labelledby");
+  if (labelledBy != null && labelledBy !== "") {
+    const parts = labelledBy
+      .split(/\s+/)
+      .map((id) => element.ownerDocument?.getElementById(id))
+      .filter(Boolean)
+      .map((target) => textOf(target as any));
+    if (parts.length > 0) {
+      return normalize(parts.join(" "));
+    }
+  }
+
+  const id = element.getAttribute("id");
+  if (id != null && id !== "") {
+    const own = element.ownerDocument?.querySelector(`label[for="${cssEscape(id)}"]`);
+    if (own != null) {
+      return textOf(own);
+    }
+  }
+
+  if (element.tagName.toLowerCase() === "input") {
+    const type = (element.getAttribute("type") ?? "").toLowerCase();
+    if (type === "submit" || type === "button" || type === "reset") {
+      return normalize((element as any).value ?? "");
+    }
+  }
+
+  return textOf(element);
+}
+
+/** Why a query failed, with enough of the DOM to see why. */
+export function queryFailure(
+  kind: string,
+  matcher: Matcher,
+  root: ParentNode,
+  found: number,
+): Error {
+  const description =
+    typeof matcher === "function"
+      ? "the given predicate"
+      : matcher instanceof RegExp
+        ? String(matcher)
+        : JSON.stringify(matcher);
+  const html = (root as any).innerHTML ?? "";
+  const shown = html.length > 2000 ? `${html.slice(0, 2000)}\n…` : html;
+  const count = found === 0 ? "found nothing" : `found ${found} elements and needed exactly one`;
+  return new Error(`${kind} ${description}: ${count}\n\n${shown}`);
+}

package/internal/render.js

@@ -0,0 +1,170 @@
+// @flow
+//
+// Mounting a component into a real document.
+//
+// Everything that changes the tree goes through React's `act`, which is what
+// makes a test able to assert immediately afterwards: `act` runs the render,
+// the effects, and the microtasks React queued, then returns. Without it a
+// test asserts against the DOM as it was before React got to it, and the fix
+// people reach for is a sleep.
+
+import { createRequire } from "node:module";
+
+// A type-only import: `React.Node` is the only thing this module needs from
+// React itself, and importing the namespace as a value left an unused binding
+// in the bundle.
+import type * as React from "@uniflowed/react";
+import { act } from "@uniflowed/react";
+
+import { installDom } from "./dom.js";
+
+/** What `render` hands back. */
+export type RenderResult = {|
+  /** The element the tree was mounted into. */
+  readonly container: Element,
+  /** The document body, which is where a portal ends up. */
+  readonly baseElement: Element,
+  /** Render different elements into the same container. */
+  readonly rerender: (ui: React.Node) => void,
+  /** Take the tree down and remove the container. */
+  readonly unmount: () => void,
+  /** The container's markup, for a failure message. */
+  readonly asFragment: () => string,
+|};
+
+type Mounted = {|
+  container: Element,
+  root: { render(node: React.Node): void, unmount(): void },
+|};
+
+const mounted: Array<Mounted> = [];
+
+/**
+ * Render `ui` into a fresh container in the document body.
+ *
+ * Anything still mounted from an earlier `render` is taken down first. `screen`
+ * queries the whole document, so a tree left over from the previous test would
+ * make "there is exactly one Save button" false for reasons that have nothing
+ * to do with the test being read.
+ */
+export function render(ui: React.Node, options?: {| readonly container?: Element |}): RenderResult {
+  installDom();
+  cleanup();
+
+  const { createRoot } = requireClient();
+  const container = options?.container ?? createContainer();
+  const root = createRoot(container);
+  mounted.push({ container, root });
+
+  act(() => {
+    root.render(ui);
+  });
+
+  return {
+    container,
+    baseElement: globalThis.document.body as any,
+    rerender: (next: React.Node) => {
+      act(() => {
+        root.render(next);
+      });
+    },
+    unmount: () => {
+      act(() => {
+        root.unmount();
+      });
+      container.remove();
+      const index = mounted.findIndex((entry) => entry.container === container);
+      if (index >= 0) {
+        mounted.splice(index, 1);
+      }
+    },
+    asFragment: () => container.innerHTML,
+  };
+}
+
+/** Unmount everything this module has mounted. */
+export function cleanup(): void {
+  while (mounted.length > 0) {
+    const entry = mounted.pop();
+    if (entry == null) {
+      break;
+    }
+    act(() => {
+      entry.root.unmount();
+    });
+    entry.container.remove();
+  }
+}
+
+function createContainer(): Element {
+  const container = globalThis.document.createElement("div");
+  globalThis.document.body.appendChild(container);
+  return container;
+}
+
+/**
+ * `react-dom/client`, loaded only once a test renders.
+ *
+ * It reads `document` while it is being evaluated, so it cannot be a static
+ * import of this module: ESM evaluates every import before the module body,
+ * and the DOM has to exist first. `render` is synchronous — a test asserts on
+ * the line after it — so this cannot be `await import(…)` either.
+ *
+ * That leaves a synchronous require, through `node:module`. All three hosts
+ * uf supports provide it, and React ships a CommonJS build for exactly this
+ * kind of caller.
+ */
+let client: mixed = null;
+function requireClient(): { createRoot: (Element) => any } {
+  if (client == null) {
+    const load = createRequire(import.meta.url);
+    client = load("react-dom/client") as any;
+  }
+  return client as any;
+}
+
+/**
+ * Run `body`, letting React flush everything it queues.
+ *
+ * Exported because a test that changes state outside an event — a timer
+ * firing, a promise settling — has to tell React that the change happened,
+ * and this is how.
+ */
+export function actively<T>(body: () => T): T {
+  let result: T;
+  act(() => {
+    result = body();
+  });
+  return result as any;
+}
+
+/**
+ * Wait until `body` stops throwing, or give up.
+ *
+ * Polling rather than observing mutations, because what a test waits for is
+ * usually not a DOM change at all — it is a promise resolving, a fetch
+ * settling, a timer firing — and a mutation observer sees none of those.
+ */
+export async function waitFor<T>(
+  body: () => T | Promise<T>,
+  options?: {| readonly timeout?: number, readonly interval?: number |},
+): Promise<T> {
+  const timeout = options?.timeout ?? 1000;
+  const interval = options?.interval ?? 20;
+  const deadline = Date.now() + timeout;
+  let lastError: mixed = null;
+
+  while (true) {
+    try {
+      return await body();
+    } catch (error) {
+      lastError = error;
+    }
+    if (Date.now() >= deadline) {
+      throw lastError instanceof Error
+        ? lastError
+        : new Error(`waitFor timed out after ${timeout}ms: ${String(lastError)}`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, interval));
+  }
+}

package/internal/screen.js

@@ -0,0 +1,113 @@
+// @flow
+//
+// The six forms of every query, generated once.
+//
+// Writing `getByText`, `queryByText`, `findByText`, `getAllByText`,
+// `queryAllByText` and `findAllByText` by hand, for seven queries, is
+// forty-two functions that differ in two decisions: whether finding nothing is
+// an error, and whether to wait. So the two decisions are written once and the
+// forty-two are derived — which also means a new query is one entry rather
+// than six functions.
+
+import {
+  allByDisplayValue,
+  allByLabelText,
+  allByPlaceholderText,
+  allByRole,
+  allByTestId,
+  allByText,
+  queryFailure,
+} from "./queries.js";
+import type { Matcher, MatcherOptions } from "./queries.js";
+import { documentOf } from "./dom.js";
+import { waitFor } from "./render.js";
+
+/** The queries available on `screen` and on `within(element)`. */
+export type Queries = {
+  readonly [string]: (matcher: mixed, options?: mixed) => any,
+};
+
+/** Every query, as the one function each needs. */
+const FINDERS = {
+  Text: allByText,
+  Role: allByRole,
+  LabelText: allByLabelText,
+  PlaceholderText: allByPlaceholderText,
+  TestId: allByTestId,
+  DisplayValue: allByDisplayValue,
+};
+
+/**
+ * The six forms of one finder, bound to a root.
+ *
+ * `getBy` fails when there is not exactly one, and says how many it saw and
+ * what the markup looked like, because "found 3 elements" and "found nothing"
+ * are different bugs and a test that reports neither wastes the reader's time.
+ */
+function forms(name: string, find: Function, root: () => ParentNode): { [string]: Function } {
+  const all = (matcher: Matcher, options?: MatcherOptions) => find(root(), matcher, options);
+
+  return {
+    [`getAllBy${name}`]: (matcher: Matcher, options?: MatcherOptions) => {
+      const found = all(matcher, options);
+      if (found.length === 0) {
+        throw queryFailure(`getAllBy${name}`, matcher, root(), 0);
+      }
+      return found;
+    },
+    [`queryAllBy${name}`]: all,
+    [`getBy${name}`]: (matcher: Matcher, options?: MatcherOptions) => {
+      const found = all(matcher, options);
+      if (found.length !== 1) {
+        throw queryFailure(`getBy${name}`, matcher, root(), found.length);
+      }
+      return found[0];
+    },
+    [`queryBy${name}`]: (matcher: Matcher, options?: MatcherOptions) => {
+      const found = all(matcher, options);
+      if (found.length > 1) {
+        throw queryFailure(`queryBy${name}`, matcher, root(), found.length);
+      }
+      return found[0] ?? null;
+    },
+    [`findBy${name}`]: (matcher: Matcher, options?: MatcherOptions) =>
+      waitFor(() => {
+        const found = all(matcher, options);
+        if (found.length !== 1) {
+          throw queryFailure(`findBy${name}`, matcher, root(), found.length);
+        }
+        return found[0];
+      }),
+    [`findAllBy${name}`]: (matcher: Matcher, options?: MatcherOptions) =>
+      waitFor(() => {
+        const found = all(matcher, options);
+        if (found.length === 0) {
+          throw queryFailure(`findAllBy${name}`, matcher, root(), 0);
+        }
+        return found;
+      }),
+  };
+}
+
+function queriesFor(root: () => ParentNode): Queries {
+  const queries = {};
+  for (const name of Object.keys(FINDERS)) {
+    Object.assign(queries, forms(name, (FINDERS as any)[name], root));
+  }
+  return queries as any;
+}
+
+/**
+ * Queries over the whole document.
+ *
+ * The document rather than the rendered container, because a dialog, a tooltip
+ * and a toast are rendered into a portal outside it — and a test that could
+ * not see them would be unable to assert on the components most likely to have
+ * a bug.
+ */
+export const screen: Queries = queriesFor(() => documentOf().body);
+
+/** The same queries, restricted to one element's subtree. */
+export function within(element: ParentNode): Queries {
+  return queriesFor(() => element);
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@uniflowed/react-testing",
+  "version": "0.0.0-alpha.2",
+  "description": "React Testing Library over a real DOM, part of the Unified Toolchain for Flow.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ubugeeei-prod/uf.git",
+    "directory": "packages/react-testing"
+  },
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "internal"
+  ],
+  "dependencies": {
+    "@uniflowed/core": "0.0.0-alpha.2",
+    "@uniflowed/react": "0.0.0-alpha.2",
+    "happy-dom": "^20.13.2"
+  },
+  "peerDependencies": {
+    "react": ">=19",
+    "react-dom": ">=19"
+  }
+}