@gtkx/testing 1.0.0-rc.4 → 1.1.0

package/src/render.tsx

@@ -5,23 +5,30 @@ 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 { getConfig } from "./config.js";
+import { scheduleWhenWindowReady } from "./frame-sync.js";
+import { createHarnessWindow, presentHarnessWindow } 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 { findPresentedWindowFailure, findRenderedWindowFailure, mappedToplevels } from "./window-state.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;
 };
 
@@ -35,16 +42,34 @@ type ReconcilerErrorState = {
     isHandlerInstalled: boolean;
 };
 
+type WindowFailureReporter = (window: Gtk.Window) => string | null;
+type SettleAction = "render" | "rerender";
+
 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);
+const settleWindow = async (
+    window: Gtk.Window | null,
+    findFailure: WindowFailureReporter,
+    action: SettleAction,
+): Promise<void> => {
+    const timeout = getConfig().windowActivationTimeout;
+
+    await new Promise<void>((resolve) => {
+        scheduleWhenWindowReady(window, (target) => findFailure(target) === null, timeout, resolve);
     });
 
+    settleAccessible();
+    const failure = window === null ? null : findFailure(window);
+
+    if (failure !== null) {
+        throw new Error(
+            `${action} timed out after ${String(timeout)}ms waiting for the window it rendered into: ${failure}. ` +
+            "Platform state such as focus is only readable once that window is allocated and active.",
+        );
+    }
+};
+
 const update = async (element: ReactNode, root: ReconcilerRoot): Promise<void> => {
     await runInAct(() => {
         root.update(element);
@@ -96,7 +121,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 +132,7 @@ const firstToplevelWidget = (baseElement: Container): Gtk.Widget => {
         return baseElement;
     }
 
-    const [first] = traverse(baseElement);
+    const [first] = roots(baseElement);
 
     if (first) {
         return first;
@@ -132,6 +157,31 @@ const resolveResultContainer = (
     return firstToplevelWidget(baseElement);
 };
 
+const realizedWindow = (root: Gtk.Root | null): Gtk.Window | null =>
+    root instanceof Gtk.Window && root.getFrameClock() !== null ? root : null;
+
+const settleTarget = (resolved: ResolvedContainer, container: RenderOptions["container"]): Gtk.Window | null => {
+    if (resolved.window) {
+        return realizedWindow(resolved.window);
+    }
+
+    if (container instanceof Gtk.Widget) {
+        return realizedWindow(container.getRoot());
+    }
+
+    return realizedWindow(mappedToplevels()[0] ?? null);
+};
+
+const settleRender = async (
+    resolved: ResolvedContainer,
+    container: RenderOptions["container"],
+    action: SettleAction,
+): Promise<void> => {
+    const isPresentedNow = action === "render" && resolved.window !== null;
+    const findFailure = isPresentedNow ? findPresentedWindowFailure : findRenderedWindowFailure;
+    await settleWindow(settleTarget(resolved, container), findFailure, action);
+};
+
 const renderErrorHandlers = <Q extends QueryMap>(options: RenderOptions<Q> | undefined) => ({
     onUncaughtError: handleError,
     onCaughtError: (error: unknown, errorInfo: ErrorInfo): void => {
@@ -154,11 +204,22 @@ const applyEnableAnimations = (areAnimationsEnabled: boolean): void => {
 /**
  * Renders a React element into a GTK4 widget tree and returns queries
  * scoped to it along with controls for rerendering and unmounting. When no
- * container is supplied, a harness window is created and presented.
+ * container is supplied, a harness window is created and presented, and the editable it hands the
+ * focus to keeps its text unselected, with its caret at the end. The returned promise settles once
+ * the window the tree is shown in has been laid out and activation has arrived, so platform state
+ * such as focus is already readable when it resolves. A presented harness window is waited on until
+ * it is itself active; a window the caller or the tree owns is waited on until the application holds
+ * activation, since only a present can claim it. Rendering into a container that is not shown waits
+ * for nothing, and a window that never becomes readable within `windowActivationTimeout` throws an
+ * error naming the condition that failed rather than resolving with unreadable platform state. A
+ * tree mounted into a container that sits outside every toplevel, or inside a window that is not
+ * visible, is out of reach of a pointer and a keyboard, so every `userEvent` helper aimed at it
+ * rejects after `actionabilityTimeout` naming that condition, and `fireEvent` drives it instead.
  *
  * @param element The React element to render.
  * @param options Optional container, wrapper, custom queries, and other render settings.
  * @returns A render result with bound queries, debug helpers, and lifecycle controls.
+ * @throws When the window the tree is shown in is not laid out and activated in time.
  */
 const render = async <Q extends QueryMap = Record<never, never>>(
     element: ReactNode,
@@ -188,8 +249,8 @@ const render = async <Q extends QueryMap = Record<never, never>>(
     };
 
     await update(wrap(element), root);
-    resolved.window?.present();
-    await flushLayout(resolved.window);
+    presentHarnessWindow(resolved.window);
+    await settleRender(resolved, options?.container, "render");
     const container = resolveResultContainer(resolved, options?.container, baseElement);
 
     const result: RenderResult<Q> = {
@@ -201,7 +262,7 @@ const render = async <Q extends QueryMap = Record<never, never>>(
         },
         rerender: async (newElement: ReactNode) => {
             await update(wrap(newElement), root);
-            await flushLayout(resolved.window);
+            await settleRender(resolved, options?.container, "rerender");
         },
         debug: (element: Container | Container[] = baseElement, debugOptions?: PrettyWidgetOptions) => {
             logWidget(element, debugOptions);
@@ -209,8 +270,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);

package/src/role-helpers.ts

@@ -1,7 +1,8 @@
 import * as Gtk from "@gtkx/gi/gtk";
 import { sortStringsBy } from "@gtkx/utils";
 import { type Container, traverse } from "./traversal.js";
-import { getWidgetAccessibleName } from "./widget-accessible-properties.js";
+import { getWidgetAccessibleName, getWidgetLevel } from "./widget-accessible-properties.js";
+import { getTypeTag } from "./widget-getters.js";
 
 const ROLE_NAMES_BY_VALUE = enumNamesByValue(Gtk.AccessibleRole);
 
@@ -47,10 +48,11 @@ const formatRoleList = (roles: Iterable<Gtk.AccessibleRole>): string => {
 };
 
 /**
- * Groups every widget in a container's tree by its accessible role name.
+ * Groups every mapped widget in a container's tree by its accessible role name. Widgets that are not
+ * mapped are left out.
  *
  * @param container The scope to traverse.
- * @returns A map from role name to the widgets that have that role.
+ * @returns A map from role name to the mapped widgets that have that role.
  */
 const getRoles = (container: Container): Map<string, Gtk.Widget[]> => {
     const roles: Map<string, Gtk.Widget[]> = new Map();
@@ -70,7 +72,7 @@ const getRoles = (container: Container): Map<string, Gtk.Widget[]> => {
 };
 
 const formatWidgetPreview = (widget: Gtk.Widget, name: string | null): string => {
-    const tagName = widget.constructor.name;
+    const tagName = getTypeTag(widget);
     const roleAttr = formatRole(widget.getAccessibleRole());
     const nameDisplay = name ? `Name "${name}"` : 'Name ""';
 
@@ -80,6 +82,7 @@ const formatWidgetPreview = (widget: Gtk.Widget, name: string | null): string =>
 /**
  * Formats the accessible roles in a container's tree as a readable string,
  * listing each role together with its widgets and their accessible names.
+ * Widgets that are not mapped are left out.
  *
  * @param container The scope to inspect.
  */
@@ -116,4 +119,12 @@ const logRoles = (container: Container): void => {
     console.log(prettyRoles(container));
 };
 
-export { formatRole, formatRoleList, getRoles, prettyRoles, logRoles };
+/**
+ * Returns the heading or hierarchy level GTK reports for a widget, or undefined when it declares
+ * none.
+ *
+ * @param widget The widget to read the level from.
+ */
+const computeHeadingLevel = (widget: Gtk.Widget): number | undefined => getWidgetLevel(widget) ?? undefined;
+
+export { computeHeadingLevel, formatRole, formatRoleList, getRoles, prettyRoles, logRoles };

package/src/role-naming.ts

@@ -0,0 +1,99 @@
+import * as Gtk from "@gtkx/gi/gtk";
+
+const FROM_AUTHOR = 1;
+const FROM_CONTENT = 2;
+const PROHIBITED = 4;
+
+const NAMING: Partial<Record<Gtk.AccessibleRole, number>> = {
+    [Gtk.AccessibleRole.ALERT]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.ALERT_DIALOG]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.APPLICATION]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.ARTICLE]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.BANNER]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.BLOCK_QUOTE]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.BUTTON]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.CAPTION]: PROHIBITED,
+    [Gtk.AccessibleRole.CELL]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.CHECKBOX]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.COLUMN_HEADER]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.COMBO_BOX]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.COMMAND]: PROHIBITED,
+    [Gtk.AccessibleRole.COMMENT]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.COMPOSITE]: PROHIBITED,
+    [Gtk.AccessibleRole.DIALOG]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.DOCUMENT]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.FEED]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.FORM]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.GENERIC]: PROHIBITED,
+    [Gtk.AccessibleRole.GRID]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.GRID_CELL]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.GROUP]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.HEADING]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.IMG]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.INPUT]: PROHIBITED,
+    [Gtk.AccessibleRole.LABEL]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.LANDMARK]: PROHIBITED,
+    [Gtk.AccessibleRole.LEGEND]: PROHIBITED,
+    [Gtk.AccessibleRole.LINK]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.LIST]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.LIST_BOX]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.LIST_ITEM]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.LOG]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.MAIN]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.MARQUEE]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.MATH]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.METER]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.MENU]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.MENU_BAR]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.MENU_ITEM]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.MENU_ITEM_CHECKBOX]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.MENU_ITEM_RADIO]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.NAVIGATION]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.NONE]: PROHIBITED,
+    [Gtk.AccessibleRole.NOTE]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.OPTION]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.PARAGRAPH]: PROHIBITED,
+    [Gtk.AccessibleRole.PRESENTATION]: PROHIBITED,
+    [Gtk.AccessibleRole.PROGRESS_BAR]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.RADIO]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.RADIO_GROUP]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.RANGE]: PROHIBITED,
+    [Gtk.AccessibleRole.REGION]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.ROW]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.ROW_GROUP]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.ROW_HEADER]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.SCROLLBAR]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.SEARCH]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.SEARCH_BOX]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.SECTION]: PROHIBITED,
+    [Gtk.AccessibleRole.SECTION_HEAD]: PROHIBITED,
+    [Gtk.AccessibleRole.SELECT]: PROHIBITED,
+    [Gtk.AccessibleRole.SEPARATOR]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.SLIDER]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.SPIN_BUTTON]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.STATUS]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.STRUCTURE]: PROHIBITED,
+    [Gtk.AccessibleRole.SWITCH]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.TAB]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.TABLE]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TAB_LIST]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TAB_PANEL]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TERMINAL]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TEXT_BOX]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TIME]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TIMER]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TOGGLE_BUTTON]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TOOLBAR]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TOOLTIP]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.TREE]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TREE_GRID]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TREE_ITEM]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.WIDGET]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.WINDOW]: FROM_AUTHOR,
+};
+
+const namingFor = (role: Gtk.AccessibleRole): number => NAMING[role] ?? 0;
+const isNameProhibited = (role: Gtk.AccessibleRole): boolean => (namingFor(role) & PROHIBITED) !== 0;
+const isNameFromAuthor = (role: Gtk.AccessibleRole): boolean => (namingFor(role) & FROM_AUTHOR) !== 0;
+
+export { isNameFromAuthor, isNameProhibited };