@uniflowed/react-testing 0.0.0-alpha.2 → 0.0.0-alpha.5

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 { installDom } 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.
  *
@@ -131,11 +149,83 @@ function requireClient(): { createRoot: (Element) => any } {
  * and this is how.
  */
 export function actively<T>(body: () => T): T {
-  let result: T;
-  act(() => {
-    result = body();
+  // A test that acts without having rendered — a timer firing in a hook test
+  // — reaches `act` without going through `render`, and `act` still has to
+  // know it is being called by a test.
+  installActEnvironment();
+
+  // 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(() => {
+    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 produced.current.value;
   });
-  return result as any;
+
+  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
+    // `undefined` rather than a promise. Chaining off it directly produced an
+    // `undefined` that `await` resolved immediately, so the caller carried on
+    // while the scope was still open: the body's timers had not fired, and
+    // 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;
+}
+
+/** Whether `value` is something to await. */
+function isThenable(value: mixed): boolean {
+  if (value == null || typeof value !== "object") {
+    return false;
+  }
+  const object: { readonly [string]: mixed } = value;
+  return typeof object.then === "function";
 }
 
 /**
@@ -149,8 +239,44 @@ export async function waitFor<T>(
   body: () => T | Promise<T>,
   options?: {| readonly timeout?: number, readonly interval?: number |},
 ): Promise<T> {
+  installActEnvironment();
   const timeout = options?.timeout ?? 1000;
   const interval = options?.interval ?? 20;
+
+  // React is told this is not an act environment for as long as the wait
+  // lasts, and told again afterwards.
+  //
+  // The update a test waits for arrives between two polls, and React reports
+  // it as "an update to X inside a test was not wrapped in act(...)" —
+  // correctly, since nothing was there to flush it. The fix cannot be to put
+  // the polling loop inside an `act` scope: `act` holds updates back until
+  // the scope closes, so the loop would poll a tree that cannot change and
+  // every `waitFor` would run to its timeout.
+  //
+  // So the scope is stood down instead. The warning exists to catch an update
+  // a test did not know it was causing; a test that wrote `waitFor` knows.
+  // Counted rather than saved and restored, because waits nest: every
+  // `findBy…` is a `waitFor`, and a test may put one inside another. The
+  // outermost wait stands the environment down and the outermost restores it.
+  waits += 1;
+  if (waits === 1) {
+    setActEnvironment(false);
+  }
+  try {
+    return await poll(body, timeout, interval);
+  } finally {
+    waits -= 1;
+    if (waits === 0) {
+      setActEnvironment(true);
+    }
+  }
+}
+
+/** How many waits are in progress. */
+let waits = 0;
+
+/** Call `body` until it stops throwing, or give up after `timeout`. */
+async function poll<T>(body: () => T | Promise<T>, timeout: number, interval: number): Promise<T> {
   const deadline = Date.now() + timeout;
   let lastError: mixed = null;