@gtkx/testing 0.18.0 → 0.18.2

package/src/wait-for.ts

@@ -0,0 +1,115 @@
+import type * as Gtk from "@gtkx/ffi/gtk";
+import { getConfig } from "./config.js";
+import { buildTimeoutError } from "./error-builder.js";
+import type { WaitForOptions } from "./types.js";
+
+const DEFAULT_INTERVAL = 50;
+
+/**
+ * Waits for a callback to succeed.
+ *
+ * Repeatedly calls the callback until it returns without throwing,
+ * or until the timeout is reached.
+ *
+ * @param callback - Function to execute repeatedly
+ * @param options - Timeout and interval configuration
+ * @returns Promise resolving to the callback's return value
+ *
+ * @example
+ * ```tsx
+ * import { waitFor } from "@gtkx/testing";
+ *
+ * await waitFor(() => {
+ *   expect(counter.value).toBe(5);
+ * }, { timeout: 2000 });
+ * ```
+ */
+export const waitFor = async <T>(callback: () => T | Promise<T>, options?: WaitForOptions): Promise<T> => {
+    const config = getConfig();
+    const { timeout = config.asyncUtilTimeout, interval = DEFAULT_INTERVAL, onTimeout } = options ?? {};
+    const startTime = Date.now();
+    let lastError: Error | null = null;
+
+    while (Date.now() - startTime < timeout) {
+        try {
+            return await callback();
+        } catch (error) {
+            lastError = error as Error;
+            await new Promise((resolve) => setTimeout(resolve, interval));
+        }
+    }
+
+    const timeoutError = buildTimeoutError(timeout, lastError);
+    if (onTimeout) {
+        throw onTimeout(timeoutError);
+    }
+    throw timeoutError;
+};
+
+type ElementOrCallback = Gtk.Widget | (() => Gtk.Widget | null);
+
+const getElement = (elementOrCallback: ElementOrCallback): Gtk.Widget | null => {
+    if (typeof elementOrCallback === "function") {
+        return elementOrCallback();
+    }
+    return elementOrCallback;
+};
+
+const isElementRemoved = (element: Gtk.Widget | null): boolean => {
+    if (element === null) return true;
+
+    try {
+        const parent = element.getParent();
+        return parent === null;
+    } catch {
+        return true;
+    }
+};
+
+/**
+ * Waits for an element to be removed from the widget tree.
+ *
+ * Polls until the element no longer has a parent or no longer exists.
+ *
+ * @param elementOrCallback - Element or function returning element to watch
+ * @param options - Timeout and interval configuration
+ *
+ * @example
+ * ```tsx
+ * import { waitForElementToBeRemoved } from "@gtkx/testing";
+ *
+ * const loader = await screen.findByRole(Gtk.AccessibleRole.PROGRESS_BAR);
+ * await waitForElementToBeRemoved(loader);
+ * // Loader is now gone
+ * ```
+ */
+export const waitForElementToBeRemoved = async (
+    elementOrCallback: ElementOrCallback,
+    options?: WaitForOptions,
+): Promise<void> => {
+    const config = getConfig();
+    const { timeout = config.asyncUtilTimeout, interval = DEFAULT_INTERVAL, onTimeout } = options ?? {};
+
+    const initialElement = getElement(elementOrCallback);
+    if (initialElement === null || isElementRemoved(initialElement)) {
+        throw new Error(
+            "Element already removed: waitForElementToBeRemoved requires the element to be present initially",
+        );
+    }
+
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < timeout) {
+        const element = getElement(elementOrCallback);
+        if (isElementRemoved(element)) {
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+
+    const timeoutError = new Error(`Timed out after ${timeout}ms waiting for element to be removed.`);
+    if (onTimeout) {
+        throw onTimeout(timeoutError);
+    }
+    throw timeoutError;
+};

package/src/widget-text.ts

@@ -0,0 +1,206 @@
+import { getNativeInterface } from "@gtkx/ffi";
+import * as Gtk from "@gtkx/ffi/gtk";
+
+const ROLES_WITH_INTERNAL_LABELS = new Set([
+    Gtk.AccessibleRole.BUTTON,
+    Gtk.AccessibleRole.TOGGLE_BUTTON,
+    Gtk.AccessibleRole.CHECKBOX,
+    Gtk.AccessibleRole.RADIO,
+    Gtk.AccessibleRole.LIST_ITEM,
+    Gtk.AccessibleRole.MENU_ITEM,
+    Gtk.AccessibleRole.MENU_ITEM_CHECKBOX,
+    Gtk.AccessibleRole.MENU_ITEM_RADIO,
+    Gtk.AccessibleRole.ROW,
+    Gtk.AccessibleRole.TAB,
+    Gtk.AccessibleRole.LINK,
+]);
+
+const isInternalLabel = (widget: Gtk.Widget): boolean => {
+    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;
+
+    if (ROLES_WITH_INTERNAL_LABELS.has(parentRole)) return true;
+
+    const labelText = getLabelText(widget);
+    if (!labelText) return false;
+
+    let ancestor: Gtk.Widget | null = parent;
+    while (ancestor) {
+        if (ancestor.getAccessibleRole === undefined) return false;
+        const role = ancestor.getAccessibleRole();
+        if (role && ROLES_WITH_INTERNAL_LABELS.has(role)) {
+            return getDefaultText(ancestor) === labelText;
+        }
+        ancestor = ancestor.getParent();
+    }
+
+    return false;
+};
+
+const getLabelText = (widget: Gtk.Widget): string | null => {
+    const asLabel = widget as Gtk.Label;
+    const asInscription = widget as Gtk.Inscription;
+    return asLabel.getLabel?.() ?? asInscription.getText?.() ?? null;
+};
+
+const getDefaultText = (widget: Gtk.Widget): string | null => {
+    if ("getLabel" in widget && typeof widget.getLabel === "function") {
+        return (widget.getLabel() as string) ?? null;
+    }
+
+    if ("getText" in widget && typeof widget.getText === "function") {
+        return (widget.getText() as string) ?? null;
+    }
+
+    if ("getTitle" in widget && typeof widget.getTitle === "function") {
+        return (widget.getTitle() as string) ?? null;
+    }
+
+    return getNativeInterface(widget, Gtk.Editable)?.getText() ?? null;
+};
+
+const collectChildLabels = (widget: Gtk.Widget): string[] => {
+    const labels: string[] = [];
+    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;
+};
+
+/**
+ * Extracts the accessible text content from a widget based on its role.
+ *
+ * @param widget - The widget to extract text from
+ * @returns The accessible text or null if none found
+ */
+export const getWidgetText = (widget: Gtk.Widget): string | null => {
+    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:
+        case Gtk.AccessibleRole.MENU_ITEM:
+        case Gtk.AccessibleRole.MENU_ITEM_CHECKBOX:
+        case Gtk.AccessibleRole.MENU_ITEM_RADIO: {
+            const directLabel = getDefaultText(widget);
+            if (directLabel) return directLabel;
+
+            const childLabels = collectChildLabels(widget);
+            return childLabels.length > 0 ? childLabels.join(" ") : null;
+        }
+        case Gtk.AccessibleRole.TAB_PANEL: {
+            const parent = widget.getParent();
+            if (parent) {
+                const stack = parent as Gtk.Stack;
+                const page = stack.getPage?.(widget);
+                if (page) {
+                    return page.getTitle() ?? null;
+                }
+            }
+            return null;
+        }
+        default:
+            return getDefaultText(widget);
+    }
+};
+
+/**
+ * Gets the test ID from a widget (uses the widget's name property).
+ *
+ * @param widget - The widget to get the test ID from
+ * @returns The test ID or null if not set
+ */
+export const getWidgetTestId = (widget: Gtk.Widget): string | null => {
+    return widget.getName();
+};
+
+/**
+ * Gets the checked state from toggle-like widgets.
+ *
+ * @param widget - The widget to get the checked state from
+ * @returns The checked state or null if not applicable
+ */
+export const getWidgetCheckedState = (widget: Gtk.Widget): boolean | null => {
+    const role = widget.getAccessibleRole();
+
+    switch (role) {
+        case Gtk.AccessibleRole.CHECKBOX:
+        case Gtk.AccessibleRole.RADIO:
+            return (widget as Gtk.CheckButton).getActive();
+        case Gtk.AccessibleRole.TOGGLE_BUTTON:
+            return (widget as Gtk.ToggleButton).getActive();
+        case Gtk.AccessibleRole.SWITCH:
+            return (widget as Gtk.Switch).getActive();
+        default:
+            return null;
+    }
+};
+
+/**
+ * Gets the pressed state from toggle button widgets.
+ *
+ * @param widget - The widget to get the pressed state from
+ * @returns The pressed state or null if not applicable
+ */
+export const getWidgetPressedState = (widget: Gtk.Widget): boolean | null => {
+    const role = widget.getAccessibleRole();
+
+    if (role === Gtk.AccessibleRole.TOGGLE_BUTTON) {
+        return (widget as Gtk.ToggleButton).getActive();
+    }
+
+    return null;
+};
+
+/**
+ * Gets the expanded state from expander widgets.
+ *
+ * @param widget - The widget to get the expanded state from
+ * @returns The expanded state or null if not applicable
+ */
+export const getWidgetExpandedState = (widget: Gtk.Widget): boolean | null => {
+    if (widget instanceof Gtk.Expander) {
+        return widget.getExpanded();
+    }
+
+    if (widget instanceof Gtk.TreeExpander) {
+        return widget.getListRow()?.getExpanded() ?? null;
+    }
+
+    return null;
+};
+
+/**
+ * Gets the selected state from selectable widgets.
+ *
+ * @param widget - The widget to get the selected state from
+ * @returns The selected state or null if not applicable
+ */
+export const getWidgetSelectedState = (widget: Gtk.Widget): boolean | null => {
+    const role = widget.getAccessibleRole();
+
+    if (role === Gtk.AccessibleRole.ROW) {
+        return (widget as Gtk.ListBoxRow).isSelected();
+    }
+
+    return null;
+};

package/src/widget.ts

@@ -0,0 +1,15 @@
+import * as Gtk from "@gtkx/ffi/gtk";
+
+const EDITABLE_ROLES = new Set([
+    Gtk.AccessibleRole.TEXT_BOX,
+    Gtk.AccessibleRole.SEARCH_BOX,
+    Gtk.AccessibleRole.SPIN_BUTTON,
+]);
+
+export const isEditable = (widget: unknown): widget is Gtk.Editable => {
+    if (!(widget instanceof Gtk.Widget)) {
+        return false;
+    }
+
+    return EDITABLE_ROLES.has(widget.getAccessibleRole());
+};

package/src/within.ts

@@ -0,0 +1,31 @@
+import type * as Gtk from "@gtkx/ffi/gtk";
+import { bindQueries } from "./bind-queries.js";
+import type { BoundQueries } from "./types.js";
+
+/**
+ * Creates scoped query methods for a container widget.
+ *
+ * Use this to query within a specific section of your UI rather than
+ * the entire application.
+ *
+ * @param container - The widget to scope queries to
+ * @returns Object with query methods bound to the container
+ *
+ * @example
+ * ```tsx
+ * import { render, within } from "@gtkx/testing";
+ *
+ * test("scoped queries", async () => {
+ *   await render(<MyPage />);
+ *
+ *   const sidebar = await screen.findByRole(Gtk.AccessibleRole.NAVIGATION);
+ *   const sidebarQueries = within(sidebar);
+ *
+ *   // Only searches within the sidebar
+ *   const navButton = await sidebarQueries.findByRole(Gtk.AccessibleRole.BUTTON);
+ * });
+ * ```
+ *
+ * @see {@link screen} for global queries
+ */
+export const within = (container: Gtk.Widget): BoundQueries => bindQueries(container);