@uniflowed/react-testing 0.0.0-alpha.4 → 0.0.0-alpha.6

package/internal/dom.js

@@ -14,6 +14,67 @@
 
 import { Window } from "happy-dom";
 
+/**
+ * A function this module found on a window and knows nothing else about.
+ *
+ * `mixed` in and `mixed` out is the whole contract: these are copied across
+ * for React and for components to call, and nothing here ever calls one.
+ */
+type HostFunction = (...args: $ReadOnlyArray<mixed>) => mixed;
+
+/**
+ * Values kept by name, which is all this module knows about a window, the
+ * global object, or a Storage.
+ *
+ * The indexer is the honest shape rather than a placeholder for a type nobody
+ * wrote: the work this module does is to read names out of a list and hand the
+ * values to `Object.defineProperty`. It does not call them, construct them, or
+ * look inside them, so `mixed` is the amount it knows.
+ */
+type Named = { readonly [string]: mixed };
+
+/**
+ * A window, as this module uses one.
+ *
+ * A table of globals to copy, plus the three functions that are *bound* rather
+ * than copied — and those are named because binding is the one thing an
+ * indexer cannot describe. `typeof win[name] === "function"` refines a `mixed`
+ * to a function whose parameters Flow does not know, and `.bind` is not
+ * something that can be done to one of those:
+ *
+ *     error[incompatible-use]: Cannot call `value.bind` because
+ *     `unknown function` is not a function type.
+ *
+ * So the list of functions to bind, which used to be a `FUNCTIONS` array
+ * beside the other three arrays, is this part of the type instead. One list
+ * rather than two, and it is the one the checker reads.
+ *
+ * `happy-dom` ships TypeScript rather than Flow, so `new Window(…)` is `any`.
+ * This annotation is the first statement anywhere about what comes back, not a
+ * cast that discards one.
+ */
+type HostWindow = {
+  readonly getComputedStyle?: HostFunction,
+  readonly requestAnimationFrame?: HostFunction,
+  readonly cancelAnimationFrame?: HostFunction,
+  readonly [string]: mixed,
+};
+
+/**
+ * The global object, under the one description this module has of it.
+ *
+ * `globalThis` is a namespace to the checker rather than an object, so
+ * `globalThis[name]` is not an expression that can be written —
+ * `Cannot access namespace globalThis with computed property using string` —
+ * and reading an installed global by a name from a list is what deciding
+ * whether to install one requires. Naming the same object as a table says what
+ * those reads are: a name in, and no claim at all about what comes out.
+ *
+ * Writes still go through `define`, because they have to be
+ * `Object.defineProperty`; see the reason there.
+ */
+const globals: Named = globalThis;
+
 /**
  * The document's own classes, which always replace whatever the host had.
  *
@@ -22,6 +83,14 @@ import { Window } from "happy-dom";
  * "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.
+ *
+ * The list is also the list of questions the rest of the package can ask.
+ * `internal/queries.js` and `internal/events.js` narrow an `Element` with
+ * `instanceof HTMLInputElement` rather than reading `.value` off a cast, and
+ * an `instanceof` against a name that was never installed is not a `false` —
+ * it is `ReferenceError: HTMLFieldSetElement is not defined`, from a line
+ * about clicking a tab. So a class this package needs to *recognise* belongs
+ * here as much as one the document needs to accept.
  */
 const CLASSES = [
   "Node",
@@ -31,6 +100,7 @@ const CLASSES = [
   "HTMLTextAreaElement",
   "HTMLSelectElement",
   "HTMLButtonElement",
+  "HTMLFieldSetElement",
   "HTMLAnchorElement",
   "SVGElement",
   "Event",
@@ -47,11 +117,6 @@ const CLASSES = [
   "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.
  *
@@ -90,7 +155,7 @@ function isUsableStorage(value: mixed): boolean {
   if (value == null || typeof value !== "object") {
     return false;
   }
-  const storage: { [string]: mixed } = value as any;
+  const storage: Named = value;
   return (
     typeof storage.getItem === "function" &&
     typeof storage.setItem === "function" &&
@@ -99,7 +164,7 @@ function isUsableStorage(value: mixed): boolean {
   );
 }
 
-let installed: mixed = null;
+let installed: HostWindow | null = null;
 
 /**
  * Install a DOM on the global object, once.
@@ -109,7 +174,7 @@ let installed: mixed = null;
  * not replace the document — replacing it mid-process would strand every React
  * root already mounted in the old one.
  */
-export function installDom(): mixed {
+export function installDom(): HostWindow {
   installActEnvironment();
   if (installed != null) {
     return installed;
@@ -122,31 +187,29 @@ export function installDom(): mixed {
     return installed;
   }
 
-  const win = new Window({ url: "http://localhost/" });
+  const win: HostWindow = new Window({ url: "http://localhost/" });
 
   for (const name of CLASSES) {
-    const value = (win as any)[name];
+    const value = win[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));
-    }
-  }
+  // The three by name rather than from a list: see `HostWindow`.
+  defineBound("getComputedStyle", win.getComputedStyle, win);
+  defineBound("requestAnimationFrame", win.requestAnimationFrame, win);
+  defineBound("cancelAnimationFrame", win.cancelAnimationFrame, win);
   for (const name of OBJECTS) {
-    const value = (win as any)[name];
-    if (value !== undefined && globalThis[name] === undefined) {
+    const value = win[name];
+    if (value !== undefined && globals[name] === undefined) {
       define(name, value);
     }
   }
   for (const name of STORAGE) {
-    if (isUsableStorage(globalThis[name])) {
+    if (isUsableStorage(globals[name])) {
       continue;
     }
-    const value = (win as any)[name];
+    const value = win[name];
     if (isUsableStorage(value)) {
       define(name, value);
     }
@@ -154,8 +217,8 @@ export function installDom(): mixed {
 
   // 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);
+  define("window", win);
+  define("document", win.document);
 
   installed = win;
   return installed;
@@ -216,8 +279,34 @@ function define(name: string, value: mixed): void {
   });
 }
 
+/** Install one of the window's own functions, still reading that window. */
+function defineBound(name: string, fn: HostFunction | void, win: HostWindow): void {
+  if (typeof fn === "function") {
+    define(name, fn.bind(win));
+  }
+}
+
 /** The document tests query, installing one if the process has none. */
 export function documentOf(): Document {
   installDom();
-  return globalThis.document as any;
+  return globalThis.document;
+}
+
+/**
+ * The body a test renders into and queries, installing a document first.
+ *
+ * Separate from `documentOf` because `Document.body` is `HTMLBodyElement |
+ * null` — a document with no `<body>` is a document a parser can produce — and
+ * both callers want the element rather than the question. A document this
+ * module installed has a body, and a document the host already had is a page,
+ * which also has one; the throw is for the third case, and it says what is
+ * missing rather than leaving `Cannot read properties of null (reading
+ * 'appendChild')` to be read at a line about rendering.
+ */
+export function bodyOf(): HTMLElement {
+  const body = documentOf().body;
+  if (body == null) {
+    throw new Error("@uniflowed/react-testing: the document has no <body> to render into");
+  }
+  return body;
 }

package/internal/events.js

@@ -15,8 +15,22 @@
 // not at all under a bare `click` event, and a test that only fires `click`
 // would pass while the feature was broken.
 
+import { bodyOf, documentOf } from "./dom.js";
+import { displayValue } from "./queries.js";
 import { actively } from "./render.js";
 
+/**
+ * What a caller wants the event to carry.
+ *
+ * An indexer, because which properties are meaningful is decided by the event's
+ * *interface* and the interface is decided by the name — `{ key: "Escape" }`
+ * for a `keydown`, `{ clientX: 40 }` for a `pointermove` — and the name is a
+ * string a caller computes. There is no type that says "the initialisers of
+ * whichever interface `name` maps to", so this says what is true: names in,
+ * and what each one means is the DOM's business.
+ */
+export type EventInit = { readonly [string]: mixed };
+
 /** Event constructors by DOM event name, with the right interface for each. */
 const EVENT_TYPES: { readonly [string]: string } = {
   click: "MouseEvent",
@@ -66,22 +80,71 @@ const ALSO_BUBBLES: { readonly [string]: string } = {
   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,
-  };
+/**
+ * The event a name asks for, built by the document's own class for it.
+ *
+ * # Why `Constructor` is `any`
+ *
+ * Neither half of this can be typed.
+ *
+ * Reading it: `globalThis` is a namespace to the checker rather than an
+ * object, and the value under a computed name is `mixed`, which cannot be
+ * `new`ed — refining a `mixed` with `typeof x === "function"` gives a function
+ * whose signature Flow says it does not know.
+ *
+ * Calling it: this is the half that is not uf's to fix. Flow's library
+ * definitions declare every event initialiser dictionary with *writable*
+ * properties — `MouseEvent$MouseEventInit` has `clientX?: number`, not
+ * `readonly clientX?: number` — so those properties are invariant, and no
+ * value whose type was computed rather than written inline can be passed to
+ * one. `{ readonly [string]: mixed }` fails on variance before it fails on
+ * anything else:
+ *
+ *     error[incompatible-variance]: property `bubbles` is read-only in
+ *     `EventInit` but writable in `Event$Init`
+ *     error[incompatible-type]: in property `clientX`: `unknown` is not
+ *     exactly the same as `number`
+ *
+ * — twelve of those for `MouseEvent` alone, and Flow's own advice in the
+ * message is to make the library definition's property readonly. So an
+ * `EventInit` cannot reach an event constructor under any spelling, and this
+ * stays one cast at one line rather than a dozen errors at every call.
+ */
+function construct(name: string, init: EventInit): Event {
+  // One cast, covering the lookup and both constructions; see above.
+  const classes: any = globalThis;
+  const Constructor = classes[EVENT_TYPES[name] ?? "Event"] ?? classes.Event;
+  const options = optionsFor(name, 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);
+    return new classes.Event(name, options);
   }
 }
 
+/**
+ * The defaults an event is built with, under whatever the caller asked for.
+ *
+ * Written as a loop rather than `{ bubbles, cancelable, ...init }` because
+ * spreading an indexer is something Flow declines to compute a type for —
+ * "the indexer `string` may overwrite properties with explicit keys in a way
+ * that Flow cannot track", which is precisely what this is for. Its
+ * suggestion, spreading `init` first, would reverse the precedence and stop a
+ * caller from passing `bubbles: false`; the loop keeps the caller on top,
+ * which is what the spread said.
+ */
+function optionsFor(name: string, init: EventInit): EventInit {
+  const options: { [string]: mixed } = {
+    bubbles: !NON_BUBBLING.has(name),
+    cancelable: true,
+  };
+  for (const key of Object.keys(init)) {
+    options[key] = init[key];
+  }
+  return options;
+}
+
 /**
  * Dispatch one event, inside `act`.
  *
@@ -89,11 +152,7 @@ function construct(name: string, init: { readonly [string]: mixed }): Event {
  * `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 {
+export function dispatch(target: EventTarget, name: string, init?: EventInit): boolean {
   const event = construct(name, init ?? {});
   const paired = ALSO_BUBBLES[name];
   let ran = true;
@@ -114,19 +173,57 @@ export function dispatch(
  * 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.
+ *
+ * # Why the type is still `any`, and what was tried
+ *
+ * The type this wants is a function that also answers to every event name.
+ * Written with an indexer:
+ *
+ *     type FireEvent = {
+ *       (target: EventTarget, name: string, init?: EventInit): boolean,
+ *       readonly [string]: (target: EventTarget, init?: EventInit) => boolean,
+ *     };
+ *
+ * Flow declines the indexer, and is right to. As an `interface`, so the
+ * assignment gets far enough to say why, it reads "an unknown property that
+ * may exist on the inexact function is incompatible with `Firer`" — the value
+ * is a function, a function has `name`, `length`, `call`, `apply` and `bind`,
+ * and the trap below hands those back as themselves because `property in base`
+ * is true for them. None of the five is a DOM event, so the lie is unreachable
+ * from any real call, but a type is not something to be right about on
+ * average.
+ *
+ * The written-out table the runtime deliberately is not — a call signature
+ * plus a named property per event — fails earlier and for a reason no list of
+ * names would fix:
+ *
+ *     error[incompatible-type]: Cannot assign `new Proxy(...)` to `fireEvent`
+ *     because `(target: EventTarget, name: string, init?: EventInit) =>
+ *     boolean` is incompatible with `FireEvent`.
+ *     Functions without statics are not compatible with objects.
+ *
+ * A `Proxy` over a function *is* a function, and Flow will not treat a
+ * function with no statics as an object with properties whatever those
+ * properties are. So no type at all can be assigned to this value: typing
+ * `fireEvent` means changing what it is — a function carrying real static
+ * properties, one per event name, which is a table of a hundred-odd entries
+ * that stops answering to the hundred-and-first. That is a design decision
+ * about a published API and not a cast to remove in passing.
+ *
+ * Left as `any` rather than renamed to `$FlowFixMe`, which would move it out
+ * of `flow/unclear-type`'s sight without moving it out of the package.
  */
 export const fireEvent: any = new Proxy(
-  (target: EventTarget, name: string, init?: { readonly [string]: mixed }) =>
-    dispatch(target, name, init),
+  (target: EventTarget, name: string, init?: EventInit) => dispatch(target, name, init),
   {
     get(base, property) {
       if (typeof property !== "string") {
-        return (base as any)[property];
+        return Reflect.get(base, property);
       }
       if (property in base) {
-        return (base as any)[property];
+        return Reflect.get(base, property);
       }
-      return (target: EventTarget, init?: { readonly [string]: mixed }) =>
+      return (target: EventTarget, init?: EventInit) =>
         dispatch(target, property.toLowerCase(), init);
     },
   },
@@ -134,16 +231,23 @@ export const fireEvent: any = new Proxy(
 
 /** 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;
+  const descriptor = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(element), "value");
+  const set = descriptor?.set;
+  if (set != null) {
+    set.call(element, value);
+  } else if (
+    element instanceof HTMLInputElement ||
+    element instanceof HTMLTextAreaElement ||
+    element instanceof HTMLSelectElement
+  ) {
+    // The fallback, for a host whose control classes keep `value` as an own
+    // property rather than an accessor on the prototype. The three classes are
+    // the ones `displayValue` reads, so what a test writes is what a
+    // `ByDisplayValue` query can find.
+    element.value = value;
   }
 }
 
@@ -170,12 +274,46 @@ function describeKey(key: string): {| key: string, code: string, text: string |
   return { key, code: `Key${key.toUpperCase()}`, text: key };
 }
 
-/** Elements the tab order includes, in document order. */
+/**
+ * Elements the tab order includes, in document order.
+ *
+ * `instanceof HTMLElement` rather than a cast, and it is not only the
+ * checker's question: the next thing done to one of these is `focus`, and
+ * `focus` is a method of `HTMLElement`. The declared return type has always
+ * said `HTMLElement` while the selector could match an `Element` — Flow said
+ * so, "in array element: `Element` is incompatible with `HTMLElement`" — and
+ * anything that reached here without being one would have been handed to a
+ * `(element as any).focus?.()` that silently did nothing, swallowing the Tab.
+ */
 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",
+  const order = [];
+  for (const element of documentOf().querySelectorAll(selector)) {
+    if (element instanceof HTMLElement && element.getAttribute("aria-hidden") !== "true") {
+      order.push(element);
+    }
+  }
+  return order;
+}
+
+/**
+ * Whether a control is disabled, for the elements that can be.
+ *
+ * The classes rather than `(element as any).disabled === true`, which was the
+ * same question asked in a way that answered `any`. `disabled` belongs to the
+ * form controls and to `fieldset`; on a `div` it is an attribute React put in
+ * the markup and not a property, which is why the old test was `=== true`
+ * rather than truthiness, and why the answer for one is still `false`.
+ */
+function isDisabled(element: HTMLElement): boolean {
+  return (
+    (element instanceof HTMLButtonElement ||
+      element instanceof HTMLInputElement ||
+      element instanceof HTMLSelectElement ||
+      element instanceof HTMLTextAreaElement ||
+      element instanceof HTMLFieldSetElement) &&
+    element.disabled
   );
 }
 
@@ -190,8 +328,8 @@ function tabbable(): Array<HTMLElement> {
  */
 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) {
+  async click(element: HTMLElement, init?: EventInit): Promise<void> {
+    if (isDisabled(element)) {
       return;
     }
     dispatch(element, "pointerdown", init);
@@ -224,8 +362,11 @@ export const userEvent = {
     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}`);
+      // Nothing is typed into an element that shows no value; see `keyboard`
+      // for what that used to do instead.
+      const current = displayValue(element);
+      if (printable != null && printable !== "\n" && current != null) {
+        setValue(element, `${current}${printable}`);
         dispatch(element, "input", { data: printable });
       }
       dispatch(element, "keyup", { key, code });
@@ -243,12 +384,22 @@ export const userEvent = {
 
   /** 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;
+    const target = documentOf().activeElement ?? bodyOf();
     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}`);
+      // `displayValue` rather than `target.value !== undefined`.
+      //
+      // The two agree about every control a person can type into, and differ
+      // about `<button>`, `<option>`, `<progress>` and the rest of the
+      // elements that have a `value` property without showing one: pressing
+      // Space at a focused button used to write `button.value = " "` and
+      // dispatch an `input` event at it, which no browser does — Space on a
+      // button is a click. Nothing in this repository's suite depended on it,
+      // and `ui.test.js` presses Space at a switch on the way past.
+      const current = displayValue(target);
+      if (text != null && text !== "\n" && current != null) {
+        setValue(target, `${current}${text}`);
         dispatch(target, "input", { data: text });
       }
       dispatch(target, "keyup", { key, code });
@@ -262,8 +413,10 @@ export const userEvent = {
     if (order.length === 0) {
       return;
     }
-    const active: any = globalThis.document.activeElement;
-    const at = order.indexOf(active);
+    const active = documentOf().activeElement;
+    // `indexOf` needs an element; a document with nothing focused is the same
+    // "not in the order" that `indexOf` answers `-1` to, said in front.
+    const at = active == null ? -1 : order.indexOf(active);
     const shift = options?.shift ?? false;
     const next =
       at < 0
@@ -281,9 +434,14 @@ export const userEvent = {
     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);
+    // Only a `select` has options; anything else has none, which is what
+    // `select.options ?? []` used to say. The events are dispatched either
+    // way, because a component listening for `change` on something that is not
+    // a select is a component under test and not this function's business.
+    if (element instanceof HTMLSelectElement) {
+      for (const option of Array.from(element.options)) {
+        option.selected = wanted.includes(option.value);
+      }
     }
     dispatch(element, "input");
     dispatch(element, "change");
@@ -293,20 +451,19 @@ export const userEvent = {
   /** 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?.();
+    element.blur();
     await settle();
   },
 };
 
 function focus(element: HTMLElement): void {
-  const previous: any = globalThis.document.activeElement;
-  if (previous === element) {
+  if (documentOf().activeElement === element) {
     return;
   }
   actively(() => {
-    (element as any).focus?.();
+    element.focus();
   });
-  if (globalThis.document.activeElement !== element) {
+  if (documentOf().activeElement !== element) {
     // A host whose `focus` does not move `activeElement`; the events are what
     // components listen for, so dispatch them regardless.
     dispatch(element, "focus");

package/internal/queries.js

@@ -14,6 +14,22 @@
 // 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`.
+//
+// # Where a query looks
+//
+// `Element`. Every function here used to say `ParentNode`, which reads as the
+// right name — "something with children to search" is exactly what a root is —
+// and is not a type: the DOM specification has a `ParentNode` mixin, and Flow
+// folds it into `Document`, `DocumentFragment` and `Element` as comments
+// rather than declaring anything by that name. So it was twelve
+// `cannot-resolve-name` errors between here and `internal/screen.js`, and an
+// unresolvable name is `any`: `root` answered every question, which is why the
+// casts below it existed at all.
+//
+// `Element` is what the two callers actually pass — the document's body, and
+// an element a test already found — and it carries `querySelector`,
+// `querySelectorAll` and `innerHTML`, which is everything this module asks of
+// a root.
 
 /** What a query will accept as a description of the thing to find. */
 export type Matcher = string | RegExp | ((content: string, element: Element) => boolean);
@@ -24,6 +40,20 @@ export type MatcherOptions = {|
   readonly exact?: boolean,
 |};
 
+/**
+ * How to narrow a role query.
+ *
+ * A role is shared by every button on the page, so `name` is the option that
+ * makes the query mean something: "the button called Save", which is how a
+ * person would say it and what a screen reader announces.
+ */
+export type RoleOptions = {|
+  /** The accessible name the element must have. */
+  readonly name?: Matcher,
+  /** `false` matches a substring of the name. Defaults to `true`. */
+  readonly exact?: boolean,
+|};
+
 /**
  * Collapse whitespace the way a browser does when it lays text out.
  *
@@ -58,13 +88,13 @@ export function textOf(element: Element): string {
   return normalize(element.textContent ?? "");
 }
 
-function candidates(root: ParentNode, selector: string): Array<Element> {
+function candidates(root: Element, selector: string): Array<Element> {
   return Array.from(root.querySelectorAll(selector));
 }
 
 /** Elements whose own visible text matches. */
 export function allByText(
-  root: ParentNode,
+  root: Element,
   matcher: Matcher,
   options?: MatcherOptions,
 ): Array<Element> {
@@ -82,11 +112,7 @@ export function allByText(
 }
 
 /** 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> {
+export function allByRole(root: Element, role: string, options?: RoleOptions): Array<Element> {
   const found = candidates(root, "*").filter((element) => roleOf(element) === role);
   const name = options?.name;
   if (name == null) {
@@ -99,7 +125,7 @@ export function allByRole(
 
 /** Form controls labelled by this text. */
 export function allByLabelText(
-  root: ParentNode,
+  root: Element,
   matcher: Matcher,
   options?: MatcherOptions,
 ): Array<Element> {
@@ -125,7 +151,7 @@ export function allByLabelText(
 
 /** Elements with this placeholder. */
 export function allByPlaceholderText(
-  root: ParentNode,
+  root: Element,
   matcher: Matcher,
   options?: MatcherOptions,
 ): Array<Element> {
@@ -136,7 +162,7 @@ export function allByPlaceholderText(
 
 /** Elements marked for tests, which is the query of last resort. */
 export function allByTestId(
-  root: ParentNode,
+  root: Element,
   matcher: Matcher,
   options?: MatcherOptions,
 ): Array<Element> {
@@ -147,25 +173,57 @@ export function allByTestId(
 
 /** Elements whose value matches, for inputs and selects. */
 export function allByDisplayValue(
-  root: ParentNode,
+  root: Element,
   matcher: Matcher,
   options?: MatcherOptions,
 ): Array<Element> {
   return candidates(root, "input, textarea, select").filter((element) =>
-    matches(normalize((element as any).value ?? ""), element, matcher, options),
+    matches(normalize(displayValue(element) ?? ""), element, matcher, options),
   );
 }
 
+/**
+ * The value a control is showing, or `null` for an element that has none.
+ *
+ * The three classes rather than `element.value`, because `value` is not a
+ * property of `Element` — it belongs to each control class — and the selector
+ * that produced this element is a string the checker cannot read. An
+ * `instanceof` is the same fact stated where the checker can see it, and it is
+ * true of the elements this is called with for the reason `internal/dom.js`
+ * installs the document's own classes as the global ones: every element in the
+ * document under test is an instance of them.
+ *
+ * A cast was the other answer, and it is what was here. `(element as any).value`
+ * types this function's whole result as `any`, which then flows into
+ * `normalize` and out through `accessibleName` — a published function whose
+ * return type stopped being checked because of an expression three calls away.
+ *
+ * Exported so that `internal/events.js` asks the same question the same way:
+ * typing into a control and finding a control by its value have to agree about
+ * which elements have one, or `userEvent.type` would write a value that
+ * `getByDisplayValue` could not then find.
+ */
+export function displayValue(element: Element): string | null {
+  if (
+    element instanceof HTMLInputElement ||
+    element instanceof HTMLTextAreaElement ||
+    element instanceof HTMLSelectElement
+  ) {
+    return element.value;
+  }
+  return null;
+}
+
 /**
  * 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 {
+function controlFor(root: Element, label: Element): Element | null {
   const id = label.getAttribute("for");
   if (id != null && id !== "") {
-    const byId = (root as any).querySelector?.(`#${cssEscape(id)}`);
+    const byId = root.querySelector(`#${cssEscape(id)}`);
     if (byId != null) {
       return byId;
     }
@@ -263,11 +321,17 @@ export function accessibleName(element: Element): string {
 
   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));
+    // A loop rather than `.map().filter(Boolean).map()`: `filter(Boolean)`
+    // removes the nulls at runtime and not from the type, so the second `map`
+    // saw `HTMLElement | null` and the cast that hid it also hid whether
+    // `textOf` was being handed an element at all.
+    const parts = [];
+    for (const id of labelledBy.split(/\s+/)) {
+      const target = element.ownerDocument.getElementById(id);
+      if (target != null) {
+        parts.push(textOf(target));
+      }
+    }
     if (parts.length > 0) {
       return normalize(parts.join(" "));
     }
@@ -284,7 +348,7 @@ export function accessibleName(element: Element): string {
   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 normalize(displayValue(element) ?? "");
     }
   }
 
@@ -292,19 +356,14 @@ export function accessibleName(element: Element): string {
 }
 
 /** Why a query failed, with enough of the DOM to see why. */
-export function queryFailure(
-  kind: string,
-  matcher: Matcher,
-  root: ParentNode,
-  found: number,
-): Error {
+export function queryFailure(kind: string, matcher: Matcher, root: Element, 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 html = root.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

@@ -16,7 +16,7 @@ import { createRequire } from "node:module";
 import type * as React from "@uniflowed/react";
 import { act } from "@uniflowed/react";
 
-import { installActEnvironment, installDom, setActEnvironment } from "./dom.js";
+import { bodyOf, installActEnvironment, installDom, setActEnvironment } from "./dom.js";
 
 /** What `render` hands back. */
 export type RenderResult = {|
@@ -34,7 +34,7 @@ export type RenderResult = {|
 
 type Mounted = {|
   container: Element,
-  root: { render(node: React.Node): void, unmount(): void },
+  root: ReactRoot,
 |};
 
 const mounted: Array<Mounted> = [];
@@ -62,7 +62,7 @@ export function render(ui: React.Node, options?: {| readonly container?: Element
 
   return {
     container,
-    baseElement: globalThis.document.body as any,
+    baseElement: bodyOf(),
     rerender: (next: React.Node) => {
       act(() => {
         root.render(next);
@@ -98,7 +98,7 @@ export function cleanup(): void {
 
 function createContainer(): Element {
   const container = globalThis.document.createElement("div");
-  globalThis.document.body.appendChild(container);
+  bodyOf().appendChild(container);
   return container;
 }
 
@@ -114,15 +114,33 @@ function createContainer(): Element {
  * 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 } {
+let client: ReactDomClient | null = null;
+function requireClient(): ReactDomClient {
   if (client == null) {
     const load = createRequire(import.meta.url);
-    client = load("react-dom/client") as any;
+    client = load("react-dom/client");
   }
-  return client as any;
+  return client;
 }
 
+/**
+ * As much of `react-dom/client` as this module uses.
+ *
+ * The annotation is the trust boundary and it is deliberately one line wide: a
+ * synchronous `require` of a CommonJS build returns `any` whatever anyone
+ * writes, so the choice is not between `any` and certainty, it is between
+ * saying what is expected of the module and saying nothing. `createRoot` and
+ * the two methods below are the whole of what is expected, and a React that
+ * stopped providing them would fail here rather than at
+ * `root.render is not a function` inside an unrelated test.
+ */
+type ReactDomClient = {|
+  readonly createRoot: (container: Element) => ReactRoot,
+|};
+
+/** A React root, as much of one as this module touches. */
+type ReactRoot = {| render(node: React.Node): void, unmount(): void |};
+
 /**
  * Run `body`, letting React flush everything it queues.
  *
@@ -135,15 +153,32 @@ export function actively<T>(body: () => T): T {
   // — reaches `act` without going through `render`, and `act` still has to
   // know it is being called by a test.
   installActEnvironment();
-  let result: mixed;
+
+  // A box holding the body's result, rather than a `let result: T`.
+  //
+  // The result is produced inside a callback, and Flow cannot see that `act`
+  // called it: an annotated `let` written only there is
+  // `possibly uninitialized variable` on the way out, and a `T | void` would
+  // be wrong for the caller who wrote `act(() => {})` and whose `T` *is*
+  // `void`. A box distinguishes "not produced" from "produced `undefined`",
+  // and the check below states, at runtime, the invariant the checker cannot
+  // prove: `act` calls its scope, synchronously, always.
+  const produced: { current: {| value: T |} | null } = { current: null };
   const scope: mixed = act(() => {
-    result = body();
+    produced.current = { value: body() };
     // Handed back so React keeps the scope open until an async body settles.
     // Without this the scope closed on the first tick and every update the
     // body was still waiting for landed outside it, which React reports as
     // "an update was not wrapped in act(...)".
-    return result;
+    return produced.current.value;
   });
+
+  const held = produced.current;
+  if (held == null) {
+    throw new Error("act(...) did not run its scope, so there is no result to return");
+  }
+  const result = held.value;
+
   if (isThenable(result) && isThenable(scope)) {
     // `Promise.resolve`, not `scope.then(…)`: `act` hands back a bare thenable
     // — an object with a `then` and nothing else — whose `then` returns
@@ -153,14 +188,44 @@ export function actively<T>(body: () => T): T {
     // every later `act` nested inside the scope that was never closed and
     // flushed nothing. `render` after one of those returned an empty
     // container.
+    //
+    // # The one cast in this file, and why it is still here
+    //
+    // On this branch `T` *is* a promise — `isThenable(result)` is the runtime
+    // proof — so a promise that resolves to what `result` resolves to, once
+    // the scope has closed, is a `T`, and the signature above is true. Flow
+    // cannot follow the last step. Refining `result` says something about the
+    // value; the return type is about `T`, and there is no way to write "T is
+    // a promise here" in Flow:
+    //
+    //   * a type guard (`value is Promise<mixed>`) refines the value and
+    //     leaves `T` alone, so the helper it enables returns `Promise<mixed>`
+    //     and `Promise<unknown> is incompatible with T` in its place;
+    //   * a conditional return type (`T extends Promise<infer U> ? Promise<U>
+    //     : T`) — which this checker does support — is unevaluated while `T`
+    //     is generic, so the body cannot be checked against it either;
+    //   * overloading, which is how Flow's own `react` library definition
+    //     describes `act`, is available to a library definition and not to an
+    //     implementation.
+    //
+    // The remaining honest answers all change behaviour: returning `Promise<T>`
+    // for every call would hand `act(() => {})` a floating promise, and
+    // returning the scope itself would depend on React's thenable passing the
+    // callback's value through, which is the assumption the comment above
+    // records going wrong. So the cast stays, visible to `flow/unclear-type`
+    // rather than renamed to `$FlowFixMe` to quiet it.
     return Promise.resolve(scope).then(() => result) as any;
   }
-  return result as any;
+  return result;
 }
 
 /** Whether `value` is something to await. */
 function isThenable(value: mixed): boolean {
-  return value != null && typeof value === "object" && typeof (value as any).then === "function";
+  if (value == null || typeof value !== "object") {
+    return false;
+  }
+  const object: { readonly [string]: mixed } = value;
+  return typeof object.then === "function";
 }
 
 /**

package/internal/screen.js

@@ -3,11 +3,29 @@
 // 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.
+// `queryAllByText` and `findAllByText` by hand, for six queries, is thirty-six
+// 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 thirty-six
+// are derived — which also means a new query is one entry rather than six
+// functions.
+//
+// # The names are written down, and the behaviour is not
+//
+// `Queries` used to be `{ readonly [string]: (matcher: mixed, options?: mixed)
+// => any }`, which is a way of writing "this object has whatever you ask it
+// for, and it is whatever you like". That is a hole in the published type of a
+// package whose entire purpose is testing *typed* components:
+// `screen.getByRole("button").valeu` was not a mistake anybody's checker would
+// find, `screen.getByTest("save")` was not a misspelling, and
+// `await screen.getByText("Save")` — the missing `find`, which is the single
+// most common mistake this library invites — was fine.
+//
+// So the thirty-six names are written out below. Flow has no template literal
+// types, so `getBy${Name}` is not something a type can compute; the names have
+// to be listed for the type to exist at all. What is *not* repeated is any
+// behaviour: `forms` is still the one place the six decisions are made, and the
+// listing below is a naming, six lines per query, which is the part a reader
+// wants to be able to check against the runtime by eye.
 
 import {
   allByDisplayValue,
@@ -18,24 +36,92 @@ import {
   allByText,
   queryFailure,
 } from "./queries.js";
-import type { Matcher, MatcherOptions } from "./queries.js";
-import { documentOf } from "./dom.js";
+import type { Matcher, MatcherOptions, RoleOptions } from "./queries.js";
+import { bodyOf } 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,
-};
+/**
+ * One query's six forms, over whatever that query matches on.
+ *
+ * Generic in the target because `ByRole` does not take a `Matcher` — it takes
+ * a role, which is a string and only a string, and a regular expression over
+ * role names is a query that would silently match nothing. Generic in the
+ * options because `ByRole` is also the only query with more than `exact` to
+ * say.
+ */
+type Forms<TTarget, TOptions> = {|
+  readonly get: (target: TTarget, options?: TOptions) => Element,
+  readonly getAll: (target: TTarget, options?: TOptions) => Array<Element>,
+  readonly query: (target: TTarget, options?: TOptions) => Element | null,
+  readonly queryAll: (target: TTarget, options?: TOptions) => Array<Element>,
+  readonly find: (target: TTarget, options?: TOptions) => Promise<Element>,
+  readonly findAll: (target: TTarget, options?: TOptions) => Promise<Array<Element>>,
+|};
+
+/**
+ * The queries available on `screen` and on `within(element)`.
+ *
+ * Read down one column and the four questions of the module comment are the
+ * four return types: `getBy…` is an `Element` because it throws rather than
+ * hand back nothing, `queryBy…` is `Element | null` because its whole purpose
+ * is asking about absence, and the `findBy…` pair are promises because they
+ * wait.
+ */
+export type Queries = {|
+  readonly getByText: (matcher: Matcher, options?: MatcherOptions) => Element,
+  readonly getAllByText: (matcher: Matcher, options?: MatcherOptions) => Array<Element>,
+  readonly queryByText: (matcher: Matcher, options?: MatcherOptions) => Element | null,
+  readonly queryAllByText: (matcher: Matcher, options?: MatcherOptions) => Array<Element>,
+  readonly findByText: (matcher: Matcher, options?: MatcherOptions) => Promise<Element>,
+  readonly findAllByText: (matcher: Matcher, options?: MatcherOptions) => Promise<Array<Element>>,
+
+  readonly getByRole: (role: string, options?: RoleOptions) => Element,
+  readonly getAllByRole: (role: string, options?: RoleOptions) => Array<Element>,
+  readonly queryByRole: (role: string, options?: RoleOptions) => Element | null,
+  readonly queryAllByRole: (role: string, options?: RoleOptions) => Array<Element>,
+  readonly findByRole: (role: string, options?: RoleOptions) => Promise<Element>,
+  readonly findAllByRole: (role: string, options?: RoleOptions) => Promise<Array<Element>>,
+
+  readonly getByLabelText: (matcher: Matcher, options?: MatcherOptions) => Element,
+  readonly getAllByLabelText: (matcher: Matcher, options?: MatcherOptions) => Array<Element>,
+  readonly queryByLabelText: (matcher: Matcher, options?: MatcherOptions) => Element | null,
+  readonly queryAllByLabelText: (matcher: Matcher, options?: MatcherOptions) => Array<Element>,
+  readonly findByLabelText: (matcher: Matcher, options?: MatcherOptions) => Promise<Element>,
+  readonly findAllByLabelText: (
+    matcher: Matcher,
+    options?: MatcherOptions,
+  ) => Promise<Array<Element>>,
+
+  readonly getByPlaceholderText: (matcher: Matcher, options?: MatcherOptions) => Element,
+  readonly getAllByPlaceholderText: (matcher: Matcher, options?: MatcherOptions) => Array<Element>,
+  readonly queryByPlaceholderText: (matcher: Matcher, options?: MatcherOptions) => Element | null,
+  readonly queryAllByPlaceholderText: (
+    matcher: Matcher,
+    options?: MatcherOptions,
+  ) => Array<Element>,
+  readonly findByPlaceholderText: (matcher: Matcher, options?: MatcherOptions) => Promise<Element>,
+  readonly findAllByPlaceholderText: (
+    matcher: Matcher,
+    options?: MatcherOptions,
+  ) => Promise<Array<Element>>,
+
+  readonly getByTestId: (matcher: Matcher, options?: MatcherOptions) => Element,
+  readonly getAllByTestId: (matcher: Matcher, options?: MatcherOptions) => Array<Element>,
+  readonly queryByTestId: (matcher: Matcher, options?: MatcherOptions) => Element | null,
+  readonly queryAllByTestId: (matcher: Matcher, options?: MatcherOptions) => Array<Element>,
+  readonly findByTestId: (matcher: Matcher, options?: MatcherOptions) => Promise<Element>,
+  readonly findAllByTestId: (matcher: Matcher, options?: MatcherOptions) => Promise<Array<Element>>,
+
+  readonly getByDisplayValue: (matcher: Matcher, options?: MatcherOptions) => Element,
+  readonly getAllByDisplayValue: (matcher: Matcher, options?: MatcherOptions) => Array<Element>,
+  readonly queryByDisplayValue: (matcher: Matcher, options?: MatcherOptions) => Element | null,
+  readonly queryAllByDisplayValue: (matcher: Matcher, options?: MatcherOptions) => Array<Element>,
+  readonly findByDisplayValue: (matcher: Matcher, options?: MatcherOptions) => Promise<Element>,
+  readonly findAllByDisplayValue: (
+    matcher: Matcher,
+    options?: MatcherOptions,
+  ) => Promise<Array<Element>>,
+|};
 
 /**
  * The six forms of one finder, bound to a root.
@@ -43,58 +129,112 @@ const FINDERS = {
  * `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.
+ *
+ * `TTarget` is bounded by `Matcher` rather than left free because
+ * `queryFailure` has to describe what was asked for, and it describes the
+ * three things a matcher can be. A role is a string, so the bound holds and
+ * the failure message is the same one it always was.
  */
-function forms(name: string, find: Function, root: () => ParentNode): { [string]: Function } {
-  const all = (matcher: Matcher, options?: MatcherOptions) => find(root(), matcher, options);
+function forms<TTarget extends Matcher, TOptions>(
+  name: string,
+  find: (root: Element, target: TTarget, options?: TOptions) => Array<Element>,
+  root: () => Element,
+): Forms<TTarget, TOptions> {
+  const all = (target: TTarget, options?: TOptions) => find(root(), target, options);
 
   return {
-    [`getAllBy${name}`]: (matcher: Matcher, options?: MatcherOptions) => {
-      const found = all(matcher, options);
+    getAll: (target, options) => {
+      const found = all(target, options);
       if (found.length === 0) {
-        throw queryFailure(`getAllBy${name}`, matcher, root(), 0);
+        throw queryFailure(`getAllBy${name}`, target, root(), 0);
       }
       return found;
     },
-    [`queryAllBy${name}`]: all,
-    [`getBy${name}`]: (matcher: Matcher, options?: MatcherOptions) => {
-      const found = all(matcher, options);
+    queryAll: all,
+    get: (target, options) => {
+      const found = all(target, options);
       if (found.length !== 1) {
-        throw queryFailure(`getBy${name}`, matcher, root(), found.length);
+        throw queryFailure(`getBy${name}`, target, root(), found.length);
       }
       return found[0];
     },
-    [`queryBy${name}`]: (matcher: Matcher, options?: MatcherOptions) => {
-      const found = all(matcher, options);
+    query: (target, options) => {
+      const found = all(target, options);
       if (found.length > 1) {
-        throw queryFailure(`queryBy${name}`, matcher, root(), found.length);
+        throw queryFailure(`queryBy${name}`, target, root(), found.length);
       }
       return found[0] ?? null;
     },
-    [`findBy${name}`]: (matcher: Matcher, options?: MatcherOptions) =>
+    find: (target, options) =>
       waitFor(() => {
-        const found = all(matcher, options);
+        const found = all(target, options);
         if (found.length !== 1) {
-          throw queryFailure(`findBy${name}`, matcher, root(), found.length);
+          throw queryFailure(`findBy${name}`, target, root(), found.length);
         }
         return found[0];
       }),
-    [`findAllBy${name}`]: (matcher: Matcher, options?: MatcherOptions) =>
+    findAll: (target, options) =>
       waitFor(() => {
-        const found = all(matcher, options);
+        const found = all(target, options);
         if (found.length === 0) {
-          throw queryFailure(`findAllBy${name}`, matcher, root(), 0);
+          throw queryFailure(`findAllBy${name}`, target, 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;
+function queriesFor(root: () => Element): Queries {
+  const text = forms("Text", allByText, root);
+  const role = forms("Role", allByRole, root);
+  const labelText = forms("LabelText", allByLabelText, root);
+  const placeholderText = forms("PlaceholderText", allByPlaceholderText, root);
+  const testId = forms("TestId", allByTestId, root);
+  const displayValue = forms("DisplayValue", allByDisplayValue, root);
+
+  return {
+    getByText: text.get,
+    getAllByText: text.getAll,
+    queryByText: text.query,
+    queryAllByText: text.queryAll,
+    findByText: text.find,
+    findAllByText: text.findAll,
+
+    getByRole: role.get,
+    getAllByRole: role.getAll,
+    queryByRole: role.query,
+    queryAllByRole: role.queryAll,
+    findByRole: role.find,
+    findAllByRole: role.findAll,
+
+    getByLabelText: labelText.get,
+    getAllByLabelText: labelText.getAll,
+    queryByLabelText: labelText.query,
+    queryAllByLabelText: labelText.queryAll,
+    findByLabelText: labelText.find,
+    findAllByLabelText: labelText.findAll,
+
+    getByPlaceholderText: placeholderText.get,
+    getAllByPlaceholderText: placeholderText.getAll,
+    queryByPlaceholderText: placeholderText.query,
+    queryAllByPlaceholderText: placeholderText.queryAll,
+    findByPlaceholderText: placeholderText.find,
+    findAllByPlaceholderText: placeholderText.findAll,
+
+    getByTestId: testId.get,
+    getAllByTestId: testId.getAll,
+    queryByTestId: testId.query,
+    queryAllByTestId: testId.queryAll,
+    findByTestId: testId.find,
+    findAllByTestId: testId.findAll,
+
+    getByDisplayValue: displayValue.get,
+    getAllByDisplayValue: displayValue.getAll,
+    queryByDisplayValue: displayValue.query,
+    queryAllByDisplayValue: displayValue.queryAll,
+    findByDisplayValue: displayValue.find,
+    findAllByDisplayValue: displayValue.findAll,
+  };
 }
 
 /**
@@ -105,9 +245,9 @@ function queriesFor(root: () => ParentNode): Queries {
  * not see them would be unable to assert on the components most likely to have
  * a bug.
  */
-export const screen: Queries = queriesFor(() => documentOf().body);
+export const screen: Queries = queriesFor(() => bodyOf());
 
 /** The same queries, restricted to one element's subtree. */
-export function within(element: ParentNode): Queries {
+export function within(element: Element): Queries {
   return queriesFor(() => element);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/react-testing",
-  "version": "0.0.0-alpha.4",
+  "version": "0.0.0-alpha.6",
   "description": "React Testing Library over a real DOM, part of the Unified Toolchain for Flow.",
   "type": "module",
   "license": "MIT",
@@ -18,8 +18,8 @@
     "internal"
   ],
   "dependencies": {
-    "@uniflowed/core": "0.0.0-alpha.4",
-    "@uniflowed/react": "0.0.0-alpha.4",
+    "@uniflowed/core": "0.0.0-alpha.6",
+    "@uniflowed/react": "0.0.0-alpha.6",
     "happy-dom": "^20.13.2"
   },
   "peerDependencies": {