@gtkx/testing 0.21.0 → 1.0.0-rc.2

package/src/wait-for.ts

@@ -1,116 +1,155 @@
-import type * as Gtk from "@gtkx/ffi/gtk";
-import { getConfig } from "./config.js";
-import { buildTimeoutError } from "./error-builder.js";
+import type * as Gtk from "@gtkx/gi/gtk";
 import type { WaitForOptions } from "./types.js";
+import { runWithActEnvironment } from "./act.js";
+import { getConfig } from "./config.js";
+import { timeoutError } from "./errors.js";
+
+type PollResult<T> = { status: "resolved"; value: T } | { status: "timedout"; lastError: Error | null };
+type RemovalTarget = Gtk.Widget | Gtk.Widget[] | null;
+type ElementOrCallback = Gtk.Widget | Gtk.Widget[] | (() => RemovalTarget);
 
 const DEFAULT_INTERVAL = 50;
+const ELEMENT_NOT_REMOVED = new Error("Element not yet removed");
 
-/**
- * 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 delay = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+const copyStackTrace = (target: Error, source: Error): void => {
+    const { stack } = source;
+
+    if (stack === undefined) {
+        return;
+    }
+
+    const index = stack.indexOf(source.message);
+
+    if (index === -1) {
+        target.stack = stack;
+
+        return;
+    }
+
+    target.stack = stack.slice(0, index) + target.message + stack.slice(index + source.message.length);
+};
+
+const pollUntilSuccess = async <T>(
+    callback: () => T | Promise<T>,
+    timeout: number,
+    interval: number,
+): Promise<PollResult<T>> => {
     const startTime = Date.now();
     let lastError: Error | null = null;
 
     while (Date.now() - startTime < timeout) {
         try {
-            return await callback();
+            const result = await callback();
+            await delay(0);
+
+            return { status: "resolved", value: result };
         } catch (error) {
             lastError = error as Error;
-            await new Promise((resolve) => setTimeout(resolve, interval));
+            await delay(interval);
         }
     }
 
-    const timeoutError = buildTimeoutError(timeout, lastError);
-    if (onTimeout) {
-        throw onTimeout(timeoutError);
-    }
-    throw timeoutError;
+    return { status: "timedout", lastError };
 };
 
-/** @internal */
-type ElementOrCallback = Gtk.Widget | (() => Gtk.Widget | null);
+const buildTimeoutError = (
+    timeout: number,
+    lastError: Error | null,
+    stackTraceError: Error,
+    onTimeout: ((error: Error) => Error) | undefined,
+): Error => {
+    const error = timeoutError(timeout, lastError);
+    const finalError = onTimeout ? onTimeout(error) : error;
+    copyStackTrace(finalError, stackTraceError);
 
-const getElement = (elementOrCallback: ElementOrCallback): Gtk.Widget | null => {
-    if (typeof elementOrCallback === "function") {
-        return elementOrCallback();
+    return finalError;
+};
+
+/**
+ * Repeatedly invokes a callback until it succeeds without throwing or the
+ * timeout elapses, retrying on each rejection at a fixed interval.
+ *
+ * @param callback The assertion or query to retry; its resolved value is returned.
+ * @param options Optional timeout, interval, and timeout error customization.
+ * @returns The callback's result once it succeeds.
+ */
+const waitFor = <T>(callback: () => T | Promise<T>, options?: WaitForOptions): Promise<T> => {
+    if (typeof callback !== "function") {
+        throw new TypeError("Received `callback` arg must be a function");
     }
-    return elementOrCallback;
+
+    const stackTraceError = options?.stackTraceError ?? new Error("STACK_TRACE_MESSAGE");
+
+    return Promise.resolve(
+        runWithActEnvironment(false, async () => {
+            const config = getConfig();
+            const { timeout = config.asyncUtilTimeout, interval = DEFAULT_INTERVAL, onTimeout } = options ?? {};
+            const result = await pollUntilSuccess(callback, timeout, interval);
+
+            if (result.status === "resolved") {
+                return result.value;
+            }
+
+            throw buildTimeoutError(timeout, result.lastError, stackTraceError, onTimeout);
+        }),
+    );
 };
 
-const isElementRemoved = (element: Gtk.Widget | null): boolean => {
-    if (element === null) return true;
+const getTarget = (elementOrCallback: ElementOrCallback): RemovalTarget =>
+    typeof elementOrCallback === "function" ? elementOrCallback() : elementOrCallback;
+
+const isWidgetRemoved = (widget: Gtk.Widget | null): boolean => {
+    if (widget === null) {
+        return true;
+    }
 
     try {
-        const parent = element.getParent();
-        return parent === null;
+        return widget.getRoot() === null;
     } catch {
         return true;
     }
 };
 
+const isTargetRemoved = (target: RemovalTarget): boolean => {
+    if (Array.isArray(target)) {
+        return target.every((widget) => isWidgetRemoved(widget));
+    }
+
+    return isWidgetRemoved(target);
+};
+
 /**
- * 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
+ * Waits until the given widget or widgets are detached from the tree. Rejects
+ * immediately if the target is already absent when called.
  *
- * @example
- * ```tsx
- * import { waitForElementToBeRemoved } from "@gtkx/testing";
- *
- * const loader = await screen.findByRole(Gtk.AccessibleRole.PROGRESS_BAR);
- * await waitForElementToBeRemoved(loader);
- * // Loader is now gone
- * ```
+ * @param elementOrCallback The widget, array of widgets, or a function
+ * returning them to observe for removal.
+ * @param options Optional timeout and interval settings.
  */
-export const waitForElementToBeRemoved = async (
+const waitForElementToBeRemoved = (
     elementOrCallback: ElementOrCallback,
     options?: WaitForOptions,
 ): Promise<void> => {
-    const config = getConfig();
-    const { timeout = config.asyncUtilTimeout, interval = DEFAULT_INTERVAL, onTimeout } = options ?? {};
+    const stackTraceError = new Error("STACK_TRACE_MESSAGE");
 
-    const initialElement = getElement(elementOrCallback);
-    if (initialElement === null || isElementRemoved(initialElement)) {
-        throw new Error(
-            "Element already removed: waitForElementToBeRemoved requires the element to be present initially",
+    if (isTargetRemoved(getTarget(elementOrCallback))) {
+        return Promise.reject(
+            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;
+    return waitFor(
+        () => {
+            if (!isTargetRemoved(getTarget(elementOrCallback))) {
+                throw ELEMENT_NOT_REMOVED;
+            }
+        },
+        { ...options, stackTraceError },
+    );
 };
+
+export { waitFor, waitForElementToBeRemoved };

package/src/widget-accessible-properties.ts

@@ -0,0 +1,388 @@
+import * as Gtk from "@gtkx/gi/gtk";
+import { getAccessibleMetadata } from "@gtkx/react/internal";
+import { EDITABLE_ROLES, isEditable, readEditableText } from "./editable.js";
+import { descendants } from "./traversal.js";
+
+type WidgetValue = {
+    now: number | null;
+    min: number | null;
+    max: number | null;
+    text: string | null;
+};
+
+type ValueTriplet = { now: number | null; min: number | null; max: number | null };
+
+const DEFAULT_TEXT_GETTERS = ["getLabel", "getText", "getTitle"] as const;
+
+const callStringGetter = (widget: Gtk.Widget, method: string): string | null => {
+    const fn: unknown = Reflect.get(widget, method);
+
+    if (typeof fn !== "function") {
+        return null;
+    }
+
+    const value = (fn as () => string | null).call(widget);
+
+    return value ?? null;
+};
+
+const readAccessibleString = (widget: Gtk.Widget, key: string): string | null => {
+    const value = getAccessibleMetadata(widget, key);
+
+    return typeof value === "string" ? value : null;
+};
+
+const readAccessibleNumber = (widget: Gtk.Widget, key: string): number | null => {
+    const value = getAccessibleMetadata(widget, key);
+
+    return typeof value === "number" ? value : null;
+};
+
+const readAccessibleWidgets = (widget: Gtk.Widget, key: string): Gtk.Widget[] | null => {
+    const value = getAccessibleMetadata(widget, key);
+
+    if (!Array.isArray(value)) {
+        return null;
+    }
+
+    const widgets = value.filter((item): item is Gtk.Widget => item instanceof Gtk.Widget);
+
+    return widgets.length > 0 ? widgets : null;
+};
+
+const readAccessibleBoolean = (widget: Gtk.Widget, key: string): boolean | null => {
+    const value = getAccessibleMetadata(widget, key);
+
+    return typeof value === "boolean" ? value : null;
+};
+
+const getLabelText = (widget: Gtk.Widget): string | null => {
+    if (widget instanceof Gtk.Label) {
+        return widget.getLabel();
+    }
+
+    if (widget instanceof Gtk.Inscription) {
+        return widget.getText() ?? null;
+    }
+
+    return null;
+};
+
+/**
+ * Returns a widget's own text by trying its label, text, and title getters in
+ * order, or null when none produce a value.
+ *
+ * @param widget The widget to read text from.
+ */
+const getWidgetNodeText = (widget: Gtk.Widget): string | null => {
+    for (const getter of DEFAULT_TEXT_GETTERS) {
+        const value = callStringGetter(widget, getter);
+
+        if (value) {
+            return value;
+        }
+    }
+
+    return null;
+};
+
+const stripMnemonic = (text: string): string => text.replaceAll(/_(.)/g, "$1");
+
+const namingLabelText = (widget: Gtk.Widget): string | null => {
+    const text = getLabelText(widget);
+
+    if (text === null) {
+        return null;
+    }
+
+    return widget instanceof Gtk.Label && widget.getUseUnderline() ? stripMnemonic(text) : text;
+};
+
+const isNamingLabelRole = (role: Gtk.AccessibleRole, shouldIncludePresentation: boolean): boolean =>
+    role === Gtk.AccessibleRole.LABEL ||
+    (shouldIncludePresentation && role === Gtk.AccessibleRole.PRESENTATION);
+
+const collectLabels = (widget: Gtk.Widget): string[] => {
+    const isIncludePresentation = widget.getAccessibleRole() === Gtk.AccessibleRole.MENU_ITEM;
+    const labels: string[] = [];
+
+    for (const descendant of descendants(widget)) {
+        if (!isNamingLabelRole(descendant.getAccessibleRole(), isIncludePresentation)) {
+            continue;
+        }
+
+        const labelText = namingLabelText(descendant);
+
+        if (labelText) {
+            labels.push(labelText);
+        }
+    }
+
+    return labels;
+};
+
+const getWidgetLabelText = (widget: Gtk.Widget): string | null => {
+    if (widget.getAccessibleRole() !== Gtk.AccessibleRole.LABEL) {
+        return null;
+    }
+
+    return getLabelText(widget);
+};
+
+const tabPanelTitle = (widget: Gtk.Widget): string | null => {
+    const parent = widget.getParent();
+
+    if (parent instanceof Gtk.Stack) {
+        return parent.getPage(widget).getTitle() ?? null;
+    }
+
+    return null;
+};
+
+const getWidgetAccessibleName = (widget: Gtk.Widget): string | null => {
+    const role = widget.getAccessibleRole();
+
+    if (role === Gtk.AccessibleRole.TAB_PANEL) {
+        return tabPanelTitle(widget);
+    }
+
+    const accessibleLabel = readAccessibleString(widget, "accessibleLabel");
+
+    if (accessibleLabel) {
+        return accessibleLabel;
+    }
+
+    const ownText = getWidgetNodeText(widget);
+
+    if (ownText) {
+        return ownText;
+    }
+
+    const childLabels = collectLabels(widget);
+
+    if (childLabels.length > 0) {
+        return childLabels.join(" ");
+    }
+
+    return callStringGetter(widget, "getTooltipText");
+};
+
+const getWidgetName = (widget: Gtk.Widget): string | null => {
+    return widget.getName();
+};
+
+const getWidgetPlaceholderText = (widget: Gtk.Widget): string | null => {
+    if (!EDITABLE_ROLES.has(widget.getAccessibleRole()) || !(widget instanceof Gtk.Editable)) {
+        return null;
+    }
+
+    return callStringGetter(widget, "getPlaceholderText");
+};
+
+const getWidgetDisplayValue = (widget: Gtk.Widget): string | null => {
+    if (EDITABLE_ROLES.has(widget.getAccessibleRole()) && isEditable(widget)) {
+        return readEditableText(widget);
+    }
+
+    return null;
+};
+
+const getWidgetCheckedState = (widget: Gtk.Widget): boolean | null => {
+    if (widget instanceof Gtk.CheckButton) {
+        return widget.getActive();
+    }
+
+    if (widget instanceof Gtk.Switch) {
+        return widget.getActive();
+    }
+
+    if (widget instanceof Gtk.ToggleButton && widget.getAccessibleRole() === Gtk.AccessibleRole.RADIO) {
+        return widget.getActive();
+    }
+
+    return null;
+};
+
+const getWidgetPressedState = (widget: Gtk.Widget): boolean | null => {
+    if (widget instanceof Gtk.ToggleButton) {
+        return widget.getActive();
+    }
+
+    return null;
+};
+
+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;
+};
+
+const getWidgetSelectedState = (widget: Gtk.Widget): boolean | null => {
+    if (widget instanceof Gtk.ListBoxRow) {
+        return widget.isSelected();
+    }
+
+    if (widget.getAccessibleRole() === Gtk.AccessibleRole.ROW) {
+        return (widget.getStateFlags() & Gtk.StateFlags.SELECTED) !== 0;
+    }
+
+    return null;
+};
+
+const getWidgetLevel = (widget: Gtk.Widget): number | null => {
+    return readAccessibleNumber(widget, "accessibleLevel");
+};
+
+const getWidgetInvalidState = (widget: Gtk.Widget): Gtk.AccessibleInvalidState | null => {
+    const value = readAccessibleNumber(widget, "accessibleInvalid");
+
+    return value ?? null;
+};
+
+const getWidgetErrorMessage = (widget: Gtk.Widget): Gtk.Widget[] | null =>
+    readAccessibleWidgets(widget, "accessibleErrorMessage");
+
+const getWidgetBusyState = (widget: Gtk.Widget): boolean | null => {
+    return readAccessibleBoolean(widget, "accessibleBusy");
+};
+
+const getWidgetDescription = (widget: Gtk.Widget): string | null => {
+    return readAccessibleString(widget, "accessibleDescription");
+};
+
+const adjustmentValue = (adjustment: Gtk.Adjustment): ValueTriplet => ({
+    now: adjustment.getValue(),
+    min: adjustment.getLower(),
+    max: adjustment.getUpper(),
+});
+
+const adjustmentWidgetValue = (widget: Gtk.Widget): ValueTriplet | null => {
+    if (widget instanceof Gtk.Range) {
+        return adjustmentValue(widget.getAdjustment());
+    }
+
+    if (widget instanceof Gtk.Scrollbar) {
+        return adjustmentValue(widget.getAdjustment());
+    }
+
+    if (widget instanceof Gtk.SpinButton) {
+        return adjustmentValue(widget.getAdjustment());
+    }
+
+    if (widget instanceof Gtk.ScaleButton) {
+        return adjustmentValue(widget.getAdjustment());
+    }
+
+    return null;
+};
+
+const getWidgetLiveValue = (widget: Gtk.Widget): ValueTriplet | null => {
+    const adjustmentBased = adjustmentWidgetValue(widget);
+
+    if (adjustmentBased) {
+        return adjustmentBased;
+    }
+
+    if (widget instanceof Gtk.LevelBar) {
+        return { now: widget.getValue(), min: widget.getMinValue(), max: widget.getMaxValue() };
+    }
+
+    if (widget instanceof Gtk.ProgressBar) {
+        return { now: widget.getFraction(), min: 0, max: 1 };
+    }
+
+    return null;
+};
+
+const getWidgetValue = (widget: Gtk.Widget): WidgetValue => {
+    const text = readAccessibleString(widget, "accessibleValueText");
+    const live = getWidgetLiveValue(widget);
+
+    if (live) {
+        return { ...live, text };
+    }
+
+    return {
+        now: readAccessibleNumber(widget, "accessibleValueNow"),
+        min: readAccessibleNumber(widget, "accessibleValueMin"),
+        max: readAccessibleNumber(widget, "accessibleValueMax"),
+        text,
+    };
+};
+
+const getWidgetOwnLabel = (widget: Gtk.Widget): string | null => {
+    return readAccessibleString(widget, "accessibleLabel");
+};
+
+const collectAccessibleNames = (targets: Gtk.Widget[]): string[] => {
+    const texts: string[] = [];
+
+    for (const target of targets) {
+        const text = getWidgetAccessibleName(target);
+
+        if (text !== null) {
+            texts.push(text);
+        }
+    }
+
+    return texts;
+};
+
+const getWidgetLabelledByText = (widget: Gtk.Widget): string | null => {
+    const targets = readAccessibleWidgets(widget, "accessibleLabelledBy");
+
+    if (targets === null) {
+        return null;
+    }
+
+    const texts = collectAccessibleNames(targets);
+
+    return texts.length > 0 ? texts.join(" ") : null;
+};
+
+const isInaccessible = (widget: Gtk.Widget): boolean => {
+    let current: Gtk.Widget | null = widget;
+
+    while (current) {
+        if (!current.getVisible()) {
+            return true;
+        }
+
+        if (readAccessibleBoolean(current, "accessibleHidden") === true) {
+            return true;
+        }
+
+        current = current.getParent();
+    }
+
+    return false;
+};
+
+export {
+    getWidgetNodeText,
+    getWidgetLabelText,
+    getWidgetAccessibleName,
+    getWidgetName,
+    getWidgetPlaceholderText,
+    getWidgetDisplayValue,
+    getWidgetCheckedState,
+    getWidgetPressedState,
+    getWidgetExpandedState,
+    getWidgetSelectedState,
+    getWidgetLevel,
+    getWidgetInvalidState,
+    getWidgetErrorMessage,
+    getWidgetBusyState,
+    getWidgetDescription,
+    getWidgetValue,
+    getWidgetOwnLabel,
+    getWidgetLabelledByText,
+    isInaccessible,
+    type WidgetValue,
+};

package/src/within.ts

@@ -1,31 +1,33 @@
-import type * as Gtk from "@gtkx/ffi/gtk";
-import { bindQueries } from "./bind-queries.js";
-import type { BoundQueries } from "./types.js";
+import type { BoundQueries } from "./bound-queries.js";
+import type { Container } from "./traversal.js";
+import type { BoundCustomQueries, QueryMap } from "./types.js";
+import { builtinQueries } from "./queries.js";
+
+const bindQuery =
+    <Args extends unknown[], Result>(query: (container: Container, ...args: Args) => Result, container: Container) =>
+        (...args: Args): Result =>
+            query(container, ...args);
+
+const bindCustomQueries = <Q extends QueryMap>(customQueries: Q, container: Container): BoundCustomQueries<Q> => {
+    const entries = Object.entries(customQueries).map(([key, query]) => [key, bindQuery(query, container)] as const);
+
+    return Object.fromEntries(entries) as BoundCustomQueries<Q>;
+};
 
 /**
- * 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
+ * Binds the built-in queries, and any custom queries, to a specific container
+ * so they search only within that scope.
  *
- * @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
+ * @param container The scope the returned queries operate on.
+ * @param queries Optional custom queries to bind alongside the built-in ones.
+ * @returns The queries bound to the container.
  */
-export const within = (container: Gtk.Widget): BoundQueries => bindQueries(container);
+const within = <Q extends QueryMap = Record<never, never>>(
+    container: Container,
+    queries?: Q,
+): BoundQueries & BoundCustomQueries<Q> => ({
+    ...bindCustomQueries(builtinQueries, container),
+    ...(queries ? bindCustomQueries(queries, container) : ({} as BoundCustomQueries<Q>)),
+});
+
+export { within };

package/dist/bind-queries.d.ts

@@ -1,14 +0,0 @@
-import type { Container } from "./traversal.js";
-import type { BoundQueries } from "./types.js";
-type ContainerOrGetter = Container | (() => Container);
-/**
- * Binds all query functions to a container.
- *
- * @param containerOrGetter - The container to bind queries to, or a function that returns it
- * @returns Object with all query methods bound to the container
- *
- * @internal
- */
-export declare const bindQueries: (containerOrGetter: ContainerOrGetter) => BoundQueries;
-export {};
-//# sourceMappingURL=bind-queries.d.ts.map