@uniflowed/react-testing 0.0.0-alpha.10

package/internal/render.js

@@ -0,0 +1,298 @@
+// @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 { bodyOf, installActEnvironment, installDom, setActEnvironment } 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: ReactRoot,
+|};
+
+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: bodyOf(),
+    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");
+  bodyOf().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: ReactDomClient | null = null;
+function requireClient(): ReactDomClient {
+  if (client == null) {
+    const load = createRequire(import.meta.url);
+    client = load("react-dom/client");
+  }
+  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.
+ *
+ * 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 {
+  // 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;
+  });
+
+  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, suppressed by name rather than
+    // renamed to `$FlowFixMe`: the directive says which rule it is escaping and
+    // this comment says why, which a rename says nothing about.
+    // uf-lint-disable-next-line flow/unclear-type
+    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";
+}
+
+/**
+ * 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> {
+  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;
+
+  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,294 @@
+// @flow
+//
+// The six forms of every query, generated once.
+//
+// Writing `getByText`, `queryByText`, `findByText`, `getAllByText`,
+// `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 {
+  MATCHER_OPTION_KEYS,
+  ROLE_OPTION_KEYS,
+  allByDisplayValue,
+  allByLabelText,
+  allByPlaceholderText,
+  allByRole,
+  allByTestId,
+  allByText,
+  atCallSite,
+  queryFailure,
+  rejectUnknownOptions,
+} from "./queries.js";
+import type { Matcher, MatcherOptions, RoleOptions } from "./queries.js";
+import { bodyOf } from "./dom.js";
+import { waitFor } from "./render.js";
+
+/**
+ * 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.
+ *
+ * `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.
+ *
+ * `known` is the keys the query's options may have, and each of the six checks
+ * before it looks at anything. Six lines rather than one inside `all`, because
+ * the message has to name the function the reader typed — `getByRole`, not
+ * "a role query" — and because the two waiting forms have to raise now rather
+ * than a second from now: an option a query does not take is a mistake in the
+ * test, not a condition that is about to come true.
+ */
+function forms<TTarget extends Matcher, TOptions>(
+  name: string,
+  find: (root: Element, target: TTarget, options?: TOptions) => Array<Element>,
+  root: () => Element,
+  known: $ReadOnlyArray<string>,
+): Forms<TTarget, TOptions> {
+  const all = (target: TTarget, options?: TOptions) => find(root(), target, options);
+  const check = (form: string, options?: TOptions) => {
+    rejectUnknownOptions(`${form}By${name}`, options, known);
+  };
+
+  return {
+    getAll: (target, options) => {
+      check("getAll", options);
+      const found = all(target, options);
+      if (found.length === 0) {
+        throw queryFailure(`getAllBy${name}`, target, root(), 0);
+      }
+      return found;
+    },
+    queryAll: (target, options) => {
+      check("queryAll", options);
+      return all(target, options);
+    },
+    get: (target, options) => {
+      check("get", options);
+      const found = all(target, options);
+      if (found.length !== 1) {
+        throw queryFailure(`getBy${name}`, target, root(), found.length);
+      }
+      return found[0];
+    },
+    query: (target, options) => {
+      check("query", options);
+      const found = all(target, options);
+      if (found.length > 1) {
+        throw queryFailure(`queryBy${name}`, target, root(), found.length);
+      }
+      return found[0] ?? null;
+    },
+    // The two waiting forms build an error at the call and hand it to the
+    // failure on the way out. A wait keeps the *last* attempt's failure, and
+    // the last attempt runs from a timer: by then the stack under it is the
+    // poll loop and nothing else, so the failure has no line of the test left
+    // in it to report. The synchronous four need none of this — they throw
+    // while the caller is still on the stack.
+    find: async (target, options) => {
+      check("find", options);
+      const asked = new Error("asked here");
+      try {
+        return await waitFor(() => {
+          const found = all(target, options);
+          if (found.length !== 1) {
+            throw queryFailure(`findBy${name}`, target, root(), found.length);
+          }
+          return found[0];
+        });
+      } catch (error) {
+        throw atCallSite(error, asked);
+      }
+    },
+    findAll: async (target, options) => {
+      check("findAll", options);
+      const asked = new Error("asked here");
+      try {
+        return await waitFor(() => {
+          const found = all(target, options);
+          if (found.length === 0) {
+            throw queryFailure(`findAllBy${name}`, target, root(), 0);
+          }
+          return found;
+        });
+      } catch (error) {
+        throw atCallSite(error, asked);
+      }
+    },
+  };
+}
+
+function queriesFor(root: () => Element): Queries {
+  const text = forms("Text", allByText, root, MATCHER_OPTION_KEYS);
+  const role = forms("Role", allByRole, root, ROLE_OPTION_KEYS);
+  const labelText = forms("LabelText", allByLabelText, root, MATCHER_OPTION_KEYS);
+  const placeholderText = forms("PlaceholderText", allByPlaceholderText, root, MATCHER_OPTION_KEYS);
+  const testId = forms("TestId", allByTestId, root, MATCHER_OPTION_KEYS);
+  const displayValue = forms("DisplayValue", allByDisplayValue, root, MATCHER_OPTION_KEYS);
+
+  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,
+  };
+}
+
+/**
+ * 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(() => bodyOf());
+
+/** The same queries, restricted to one element's subtree. */
+export function within(element: Element): Queries {
+  return queriesFor(() => element);
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@uniflowed/react-testing",
+  "version": "0.0.0-alpha.10",
+  "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.10",
+    "@uniflowed/react": "0.0.0-alpha.10",
+    "happy-dom": "^20.13.2"
+  },
+  "peerDependencies": {
+    "react": ">=19",
+    "react-dom": ">=19"
+  }
+}