@gtkx/testing 1.0.0-rc.3 → 1.0.0

package/src/queries.ts

@@ -17,7 +17,7 @@ import {
     getWidgetDescription,
     getWidgetDisplayValue,
     getWidgetExpandedState,
-    getWidgetLabelledByText,
+    getWidgetExternalLabelText,
     getWidgetLabelText,
     getWidgetLevel,
     getWidgetName,
@@ -25,18 +25,21 @@ import {
     getWidgetPlaceholderText,
     getWidgetPressedState,
     getWidgetSelectedState,
-    getWidgetValue,
+    getWidgetValueText,
     isInaccessible,
     isWidgetChecked,
+    isWidgetValueMatch,
+    namingLabelText,
+    type WidgetValueField,
 } from "./widget-accessible-properties.js";
 
+/** The built-in queries in their unbound form, each taking the container to search as its first argument. */
 type BuiltinQueries = QueryFamilies<[container: Container]>;
 
 const roleQueries = nameQueryFamily(
     "Role",
     queryAllByRole,
     buildQueries<[role: Gtk.AccessibleRole, options?: ByRoleOptions]>(
-        "Role",
         queryAllByRole,
         (container, matches, role, options) =>
             multipleFoundError(container, { queryType: "role", role, options }, matches),
@@ -48,7 +51,6 @@ const labelTextQueries = nameQueryFamily(
     "LabelText",
     queryAllByLabelText,
     buildQueries<[text: Matcher, options?: MatcherOptions]>(
-        "LabelText",
         queryAllByLabelText,
         (container, matches, text) => multipleFoundError(container, { queryType: "labelText", text }, matches),
         (container, text) => notFoundError(container, { queryType: "labelText", text }),
@@ -59,7 +61,6 @@ const textQueries = nameQueryFamily(
     "Text",
     queryAllByText,
     buildQueries<[text: Matcher, options?: MatcherOptions]>(
-        "Text",
         queryAllByText,
         (container, matches, text) => multipleFoundError(container, { queryType: "text", text }, matches),
         (container, text) => notFoundError(container, { queryType: "text", text }),
@@ -70,7 +71,6 @@ const nameQueries = nameQueryFamily(
     "Name",
     queryAllByName,
     buildQueries<[name: Matcher, options?: MatcherOptions]>(
-        "Name",
         queryAllByName,
         (container, matches, name) => multipleFoundError(container, { queryType: "name", name }, matches),
         (container, name) => notFoundError(container, { queryType: "name", name }),
@@ -81,7 +81,6 @@ const placeholderTextQueries = nameQueryFamily(
     "PlaceholderText",
     queryAllByPlaceholderText,
     buildQueries<[text: Matcher, options?: MatcherOptions]>(
-        "PlaceholderText",
         queryAllByPlaceholderText,
         (container, matches, text) => multipleFoundError(container, { queryType: "placeholderText", text }, matches),
         (container, text) => notFoundError(container, { queryType: "placeholderText", text }),
@@ -92,7 +91,6 @@ const displayValueQueries = nameQueryFamily(
     "DisplayValue",
     queryAllByDisplayValue,
     buildQueries<[value: Matcher, options?: MatcherOptions]>(
-        "DisplayValue",
         queryAllByDisplayValue,
         (container, matches, value) => multipleFoundError(container, { queryType: "displayValue", value }, matches),
         (container, value) => notFoundError(container, { queryType: "displayValue", value }),
@@ -109,120 +107,159 @@ const builtinQueries = {
 } as BuiltinQueries;
 
 /**
- * Returns the single widget with a matching accessible role and options, or null when none match.
- * Throws when more than one matches.
+ * Returns the single mapped widget with a matching accessible role and options, or null when none
+ * match. Widgets that are not mapped are never matched. Throws when more than one matches.
  */
 const queryByRole: BuiltinQueries["queryByRole"] = builtinQueries.queryByRole;
-/** Returns every widget with a matching accessible role and options. Throws when none match. */
+/**
+ * Returns every mapped widget with a matching accessible role and options. Widgets that are not
+ * mapped are never matched. Throws when none match.
+ */
 const getAllByRole: BuiltinQueries["getAllByRole"] = builtinQueries.getAllByRole;
 /**
- * Returns the single widget with a matching accessible role and options.
- * Throws when none or more than one matches.
+ * Returns the single mapped widget with a matching accessible role and options. Widgets that are not
+ * mapped are never matched. Throws when none or more than one matches.
  */
 const getByRole: BuiltinQueries["getByRole"] = builtinQueries.getByRole;
 /**
- * Waits for and returns every widget with a matching accessible role and options, retrying until at
- * least one appears or the timeout elapses.
+ * Waits for and returns every mapped widget with a matching accessible role and options, retrying
+ * until at least one appears or the timeout elapses. Widgets that are not mapped are never matched.
  */
 const findAllByRole: BuiltinQueries["findAllByRole"] = builtinQueries.findAllByRole;
 /**
- * Waits for and returns the single widget with a matching accessible role and options, retrying
- * until it appears or the timeout elapses. Rejects when none or more than one matches.
+ * Waits for and returns the single mapped widget with a matching accessible role and options,
+ * retrying until it appears or the timeout elapses. Widgets that are not mapped are never matched.
+ * Rejects when none or more than one matches.
  */
 const findByRole: BuiltinQueries["findByRole"] = builtinQueries.findByRole;
 /**
- * Returns the single widget with matching associated label text, or null when none match.
- * Throws when more than one matches.
+ * Returns the single mapped widget with matching associated label text, or null when none match.
+ * Widgets that are not mapped are never matched. Throws when more than one matches.
  */
 const queryByLabelText: BuiltinQueries["queryByLabelText"] = builtinQueries.queryByLabelText;
-/** Returns every widget with matching associated label text. Throws when none match. */
+/**
+ * Returns every mapped widget with matching associated label text. Widgets that are not mapped are
+ * never matched. Throws when none match.
+ */
 const getAllByLabelText: BuiltinQueries["getAllByLabelText"] = builtinQueries.getAllByLabelText;
-/** Returns the single widget with matching associated label text. Throws when none or more than one matches. */
+/**
+ * Returns the single mapped widget with matching associated label text. Widgets that are not mapped
+ * are never matched. Throws when none or more than one matches.
+ */
 const getByLabelText: BuiltinQueries["getByLabelText"] = builtinQueries.getByLabelText;
 /**
- * Waits for and returns every widget with matching associated label text, retrying until at least
- * one appears or the timeout elapses.
+ * Waits for and returns every mapped widget with matching associated label text, retrying until at
+ * least one appears or the timeout elapses. Widgets that are not mapped are never matched.
  */
 const findAllByLabelText: BuiltinQueries["findAllByLabelText"] = builtinQueries.findAllByLabelText;
 /**
- * Waits for and returns the single widget with matching associated label text, retrying until it
- * appears or the timeout elapses. Rejects when none or more than one matches.
+ * Waits for and returns the single mapped widget with matching associated label text, retrying until
+ * it appears or the timeout elapses. Widgets that are not mapped are never matched. Rejects when
+ * none or more than one matches.
  */
 const findByLabelText: BuiltinQueries["findByLabelText"] = builtinQueries.findByLabelText;
 /**
- * Returns the single widget with matching rendered text content, or null when none match.
- * Throws when more than one matches.
+ * Returns the single mapped widget with matching rendered text content, or null when none match.
+ * Widgets that are not mapped are never matched. Throws when more than one matches.
  */
 const queryByText: BuiltinQueries["queryByText"] = builtinQueries.queryByText;
-/** Returns every widget with matching rendered text content. Throws when none match. */
+/**
+ * Returns every mapped widget with matching rendered text content. Widgets that are not mapped are
+ * never matched. Throws when none match.
+ */
 const getAllByText: BuiltinQueries["getAllByText"] = builtinQueries.getAllByText;
-/** Returns the single widget with matching rendered text content. Throws when none or more than one matches. */
+/**
+ * Returns the single mapped widget with matching rendered text content. Widgets that are not mapped
+ * are never matched. Throws when none or more than one matches.
+ */
 const getByText: BuiltinQueries["getByText"] = builtinQueries.getByText;
 /**
- * Waits for and returns every widget with matching rendered text content, retrying until at least
- * one appears or the timeout elapses.
+ * Waits for and returns every mapped widget with matching rendered text content, retrying until at
+ * least one appears or the timeout elapses. Widgets that are not mapped are never matched.
  */
 const findAllByText: BuiltinQueries["findAllByText"] = builtinQueries.findAllByText;
 /**
- * Waits for and returns the single widget with matching rendered text content, retrying until it
- * appears or the timeout elapses. Rejects when none or more than one matches.
+ * Waits for and returns the single mapped widget with matching rendered text content, retrying until
+ * it appears or the timeout elapses. Widgets that are not mapped are never matched. Rejects when
+ * none or more than one matches.
  */
 const findByText: BuiltinQueries["findByText"] = builtinQueries.findByText;
 /**
- * Returns the single widget with a matching widget name, or null when none match.
- * Throws when more than one matches.
+ * Returns the single mapped widget with a matching widget name, or null when none match. Widgets
+ * that are not mapped are never matched. Throws when more than one matches.
  */
 const queryByName: BuiltinQueries["queryByName"] = builtinQueries.queryByName;
-/** Returns every widget with a matching widget name. Throws when none match. */
+/**
+ * Returns every mapped widget with a matching widget name. Widgets that are not mapped are never
+ * matched. Throws when none match.
+ */
 const getAllByName: BuiltinQueries["getAllByName"] = builtinQueries.getAllByName;
-/** Returns the single widget with a matching widget name. Throws when none or more than one matches. */
+/**
+ * Returns the single mapped widget with a matching widget name. Widgets that are not mapped are
+ * never matched. Throws when none or more than one matches.
+ */
 const getByName: BuiltinQueries["getByName"] = builtinQueries.getByName;
 /**
- * Waits for and returns every widget with a matching widget name, retrying until at least one
- * appears or the timeout elapses.
+ * Waits for and returns every mapped widget with a matching widget name, retrying until at least one
+ * appears or the timeout elapses. Widgets that are not mapped are never matched.
  */
 const findAllByName: BuiltinQueries["findAllByName"] = builtinQueries.findAllByName;
 /**
- * Waits for and returns the single widget with a matching widget name, retrying until it appears or
- * the timeout elapses. Rejects when none or more than one matches.
+ * Waits for and returns the single mapped widget with a matching widget name, retrying until it
+ * appears or the timeout elapses. Widgets that are not mapped are never matched. Rejects when none
+ * or more than one matches.
  */
 const findByName: BuiltinQueries["findByName"] = builtinQueries.findByName;
 /**
- * Returns the single widget with matching placeholder text, or null when none match.
- * Throws when more than one matches.
+ * Returns the single mapped widget with matching placeholder text, or null when none match. Widgets
+ * that are not mapped are never matched. Throws when more than one matches.
  */
 const queryByPlaceholderText: BuiltinQueries["queryByPlaceholderText"] = builtinQueries.queryByPlaceholderText;
-/** Returns every widget with matching placeholder text. Throws when none match. */
+/**
+ * Returns every mapped widget with matching placeholder text. Widgets that are not mapped are never
+ * matched. Throws when none match.
+ */
 const getAllByPlaceholderText: BuiltinQueries["getAllByPlaceholderText"] = builtinQueries.getAllByPlaceholderText;
-/** Returns the single widget with matching placeholder text. Throws when none or more than one matches. */
+/**
+ * Returns the single mapped widget with matching placeholder text. Widgets that are not mapped are
+ * never matched. Throws when none or more than one matches.
+ */
 const getByPlaceholderText: BuiltinQueries["getByPlaceholderText"] = builtinQueries.getByPlaceholderText;
 /**
- * Waits for and returns every widget with matching placeholder text, retrying until at least one
- * appears or the timeout elapses.
+ * Waits for and returns every mapped widget with matching placeholder text, retrying until at least
+ * one appears or the timeout elapses. Widgets that are not mapped are never matched.
  */
 const findAllByPlaceholderText: BuiltinQueries["findAllByPlaceholderText"] = builtinQueries.findAllByPlaceholderText;
 /**
- * Waits for and returns the single widget with matching placeholder text, retrying until it appears
- * or the timeout elapses. Rejects when none or more than one matches.
+ * Waits for and returns the single mapped widget with matching placeholder text, retrying until it
+ * appears or the timeout elapses. Widgets that are not mapped are never matched. Rejects when none
+ * or more than one matches.
  */
 const findByPlaceholderText: BuiltinQueries["findByPlaceholderText"] = builtinQueries.findByPlaceholderText;
 /**
- * Returns the single widget with a matching display value, or null when none match.
- * Throws when more than one matches.
+ * Returns the single mapped widget with a matching display value, or null when none match. Widgets
+ * that are not mapped are never matched. Throws when more than one matches.
  */
 const queryByDisplayValue: BuiltinQueries["queryByDisplayValue"] = builtinQueries.queryByDisplayValue;
-/** Returns every widget with a matching display value. Throws when none match. */
+/**
+ * Returns every mapped widget with a matching display value. Widgets that are not mapped are never
+ * matched. Throws when none match.
+ */
 const getAllByDisplayValue: BuiltinQueries["getAllByDisplayValue"] = builtinQueries.getAllByDisplayValue;
-/** Returns the single widget with a matching display value. Throws when none or more than one matches. */
+/**
+ * Returns the single mapped widget with a matching display value. Widgets that are not mapped are
+ * never matched. Throws when none or more than one matches.
+ */
 const getByDisplayValue: BuiltinQueries["getByDisplayValue"] = builtinQueries.getByDisplayValue;
 /**
- * Waits for and returns every widget with a matching display value, retrying until at least one
- * appears or the timeout elapses.
+ * Waits for and returns every mapped widget with a matching display value, retrying until at least
+ * one appears or the timeout elapses. Widgets that are not mapped are never matched.
  */
 const findAllByDisplayValue: BuiltinQueries["findAllByDisplayValue"] = builtinQueries.findAllByDisplayValue;
 /**
- * Waits for and returns the single widget with a matching display value, retrying until it appears
- * or the timeout elapses. Rejects when none or more than one matches.
+ * Waits for and returns the single mapped widget with a matching display value, retrying until it
+ * appears or the timeout elapses. Widgets that are not mapped are never matched. Rejects when none
+ * or more than one matches.
  */
 const findByDisplayValue: BuiltinQueries["findByDisplayValue"] = builtinQueries.findByDisplayValue;
 
@@ -290,25 +327,23 @@ const hasMatchingAccessibleName = (widget: Gtk.Widget, options: ByRoleOptions):
     return isTextMatch(text, options.name, widget, options);
 };
 
-const isNumericValueMatch = (expected: number | undefined, actual: number | null): boolean =>
-    expected === undefined || actual === expected;
+const isNumericValueMatch = (widget: Gtk.Widget, field: WidgetValueField, expected: number | undefined): boolean =>
+    expected === undefined || isWidgetValueMatch(widget, field, expected);
 
 const hasMatchingAccessibleValue = (widget: Gtk.Widget, value: ByRoleValue, options: ByRoleOptions): boolean => {
-    const actual = getWidgetValue(widget);
-
-    const numericChecks: [number | undefined, number | null][] = [
-        [value.now, actual.now],
-        [value.min, actual.min],
-        [value.max, actual.max],
+    const numericChecks: [WidgetValueField, number | undefined][] = [
+        ["now", value.now],
+        ["min", value.min],
+        ["max", value.max],
     ];
 
-    for (const [expected, current] of numericChecks) {
-        if (!isNumericValueMatch(expected, current)) {
+    for (const [field, expected] of numericChecks) {
+        if (!isNumericValueMatch(widget, field, expected)) {
             return false;
         }
     }
 
-    return value.text === undefined || isTextMatch(actual.text, value.text, widget, options);
+    return value.text === undefined || isTextMatch(getWidgetValueText(widget), value.text, widget, options);
 };
 
 const hasMatchingBooleanStates = (widget: Gtk.Widget, options: ByRoleOptions): boolean => {
@@ -365,19 +400,22 @@ function nameQueryFamily<Args extends unknown[]>(
     queryAllBy: QueryAllBy<Args>,
     built: BuiltQueries<Args>,
 ): Record<string, unknown> {
+    const [queryBy, getAllBy, getBy, findAllBy, findBy] = built;
+
     return {
-        [`queryBy${suffix}`]: built.queryBy,
+        [`queryBy${suffix}`]: queryBy,
         [`queryAllBy${suffix}`]: queryAllBy,
-        [`getBy${suffix}`]: built.getBy,
-        [`getAllBy${suffix}`]: built.getAllBy,
-        [`findBy${suffix}`]: built.findBy,
-        [`findAllBy${suffix}`]: built.findAllBy,
+        [`getBy${suffix}`]: getBy,
+        [`getAllBy${suffix}`]: getAllBy,
+        [`findBy${suffix}`]: findBy,
+        [`findAllBy${suffix}`]: findAllBy,
     };
 }
 
 /**
  * Finds every widget under the container whose accessible role matches `role` and that satisfies the given options.
- * Widgets excluded from the accessibility tree are skipped unless `options.hidden` is set.
+ * Widgets that are not mapped are never matched, and widgets excluded from the accessibility tree are
+ * skipped unless `options.hidden` is set.
  * @param container Widget subtree to search.
  * @param role Accessible role to match.
  * @param options Additional accessible name, state, and value constraints.
@@ -410,7 +448,7 @@ const collectMnemonicMatch = (
         return null;
     }
 
-    const labelText = widget.getLabel();
+    const labelText = namingLabelText(widget);
 
     if (!labelText || !isTextMatch(labelText, text, widget, options)) {
         return null;
@@ -419,6 +457,12 @@ const collectMnemonicMatch = (
     return widget.getMnemonicWidget();
 };
 
+const labellingText = (widget: Gtk.Widget): string | null => {
+    const ownLabel = widget.getAccessibleRole() === Gtk.AccessibleRole.LABEL ? null : getWidgetOwnLabel(widget);
+
+    return ownLabel ?? getWidgetExternalLabelText(widget);
+};
+
 const collectLabelMatches = (
     results: Set<Gtk.Widget>,
     widget: Gtk.Widget,
@@ -431,22 +475,16 @@ const collectLabelMatches = (
         results.add(mnemonicTarget);
     }
 
-    const ownLabel = getWidgetOwnLabel(widget);
-
-    if (ownLabel !== null && isTextMatch(ownLabel, text, widget, options)) {
-        results.add(widget);
-    }
-
-    const labelledByText = getWidgetLabelledByText(widget);
+    const labelText = labellingText(widget);
 
-    if (labelledByText !== null && isTextMatch(labelledByText, text, widget, options)) {
+    if (labelText !== null && isTextMatch(labelText, text, widget, options)) {
         results.add(widget);
     }
 };
 
 /**
  * Finds every widget associated with a label whose text matches: a Gtk.Label mnemonic target, the
- * widget's own accessible label, or its labelled-by relation.
+ * widget's own accessible label, or its labelled-by relation. Widgets that are not mapped are never matched.
  * @param container Widget subtree to search.
  * @param text Matcher for the label text.
  * @param options Text matching options.
@@ -463,7 +501,7 @@ function queryAllByLabelText(container: Container, text: Matcher, options?: Matc
 }
 
 /**
- * Finds every widget whose rendered text content matches.
+ * Finds every widget whose rendered text content matches. Widgets that are not mapped are never matched.
  * @param container Widget subtree to search.
  * @param text Matcher for the widget text.
  * @param options Text matching options.
@@ -478,7 +516,7 @@ function queryAllByText(container: Container, text: Matcher, options?: MatcherOp
 }
 
 /**
- * Finds every widget whose widget name matches.
+ * Finds every widget whose widget name matches. Widgets that are not mapped are never matched.
  * @param container Widget subtree to search.
  * @param name Matcher for the widget name.
  * @param options Text matching options.
@@ -492,7 +530,7 @@ function queryAllByName(container: Container, name: Matcher, options?: MatcherOp
 }
 
 /**
- * Finds every widget whose placeholder text matches.
+ * Finds every widget whose placeholder text matches. Widgets that are not mapped are never matched.
  * @param container Widget subtree to search.
  * @param text Matcher for the placeholder text.
  * @param options Text matching options.
@@ -512,7 +550,7 @@ function queryAllByPlaceholderText(
 }
 
 /**
- * Finds every widget whose current display value matches.
+ * Finds every widget whose current display value matches. Widgets that are not mapped are never matched.
  * @param container Widget subtree to search.
  * @param value Matcher for the display value.
  * @param options Text matching options.
@@ -529,6 +567,8 @@ function queryAllByDisplayValue(container: Container, value: Matcher, options?:
 
 export {
     builtinQueries,
+    isMatchingWidgetType,
+    isTextMatch,
     queryByRole,
     getAllByRole,
     getByRole,
@@ -565,5 +605,4 @@ export {
     queryAllByName,
     queryAllByPlaceholderText,
     queryAllByDisplayValue,
-    type BuiltinQueries,
 };

package/src/query-helpers.ts

@@ -0,0 +1,97 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import { camelCase } from "@gtkx/utils";
+import type { Matcher, MatcherOptions } from "./types.js";
+import { buildQueries } from "./build-queries.js";
+import { getElementError } from "./errors.js";
+import { isMatchingWidgetType, isTextMatch } from "./queries.js";
+import { type Container, findAll } from "./traversal.js";
+
+/** The helpers used to build custom queries, bundled the way DOM Testing Library exposes them. */
+type QueryHelpers = {
+    /** Derives a query family's variants from its `queryAllBy` function. */
+    buildQueries: typeof buildQueries;
+    /** Builds the error a failing query throws. */
+    getElementError: typeof getElementError;
+    /** Finds every widget whose GObject property matches. */
+    queryAllByObjectProperty: typeof queryAllByObjectProperty;
+    /** Finds the single widget whose GObject property matches. */
+    queryByObjectProperty: typeof queryByObjectProperty;
+};
+
+/** The query-building helpers, bundled so they can be reached under a single import. */
+const queryHelpers: QueryHelpers = {
+    buildQueries,
+    getElementError,
+    queryAllByObjectProperty,
+    queryByObjectProperty,
+};
+
+const readObjectProperty = (widget: Gtk.Widget, property: string): string | null => {
+    const value: unknown = Reflect.get(widget, camelCase(property));
+
+    if (typeof value === "string") {
+        return value;
+    }
+
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+        return String(value);
+    }
+
+    return null;
+};
+
+/**
+ * Finds every widget carrying a GObject property whose value matches, the counterpart of DOM Testing
+ * Library's `queryAllByAttribute`. The property name may be given in kebab-case or camelCase, and
+ * widgets that are not mapped are never matched.
+ *
+ * @param property Name of the GObject property to read.
+ * @param container Widget subtree to search.
+ * @param text Matcher for the property's value.
+ * @param options Text matching options.
+ * @returns Every matching widget, or an empty array when none match.
+ */
+function queryAllByObjectProperty(
+    property: string,
+    container: Container,
+    text: Matcher,
+    options?: MatcherOptions,
+): Gtk.Widget[] {
+    return findAll(
+        container,
+        (widget) =>
+            isMatchingWidgetType(widget, options) &&
+            isTextMatch(readObjectProperty(widget, property), text, widget, options),
+    );
+}
+
+/**
+ * Returns the single widget carrying a GObject property whose value matches, or null when none do,
+ * the counterpart of DOM Testing Library's `queryByAttribute`.
+ *
+ * @param property Name of the GObject property to read.
+ * @param container Widget subtree to search.
+ * @param text Matcher for the property's value.
+ * @param options Text matching options.
+ * @returns The matching widget, or null when none match.
+ * @throws When more than one widget matches.
+ */
+function queryByObjectProperty(
+    property: string,
+    container: Container,
+    text: Matcher,
+    options?: MatcherOptions,
+): Gtk.Widget | null {
+    const matches = queryAllByObjectProperty(property, container, text, options);
+
+    if (matches.length > 1) {
+        throw getElementError(
+            `Found ${String(matches.length)} elements with the '${property}' property, but expected only one`,
+            container,
+        );
+    }
+
+    return matches[0] ?? null;
+}
+
+export { queryAllByObjectProperty, queryByObjectProperty, queryHelpers, type QueryHelpers };

package/src/render-children.ts

@@ -0,0 +1,25 @@
+import type { ReactNode } from "react";
+import type { RenderOptions } from "./types.js";
+import { render } from "./render.js";
+
+type ChildrenBuilder<T> = (items: T[]) => ReactNode;
+
+type RenderChildrenResult<T> = {
+    rerender: (items: T[]) => Promise<void>;
+};
+
+async function renderChildren<T>(
+    initial: T[],
+    build: ChildrenBuilder<T>,
+    options?: RenderOptions,
+): Promise<RenderChildrenResult<T>> {
+    const { rerender } = await render(build(initial), options);
+
+    return {
+        rerender: async (items: T[]) => {
+            await rerender(build(items));
+        },
+    };
+}
+
+export { renderChildren, type ChildrenBuilder };

package/src/render.tsx

@@ -5,23 +5,28 @@ import {
     isRootElement,
     type ReconcilerRoot,
     setReconcilerErrorHandler,
+    settleAccessible,
 } from "@gtkx/react/internal";
 import { type ErrorInfo, type ReactNode, StrictMode } from "react";
 import type { RenderResult } from "./bound-queries.js";
-import type { QueryMap, RenderOptions, ScreenshotOptions, WindowSelector } from "./types.js";
+import type { QueryMap, RenderOptions, ScreenshotOptions } from "./types.js";
 import { runInAct } from "./act.js";
 import { addToCleanupQueue, runCleanup } from "./cleanup-registry.js";
 import { scheduleAfterLayout } from "./frame-sync.js";
+import { createHarnessWindow } from "./harness-window.js";
 import { logWidget, type PrettyWidgetOptions } from "./pretty-widget.js";
 import { logRoles } from "./role-helpers.js";
 import { clearScreen, setScreen } from "./screen.js";
-import { captureAndSaveScreenshot } from "./screenshot.js";
-import { type Container, TOPLEVELS, traverse } from "./traversal.js";
+import { captureScreen } from "./screenshot.js";
+import { type Container, roots, TOPLEVELS } from "./traversal.js";
 import { resetClipboard } from "./user-event/index.js";
 import { within } from "./within.js";
 
+/** A mounted render tracked so cleanup can unmount it. */
 type ActiveRender = {
+    /** Root that rerenders drive and that cleanup tears the tree down through. */
     root: ReconcilerRoot;
+    /** Harness window created for the render, null when it renders into a container the caller supplied. */
     window: Gtk.Window | null;
 };
 
@@ -37,12 +42,13 @@ type ReconcilerErrorState = {
 
 const reconcilerErrors: ReconcilerErrorState = { lastError: null, isHandlerInstalled: false };
 const activeRenders: Set<ActiveRender> = new Set();
-const HARNESS_WINDOW_WIDTH = 800;
-const HARNESS_WINDOW_HEIGHT = 600;
 
 const flushLayout = (window: Gtk.Window | null): Promise<void> =>
-    new Promise((resolve) => {
-        scheduleAfterLayout(window, resolve);
+    new Promise<void>((resolve) => {
+        scheduleAfterLayout(window, () => {
+            settleAccessible();
+            resolve();
+        });
     });
 
 const update = async (element: ReactNode, root: ReconcilerRoot): Promise<void> => {
@@ -96,7 +102,7 @@ const resolveContainer = (container: RenderOptions["container"]): ResolvedContai
         return { containerInfo: container, window: null };
     }
 
-    const window = new Gtk.Window({ defaultWidth: HARNESS_WINDOW_WIDTH, defaultHeight: HARNESS_WINDOW_HEIGHT });
+    const window = createHarnessWindow();
     window.setDecorated(false);
 
     return { containerInfo: window, window };
@@ -107,7 +113,7 @@ const firstToplevelWidget = (baseElement: Container): Gtk.Widget => {
         return baseElement;
     }
 
-    const [first] = traverse(baseElement);
+    const [first] = roots(baseElement);
 
     if (first) {
         return first;
@@ -165,7 +171,7 @@ const render = async <Q extends QueryMap = Record<never, never>>(
     options?: RenderOptions<Q>,
 ): Promise<RenderResult<Q>> => {
     installErrorHandler();
-    applyEnableAnimations(options?.animations === true);
+    applyEnableAnimations(options?.areAnimationsEnabled === true);
     const baseElement: Container = options?.baseElement ?? TOPLEVELS;
     const Wrapper = options?.wrapper;
     const resolved = resolveContainer(options?.container);
@@ -184,7 +190,7 @@ const render = async <Q extends QueryMap = Record<never, never>>(
     const wrap = (node: ReactNode): ReactNode => {
         const wrapped = Wrapper ? <Wrapper>{node}</Wrapper> : node;
 
-        return options?.reactStrictMode ? <StrictMode>{wrapped}</StrictMode> : wrapped;
+        return options?.isReactStrictMode ? <StrictMode>{wrapped}</StrictMode> : wrapped;
     };
 
     await update(wrap(element), root);
@@ -209,8 +215,7 @@ const render = async <Q extends QueryMap = Record<never, never>>(
         logRoles: () => {
             logRoles(baseElement);
         },
-        screenshot: (selector?: WindowSelector, screenshotOptions?: ScreenshotOptions) =>
-            captureAndSaveScreenshot(selector, screenshotOptions),
+        screenshot: (screenshotOptions?: ScreenshotOptions) => captureScreen(screenshotOptions),
     };
 
     setScreen(result);