@gtkx/testing 0.11.1 → 0.12.0

package/dist/queries.js

@@ -1,7 +1,8 @@
-import { getNativeObject } from "@gtkx/ffi";
-import * as Gtk from "@gtkx/ffi/gtk";
+import { buildMultipleFoundError, buildNotFoundError, buildTimeoutError } from "./error-builder.js";
 import { findAll } from "./traversal.js";
-import { waitFor } from "./wait-for.js";
+import { getWidgetCheckedState, getWidgetExpandedState, getWidgetTestId, getWidgetText } from "./widget-text.js";
+const DEFAULT_TIMEOUT = 1000;
+const DEFAULT_INTERVAL = 50;
 const buildNormalizer = (options) => {
     if (options?.normalizer) {
         return options.normalizer;
@@ -38,126 +39,6 @@ const matchText = (actual, expected, widget, options) => {
     const exact = options?.exact ?? true;
     return exact ? normalizedActual === normalizedExpected : normalizedActual.includes(normalizedExpected);
 };
-const ROLES_WITH_INTERNAL_LABELS = new Set([
-    Gtk.AccessibleRole.BUTTON,
-    Gtk.AccessibleRole.TOGGLE_BUTTON,
-    Gtk.AccessibleRole.CHECKBOX,
-    Gtk.AccessibleRole.RADIO,
-    Gtk.AccessibleRole.MENU_ITEM,
-    Gtk.AccessibleRole.MENU_ITEM_CHECKBOX,
-    Gtk.AccessibleRole.MENU_ITEM_RADIO,
-    Gtk.AccessibleRole.TAB,
-    Gtk.AccessibleRole.LINK,
-]);
-const isInternalLabel = (widget) => {
-    if (widget.getAccessibleRole() !== Gtk.AccessibleRole.LABEL)
-        return false;
-    const parent = widget.getParent();
-    if (!parent)
-        return false;
-    if (parent.getAccessibleRole === undefined)
-        return false;
-    const parentRole = parent.getAccessibleRole();
-    if (!parentRole)
-        return false;
-    return ROLES_WITH_INTERNAL_LABELS.has(parentRole);
-};
-const getLabelText = (widget) => {
-    const asLabel = widget;
-    const asInscription = widget;
-    return asLabel.getLabel?.() ?? asInscription.getText?.() ?? null;
-};
-const collectChildLabels = (widget) => {
-    const labels = [];
-    let child = widget.getFirstChild();
-    while (child) {
-        if (child.getAccessibleRole() === Gtk.AccessibleRole.LABEL) {
-            const labelText = getLabelText(child);
-            if (labelText)
-                labels.push(labelText);
-        }
-        labels.push(...collectChildLabels(child));
-        child = child.getNextSibling();
-    }
-    return labels;
-};
-const getWidgetText = (widget) => {
-    if (isInternalLabel(widget))
-        return null;
-    const role = widget.getAccessibleRole();
-    if (role === undefined)
-        return null;
-    switch (role) {
-        case Gtk.AccessibleRole.BUTTON:
-        case Gtk.AccessibleRole.LINK:
-        case Gtk.AccessibleRole.TAB: {
-            const directLabel = widget.getLabel?.() ??
-                widget.getLabel?.() ??
-                widget.getLabel?.();
-            if (directLabel)
-                return directLabel;
-            const childLabels = collectChildLabels(widget);
-            return childLabels.length > 0 ? childLabels.join(" ") : null;
-        }
-        case Gtk.AccessibleRole.TOGGLE_BUTTON:
-            return widget.getLabel?.() ?? null;
-        case Gtk.AccessibleRole.CHECKBOX:
-        case Gtk.AccessibleRole.RADIO:
-            return widget.getLabel?.() ?? null;
-        case Gtk.AccessibleRole.LABEL:
-            return getLabelText(widget);
-        case Gtk.AccessibleRole.TEXT_BOX:
-        case Gtk.AccessibleRole.SEARCH_BOX:
-        case Gtk.AccessibleRole.SPIN_BUTTON:
-            return getNativeObject(widget.id, Gtk.Editable).getText() ?? null;
-        case Gtk.AccessibleRole.GROUP:
-            return widget.getLabel?.() ?? null;
-        case Gtk.AccessibleRole.WINDOW:
-        case Gtk.AccessibleRole.DIALOG:
-        case Gtk.AccessibleRole.ALERT_DIALOG:
-            return widget.getTitle() ?? null;
-        case Gtk.AccessibleRole.TAB_PANEL: {
-            const parent = widget.getParent();
-            if (parent) {
-                const stack = parent;
-                const page = stack.getPage?.(widget);
-                if (page) {
-                    return page.getTitle() ?? null;
-                }
-            }
-            return null;
-        }
-        default:
-            return null;
-    }
-};
-const getWidgetTestId = (widget) => {
-    return widget.getName();
-};
-const getWidgetCheckedState = (widget) => {
-    const role = widget.getAccessibleRole();
-    switch (role) {
-        case Gtk.AccessibleRole.CHECKBOX:
-        case Gtk.AccessibleRole.RADIO:
-            return widget.getActive();
-        case Gtk.AccessibleRole.TOGGLE_BUTTON:
-            return widget.getActive();
-        case Gtk.AccessibleRole.SWITCH:
-            return widget.getActive();
-        default:
-            return null;
-    }
-};
-const getWidgetExpandedState = (widget) => {
-    const role = widget.getAccessibleRole();
-    if (role === Gtk.AccessibleRole.BUTTON) {
-        const parent = widget.getParent();
-        if (!parent)
-            return null;
-        return parent.getExpanded?.() ?? null;
-    }
-    return null;
-};
 const matchByRoleOptions = (widget, options) => {
     if (!options)
         return true;
@@ -178,103 +59,201 @@ const matchByRoleOptions = (widget, options) => {
     }
     return true;
 };
-const formatRole = (role) => Gtk.AccessibleRole[role] ?? String(role);
-const formatByRoleError = (role, options) => {
-    const parts = [`role '${formatRole(role)}'`];
-    if (options?.name)
-        parts.push(`name '${options.name}'`);
-    if (options?.checked !== undefined)
-        parts.push(`checked=${options.checked}`);
-    if (options?.pressed !== undefined)
-        parts.push(`pressed=${options.pressed}`);
-    if (options?.selected !== undefined)
-        parts.push(`selected=${options.selected}`);
-    if (options?.expanded !== undefined)
-        parts.push(`expanded=${options.expanded}`);
-    if (options?.level !== undefined)
-        parts.push(`level=${options.level}`);
-    return parts.join(" and ");
+const waitFor = async (callback, options) => {
+    const { timeout = DEFAULT_TIMEOUT, interval = DEFAULT_INTERVAL, onTimeout } = options ?? {};
+    const startTime = Date.now();
+    let lastError = null;
+    while (Date.now() - startTime < timeout) {
+        try {
+            return await callback();
+        }
+        catch (error) {
+            lastError = error;
+            await new Promise((resolve) => setTimeout(resolve, interval));
+        }
+    }
+    const timeoutError = buildTimeoutError(timeout, lastError);
+    if (onTimeout) {
+        throw onTimeout(timeoutError);
+    }
+    throw timeoutError;
 };
-const getAllByRole = (container, role, options) => {
-    const matches = findAll(container, (node) => {
+/**
+ * Finds all elements matching a role without throwing.
+ *
+ * @param container - The container to search within
+ * @param role - The GTK accessible role to match
+ * @param options - Query options including name and state filters
+ * @returns Array of matching widgets (empty if none found)
+ */
+export const queryAllByRole = (container, role, options) => {
+    return findAll(container, (node) => {
         if (node.getAccessibleRole() !== role)
             return false;
         return matchByRoleOptions(node, options);
     });
+};
+/**
+ * Finds a single element matching a role without throwing.
+ *
+ * @param container - The container to search within
+ * @param role - The GTK accessible role to match
+ * @param options - Query options including name and state filters
+ * @returns The matching widget or null if not found
+ * @throws Error if multiple elements match
+ */
+export const queryByRole = (container, role, options) => {
+    const matches = queryAllByRole(container, role, options);
+    if (matches.length > 1) {
+        throw buildMultipleFoundError(container, "role", { role, options }, matches.length);
+    }
+    return matches[0] ?? null;
+};
+/**
+ * Finds all elements matching label text without throwing.
+ *
+ * @param container - The container to search within
+ * @param text - Text to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization
+ * @returns Array of matching widgets (empty if none found)
+ */
+export const queryAllByLabelText = (container, text, options) => {
+    return findAll(container, (node) => {
+        const widgetText = getWidgetText(node);
+        return matchText(widgetText, text, node, options);
+    });
+};
+/**
+ * Finds a single element matching label text without throwing.
+ *
+ * @param container - The container to search within
+ * @param text - Text to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization
+ * @returns The matching widget or null if not found
+ * @throws Error if multiple elements match
+ */
+export const queryByLabelText = (container, text, options) => {
+    const matches = queryAllByLabelText(container, text, options);
+    if (matches.length > 1) {
+        throw buildMultipleFoundError(container, "labelText", { text, options }, matches.length);
+    }
+    return matches[0] ?? null;
+};
+/**
+ * Finds all elements matching text content without throwing.
+ *
+ * @param container - The container to search within
+ * @param text - Text to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization
+ * @returns Array of matching widgets (empty if none found)
+ */
+export const queryAllByText = (container, text, options) => {
+    return findAll(container, (node) => {
+        const widgetText = getWidgetText(node);
+        return matchText(widgetText, text, node, options);
+    });
+};
+/**
+ * Finds a single element matching text content without throwing.
+ *
+ * @param container - The container to search within
+ * @param text - Text to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization
+ * @returns The matching widget or null if not found
+ * @throws Error if multiple elements match
+ */
+export const queryByText = (container, text, options) => {
+    const matches = queryAllByText(container, text, options);
+    if (matches.length > 1) {
+        throw buildMultipleFoundError(container, "text", { text, options }, matches.length);
+    }
+    return matches[0] ?? null;
+};
+/**
+ * Finds all elements matching a test ID without throwing.
+ *
+ * @param container - The container to search within
+ * @param testId - Test ID to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization
+ * @returns Array of matching widgets (empty if none found)
+ */
+export const queryAllByTestId = (container, testId, options) => {
+    return findAll(container, (node) => {
+        const widgetTestId = getWidgetTestId(node);
+        return matchText(widgetTestId, testId, node, options);
+    });
+};
+/**
+ * Finds a single element matching a test ID without throwing.
+ *
+ * @param container - The container to search within
+ * @param testId - Test ID to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization
+ * @returns The matching widget or null if not found
+ * @throws Error if multiple elements match
+ */
+export const queryByTestId = (container, testId, options) => {
+    const matches = queryAllByTestId(container, testId, options);
+    if (matches.length > 1) {
+        throw buildMultipleFoundError(container, "testId", { testId, options }, matches.length);
+    }
+    return matches[0] ?? null;
+};
+const getAllByRole = (container, role, options) => {
+    const matches = queryAllByRole(container, role, options);
     if (matches.length === 0) {
-        throw new Error(`Unable to find any elements with ${formatByRoleError(role, options)}`);
+        throw buildNotFoundError(container, "role", { role, options });
     }
     return matches;
 };
 const getByRole = (container, role, options) => {
     const matches = getAllByRole(container, role, options);
     if (matches.length > 1) {
-        throw new Error(`Expected 1 element with ${formatByRoleError(role, options)}, found ${matches.length}`);
+        throw buildMultipleFoundError(container, "role", { role, options }, matches.length);
     }
-    const [first] = matches;
-    if (!first)
-        throw new Error(`Unable to find element with ${formatByRoleError(role, options)}`);
-    return first;
+    return matches[0];
 };
 const getAllByLabelText = (container, text, options) => {
-    const matches = findAll(container, (node) => {
-        const widgetText = getWidgetText(node);
-        return matchText(widgetText, text, node, options);
-    });
+    const matches = queryAllByLabelText(container, text, options);
     if (matches.length === 0) {
-        throw new Error(`Unable to find any elements with label text '${text}'`);
+        throw buildNotFoundError(container, "labelText", { text, options });
     }
     return matches;
 };
 const getByLabelText = (container, text, options) => {
     const matches = getAllByLabelText(container, text, options);
     if (matches.length > 1) {
-        throw new Error(`Expected 1 element with label text '${text}', found ${matches.length}`);
+        throw buildMultipleFoundError(container, "labelText", { text, options }, matches.length);
     }
-    const [first] = matches;
-    if (!first)
-        throw new Error(`Unable to find element with label text '${text}'`);
-    return first;
+    return matches[0];
 };
 const getAllByText = (container, text, options) => {
-    const matches = findAll(container, (node) => {
-        const widgetText = getWidgetText(node);
-        return matchText(widgetText, text, node, options);
-    });
+    const matches = queryAllByText(container, text, options);
     if (matches.length === 0) {
-        throw new Error(`Unable to find any elements with text '${text}'`);
+        throw buildNotFoundError(container, "text", { text, options });
     }
     return matches;
 };
 const getByText = (container, text, options) => {
     const matches = getAllByText(container, text, options);
     if (matches.length > 1) {
-        throw new Error(`Expected 1 element with text '${text}', found ${matches.length}`);
+        throw buildMultipleFoundError(container, "text", { text, options }, matches.length);
     }
-    const [first] = matches;
-    if (!first)
-        throw new Error(`Unable to find element with text '${text}'`);
-    return first;
+    return matches[0];
 };
 const getAllByTestId = (container, testId, options) => {
-    const matches = findAll(container, (node) => {
-        const widgetTestId = getWidgetTestId(node);
-        return matchText(widgetTestId, testId, node, options);
-    });
+    const matches = queryAllByTestId(container, testId, options);
     if (matches.length === 0) {
-        throw new Error(`Unable to find any elements with test id '${testId}'`);
+        throw buildNotFoundError(container, "testId", { testId, options });
     }
     return matches;
 };
 const getByTestId = (container, testId, options) => {
     const matches = getAllByTestId(container, testId, options);
     if (matches.length > 1) {
-        throw new Error(`Expected 1 element with test id '${testId}', found ${matches.length}`);
+        throw buildMultipleFoundError(container, "testId", { testId, options }, matches.length);
     }
-    const [first] = matches;
-    if (!first)
-        throw new Error(`Unable to find element with test id '${testId}'`);
-    return first;
+    return matches[0];
 };
 /**
  * Finds a single element by accessible role.

package/dist/render.js

@@ -1,38 +1,14 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { discardAllBatches, start } from "@gtkx/ffi";
 import * as Gio from "@gtkx/ffi/gio";
-import * as Gtk from "@gtkx/ffi/gtk";
 import { ApplicationContext, GtkApplicationWindow, reconciler } from "@gtkx/react";
-import * as queries from "./queries.js";
+import { bindQueries } from "./bind-queries.js";
+import { prettyWidget } from "./pretty-widget.js";
 import { setScreenRoot } from "./screen.js";
 import { tick } from "./timing.js";
-import { hasLabel } from "./widget.js";
 let application = null;
 let container = null;
 let lastRenderError = null;
-const getWidgetLabel = (widget) => {
-    if (!hasLabel(widget))
-        return null;
-    const role = widget.getAccessibleRole();
-    if (role === Gtk.AccessibleRole.LABEL) {
-        return widget.getLabel?.() ?? null;
-    }
-    return widget.getLabel?.() ?? null;
-};
-const printWidgetTree = (root, indent = 0) => {
-    const prefix = "  ".repeat(indent);
-    const role = root.getAccessibleRole();
-    const roleName = role !== undefined ? (Gtk.AccessibleRole[role] ?? "UNKNOWN") : "UNKNOWN";
-    const labelText = getWidgetLabel(root);
-    const label = labelText ? ` label="${labelText}"` : "";
-    let result = `${prefix}<${root.constructor.name} role=${roleName}${label}>\n`;
-    let child = root.getFirstChild();
-    while (child) {
-        result += printWidgetTree(child, indent + 1);
-        child = child.getNextSibling();
-    }
-    return result;
-};
 const update = async (instance, element, fiberRoot) => {
     lastRenderError = null;
     instance.updateContainer(element, fiberRoot, null, () => { });
@@ -97,14 +73,7 @@ export const render = async (element, options) => {
     setScreenRoot(application);
     return {
         container: application,
-        findByRole: (role, opts) => queries.findByRole(application, role, opts),
-        findByLabelText: (text, opts) => queries.findByLabelText(application, text, opts),
-        findByText: (text, opts) => queries.findByText(application, text, opts),
-        findByTestId: (testId, opts) => queries.findByTestId(application, testId, opts),
-        findAllByRole: (role, opts) => queries.findAllByRole(application, role, opts),
-        findAllByLabelText: (text, opts) => queries.findAllByLabelText(application, text, opts),
-        findAllByText: (text, opts) => queries.findAllByText(application, text, opts),
-        findAllByTestId: (testId, opts) => queries.findAllByTestId(application, testId, opts),
+        ...bindQueries(application),
         unmount: () => update(instance, null, fiberRoot),
         rerender: (newElement) => {
             const wrapped = wrapElement(newElement, options?.wrapper);
@@ -112,10 +81,7 @@ export const render = async (element, options) => {
             return update(instance, withCtx, fiberRoot);
         },
         debug: () => {
-            const activeWindow = application.getActiveWindow();
-            if (activeWindow) {
-                console.log(printWidgetTree(activeWindow));
-            }
+            console.log(prettyWidget(application));
         },
     };
 };

package/dist/role-helpers.d.ts

@@ -0,0 +1,66 @@
+import * as Gtk from "@gtkx/ffi/gtk";
+import { type Container } from "./traversal.js";
+/**
+ * Information about a widget and its accessible name.
+ */
+export type RoleInfo = {
+    widget: Gtk.Widget;
+    name: string | null;
+};
+/**
+ * Formats a GTK accessible role to a lowercase string.
+ *
+ * @param role - The GTK accessible role
+ * @returns Lowercase role name (e.g., "button", "checkbox")
+ */
+export declare const formatRole: (role: Gtk.AccessibleRole | undefined) => string;
+/**
+ * Collects all accessible roles and their widgets from a container.
+ *
+ * Returns a Map where keys are role names (lowercase) and values are
+ * arrays of widgets with that role, including their accessible names.
+ *
+ * @param container - The container to scan for roles
+ * @returns Map of role names to arrays of RoleInfo
+ *
+ * @example
+ * ```tsx
+ * import { getRoles } from "@gtkx/testing";
+ *
+ * const roles = getRoles(container);
+ * // Map {
+ * //   "button" => [{ widget: ..., name: "Submit" }, { widget: ..., name: "Cancel" }],
+ * //   "checkbox" => [{ widget: ..., name: "Remember me" }]
+ * // }
+ * ```
+ */
+export declare const getRoles: (container: Container) => Map<string, RoleInfo[]>;
+/**
+ * Formats roles into a readable string for error messages.
+ *
+ * @param container - The container to format roles for
+ * @returns Formatted string showing all roles and their accessible names
+ */
+export declare const prettyRoles: (container: Container) => string;
+/**
+ * Logs all accessible roles in a container to the console.
+ *
+ * Useful for debugging test failures and discovering available roles.
+ *
+ * @param container - The container to log roles for
+ *
+ * @example
+ * ```tsx
+ * import { render, logRoles } from "@gtkx/testing";
+ *
+ * const { container } = await render(<MyComponent />);
+ * logRoles(container);
+ * // Console output:
+ * // button:
+ * //   Name "Submit": <GtkButton role="button">Submit</GtkButton>
+ * //   Name "Cancel": <GtkButton role="button">Cancel</GtkButton>
+ * // checkbox:
+ * //   Name "Remember me": <GtkCheckButton role="checkbox">Remember me</GtkCheckButton>
+ * ```
+ */
+export declare const logRoles: (container: Container) => void;

package/dist/role-helpers.js

@@ -0,0 +1,108 @@
+import * as Gtk from "@gtkx/ffi/gtk";
+import { traverse } from "./traversal.js";
+import { getWidgetText } from "./widget-text.js";
+/**
+ * Formats a GTK accessible role to a lowercase string.
+ *
+ * @param role - The GTK accessible role
+ * @returns Lowercase role name (e.g., "button", "checkbox")
+ */
+export const formatRole = (role) => {
+    if (role === undefined)
+        return "unknown";
+    const name = Gtk.AccessibleRole[role];
+    if (!name)
+        return String(role);
+    return name.toLowerCase();
+};
+/**
+ * Collects all accessible roles and their widgets from a container.
+ *
+ * Returns a Map where keys are role names (lowercase) and values are
+ * arrays of widgets with that role, including their accessible names.
+ *
+ * @param container - The container to scan for roles
+ * @returns Map of role names to arrays of RoleInfo
+ *
+ * @example
+ * ```tsx
+ * import { getRoles } from "@gtkx/testing";
+ *
+ * const roles = getRoles(container);
+ * // Map {
+ * //   "button" => [{ widget: ..., name: "Submit" }, { widget: ..., name: "Cancel" }],
+ * //   "checkbox" => [{ widget: ..., name: "Remember me" }]
+ * // }
+ * ```
+ */
+export const getRoles = (container) => {
+    const roles = new Map();
+    for (const widget of traverse(container)) {
+        const role = widget.getAccessibleRole?.();
+        if (role === undefined)
+            continue;
+        const roleName = formatRole(role);
+        const name = getWidgetText(widget);
+        const info = { widget, name };
+        const existing = roles.get(roleName);
+        if (existing) {
+            existing.push(info);
+        }
+        else {
+            roles.set(roleName, [info]);
+        }
+    }
+    return roles;
+};
+const formatWidgetPreview = (widget, name) => {
+    const tagName = widget.constructor.name;
+    const roleAttr = formatRole(widget.getAccessibleRole?.());
+    const nameDisplay = name ? `Name "${name}"` : 'Name ""';
+    return `${nameDisplay}: <${tagName} role="${roleAttr}">${name ?? ""}</${tagName}>`;
+};
+/**
+ * Formats roles into a readable string for error messages.
+ *
+ * @param container - The container to format roles for
+ * @returns Formatted string showing all roles and their accessible names
+ */
+export const prettyRoles = (container) => {
+    const roles = getRoles(container);
+    if (roles.size === 0) {
+        return "No accessible roles found in the widget tree.";
+    }
+    const lines = [];
+    const sortedRoles = [...roles.entries()].sort(([a], [b]) => a.localeCompare(b));
+    for (const [roleName, widgets] of sortedRoles) {
+        lines.push(`${roleName}:`);
+        for (const { widget, name } of widgets) {
+            lines.push(`  ${formatWidgetPreview(widget, name)}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd();
+};
+/**
+ * Logs all accessible roles in a container to the console.
+ *
+ * Useful for debugging test failures and discovering available roles.
+ *
+ * @param container - The container to log roles for
+ *
+ * @example
+ * ```tsx
+ * import { render, logRoles } from "@gtkx/testing";
+ *
+ * const { container } = await render(<MyComponent />);
+ * logRoles(container);
+ * // Console output:
+ * // button:
+ * //   Name "Submit": <GtkButton role="button">Submit</GtkButton>
+ * //   Name "Cancel": <GtkButton role="button">Cancel</GtkButton>
+ * // checkbox:
+ * //   Name "Remember me": <GtkCheckButton role="checkbox">Remember me</GtkCheckButton>
+ * ```
+ */
+export const logRoles = (container) => {
+    console.log(prettyRoles(container));
+};