@gtkx/testing 1.0.0-rc.2 → 1.0.0-rc.4

package/src/user-event/pointer.ts

@@ -20,21 +20,21 @@ const applyPointerInput = (widget: Gtk.Widget, state: UserEventState, input: Poi
     if (CLICK_INPUTS.has(input)) {
         emitPress(widget, controllers, 1);
         emitRelease(widget, controllers, 1);
-        state.mouseLeftDown = false;
+        state.isMouseLeftDown = false;
 
         return;
     }
 
-    if (PRESS_INPUTS.has(input) && !state.mouseLeftDown) {
+    if (PRESS_INPUTS.has(input) && !state.isMouseLeftDown) {
         emitPress(widget, controllers, 1);
-        state.mouseLeftDown = true;
+        state.isMouseLeftDown = true;
 
         return;
     }
 
-    if (RELEASE_INPUTS.has(input) && state.mouseLeftDown) {
+    if (RELEASE_INPUTS.has(input) && state.isMouseLeftDown) {
         emitRelease(widget, controllers, 1);
-        state.mouseLeftDown = false;
+        state.isMouseLeftDown = false;
     }
 };
 

package/src/user-event/selection.ts

@@ -134,6 +134,14 @@ const runSelectionEvent = (
         byRole(widget, valueArray);
     });
 
+/**
+ * Selects the items at the given positions through a list, grid, or column view's selection model,
+ * by setting the active item of a drop-down or combo box, or by selecting list box rows. An empty
+ * array clears a view's selection.
+ *
+ * @throws When a view has no selection model, when a combo box is given more than one position, or
+ * when the widget is neither a view nor something with the combo box or list role.
+ */
 const selectOptions = (widget: Gtk.Widget, values: number | number[]): Promise<void> =>
     runSelectionEvent(widget, values, selectInListView, selectByRole);
 
@@ -153,6 +161,13 @@ const deselectByRole = (widget: Gtk.Widget, valueArray: number[]): void => {
     applyListBoxRows(widget, valueArray, unselectListBoxRow);
 };
 
+/**
+ * Unselects the items at the given positions in a list, grid, or column view, or the rows at those
+ * indices in a Gtk.ListBox.
+ *
+ * @throws When a view has no selection model, or when the widget is neither one of those views nor
+ * a Gtk.ListBox.
+ */
 const deselectOptions = (widget: Gtk.Widget, values: number | number[]): Promise<void> =>
     runSelectionEvent(widget, values, deselectInListView, deselectByRole);
 

package/src/user-event/state.ts

@@ -1,8 +1,8 @@
 type UserEventState = {
     modifierState: number;
-    mouseLeftDown: boolean;
+    isMouseLeftDown: boolean;
 };
 
-const createInitialState = (): UserEventState => ({ modifierState: 0, mouseLeftDown: false });
+const createInitialState = (): UserEventState => ({ modifierState: 0, isMouseLeftDown: false });
 
 export { createInitialState, type UserEventState };

package/src/user-event/text.ts

@@ -5,10 +5,10 @@ import { EDITABLE_ROLES, type EditableTarget, getEditableDelegate, isEditable }
 import { formatRoleList } from "../role-helpers.js";
 import { wrapEvent } from "./event-wrapper.js";
 
-/** Options for {@link type}. */
+/** Options for `userEvent.type`. */
 type TypeOptions = {
-    /** Do not focus the widget before typing. */
-    skipClick?: boolean | undefined;
+    /** Focus the widget before typing; defaults to true. */
+    shouldFocus?: boolean | undefined;
     /** Select from this offset before typing, replacing the selected range with the typed text. */
     initialSelectionStart?: number | undefined;
     /** End offset of the initial selection (defaults to the start offset). */
@@ -131,9 +131,15 @@ const runEditableEvent = (
         action(widget);
     });
 
+/**
+ * Focuses the widget unless `shouldFocus` is false, applies any initial selection, and inserts the text
+ * at the cursor.
+ *
+ * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView.
+ */
 const type = (widget: Gtk.Widget, text: string, options?: TypeOptions): Promise<void> =>
     runEditableEvent(widget, "Cannot type into element", (editable) => {
-        if (!options?.skipClick) {
+        if (options?.shouldFocus ?? true) {
             editable.grabFocus();
         }
 
@@ -141,22 +147,43 @@ const type = (widget: Gtk.Widget, text: string, options?: TypeOptions): Promise<
         insertEditableText(editable, text);
     });
 
+/**
+ * Replaces an editable widget's text with the empty string.
+ *
+ * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView.
+ */
 const clear = (widget: Gtk.Widget): Promise<void> =>
     runEditableEvent(widget, "Cannot clear element", (editable) => {
         setEditableText(editable, "");
     });
 
+/**
+ * Writes an editable widget's selected text to its clipboard, or the empty string when nothing is selected.
+ *
+ * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView.
+ */
 const copy = (widget: Gtk.Widget): Promise<void> =>
     runEditableEvent(widget, "Cannot copy", (editable) => {
         writeClipboardText(editable, readSelection(editable));
     });
 
+/**
+ * Writes an editable widget's selected text to its clipboard, then deletes that selection.
+ *
+ * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView.
+ */
 const cut = (widget: Gtk.Widget): Promise<void> =>
     runEditableEvent(widget, "Cannot cut", (editable) => {
         writeClipboardText(editable, readSelection(editable));
         deleteSelection(editable);
     });
 
+/**
+ * Inserts the given text at an editable widget's cursor, reading the clipboard instead when no text
+ * is given.
+ *
+ * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView.
+ */
 const paste = async (widget: Gtk.Widget, text?: string): Promise<void> => {
     if (!isEditable(widget)) {
         throw new Error(`Cannot paste: ${EDITABLE_REQUIRED}`);

package/src/wait-for.ts

@@ -5,7 +5,9 @@ import { getConfig } from "./config.js";
 import { timeoutError } from "./errors.js";
 
 type PollResult<T> = { status: "resolved"; value: T } | { status: "timedout"; lastError: Error | null };
+/** Widgets watched for removal; null counts as already removed. */
 type RemovalTarget = Gtk.Widget | Gtk.Widget[] | null;
+/** The widgets to watch for removal, or a function re-read on every poll to locate them. */
 type ElementOrCallback = Gtk.Widget | Gtk.Widget[] | (() => RemovalTarget);
 
 const DEFAULT_INTERVAL = 50;

package/src/widget-accessible-properties.ts

@@ -11,9 +11,18 @@ type WidgetValue = {
 };
 
 type ValueTriplet = { now: number | null; min: number | null; max: number | null };
+type CheckedState = "checked" | "unchecked" | "mixed";
 
 const DEFAULT_TEXT_GETTERS = ["getLabel", "getText", "getTitle"] as const;
 
+const SELECTABLE_ROLES: Set<Gtk.AccessibleRole> = new Set<Gtk.AccessibleRole>([
+    Gtk.AccessibleRole.ROW,
+    Gtk.AccessibleRole.LIST_ITEM,
+    Gtk.AccessibleRole.GRID_CELL,
+    Gtk.AccessibleRole.OPTION,
+    Gtk.AccessibleRole.TREE_ITEM,
+]);
+
 const callStringGetter = (widget: Gtk.Widget, method: string): string | null => {
     const fn: unknown = Reflect.get(widget, method);
 
@@ -129,6 +138,55 @@ const getWidgetLabelText = (widget: Gtk.Widget): string | null => {
     return getLabelText(widget);
 };
 
+const getChildren = function* (widget: Gtk.Widget): Generator<Gtk.Widget> {
+    let child = widget.getFirstChild();
+
+    while (child) {
+        yield child;
+        child = child.getNextSibling();
+    }
+};
+
+const textContentParts = (widget: Gtk.Widget): string[] => {
+    const own = getWidgetNodeText(widget);
+
+    if (own !== null) {
+        return [own];
+    }
+
+    return [...getChildren(widget)].flatMap((child) => textContentParts(child));
+};
+
+/**
+ * Returns a widget's own text, or the space-joined text of its descendants when it has none of its
+ * own, or null when neither produces a value.
+ *
+ * @param widget The widget whose subtree is read.
+ */
+const getWidgetTextContent = (widget: Gtk.Widget): string | null => {
+    const parts = textContentParts(widget);
+
+    return parts.length > 0 ? parts.join(" ") : null;
+};
+
+const isComboBoxFaceCandidate = (widget: Gtk.Widget): boolean =>
+    !(widget instanceof Gtk.Popover) && widget.getChildVisible();
+
+const comboBoxChildFaceText = (child: Gtk.Widget): string | null =>
+    isComboBoxFaceCandidate(child) ? getWidgetLabelText(child) ?? comboBoxFaceText(child) : null;
+
+const comboBoxFaceText = (widget: Gtk.Widget): string | null => {
+    for (const child of getChildren(widget)) {
+        const text = comboBoxChildFaceText(child);
+
+        if (text !== null) {
+            return text;
+        }
+    }
+
+    return null;
+};
+
 const tabPanelTitle = (widget: Gtk.Widget): string | null => {
     const parent = widget.getParent();
 
@@ -146,6 +204,12 @@ const getWidgetAccessibleName = (widget: Gtk.Widget): string | null => {
         return tabPanelTitle(widget);
     }
 
+    const labelledByText = getWidgetLabelledByText(widget);
+
+    if (labelledByText) {
+        return labelledByText;
+    }
+
     const accessibleLabel = readAccessibleString(widget, "accessibleLabel");
 
     if (accessibleLabel) {
@@ -176,7 +240,15 @@ const getWidgetPlaceholderText = (widget: Gtk.Widget): string | null => {
         return null;
     }
 
-    return callStringGetter(widget, "getPlaceholderText");
+    const fromGetter = callStringGetter(widget, "getPlaceholderText");
+
+    if (fromGetter !== null) {
+        return fromGetter;
+    }
+
+    const fromAccessor: unknown = Reflect.get(widget, "placeholderText");
+
+    return typeof fromAccessor === "string" && fromAccessor !== "" ? fromAccessor : null;
 };
 
 const getWidgetDisplayValue = (widget: Gtk.Widget): string | null => {
@@ -184,25 +256,89 @@ const getWidgetDisplayValue = (widget: Gtk.Widget): string | null => {
         return readEditableText(widget);
     }
 
+    if (widget.getAccessibleRole() === Gtk.AccessibleRole.COMBO_BOX) {
+        return comboBoxFaceText(widget);
+    }
+
     return null;
 };
 
-const getWidgetCheckedState = (widget: Gtk.Widget): boolean | null => {
-    if (widget instanceof Gtk.CheckButton) {
-        return widget.getActive();
+const hasDisplayValue = (widget: Gtk.Widget): boolean => {
+    const role = widget.getAccessibleRole();
+
+    return (EDITABLE_ROLES.has(role) && isEditable(widget)) || role === Gtk.AccessibleRole.COMBO_BOX;
+};
+
+const isWidgetDisabled = (widget: Gtk.Widget): boolean => !widget.isSensitive();
+
+const hasZeroOpacityAncestor = (widget: Gtk.Widget): boolean => {
+    let current: Gtk.Widget | null = widget;
+
+    while (current) {
+        if (current.getOpacity() === 0) {
+            return true;
+        }
+
+        current = current.getParent();
     }
 
-    if (widget instanceof Gtk.Switch) {
-        return widget.getActive();
+    return false;
+};
+
+const isWidgetVisible = (widget: Gtk.Widget): boolean => widget.isVisible() && !hasZeroOpacityAncestor(widget);
+
+const getWidgetRequiredState = (widget: Gtk.Widget): boolean | null =>
+    readAccessibleBoolean(widget, "accessibleRequired");
+
+const readTextViewSelection = (view: Gtk.TextView): string | null => {
+    const buffer = view.getBuffer();
+    const [hasSelection, start, end] = buffer.getSelectionBounds();
+
+    return hasSelection ? buffer.getText(start, end, true) : null;
+};
+
+const readEditableSelection = (editable: Gtk.Editable): string | null => {
+    const [hasSelection, start, end] = editable.getSelectionBounds();
+
+    return hasSelection ? editable.getChars(start, end) : null;
+};
+
+const getWidgetSelection = (widget: Gtk.Widget): string | null => {
+    if (widget instanceof Gtk.TextView) {
+        return readTextViewSelection(widget);
     }
 
-    if (widget instanceof Gtk.ToggleButton && widget.getAccessibleRole() === Gtk.AccessibleRole.RADIO) {
-        return widget.getActive();
+    if (widget instanceof Gtk.Editable) {
+        return readEditableSelection(widget);
     }
 
     return null;
 };
 
+const checkedFromActive = (isActive: boolean): CheckedState => (isActive ? "checked" : "unchecked");
+
+const isCheckableToggle = (widget: Gtk.Widget): boolean =>
+    widget instanceof Gtk.Switch ||
+    (widget instanceof Gtk.ToggleButton && widget.getAccessibleRole() === Gtk.AccessibleRole.RADIO);
+
+const getWidgetCheckedState = (widget: Gtk.Widget): CheckedState | null => {
+    if (widget instanceof Gtk.CheckButton) {
+        return widget.getInconsistent() ? "mixed" : checkedFromActive(widget.getActive());
+    }
+
+    if (isCheckableToggle(widget)) {
+        return checkedFromActive(Reflect.get(widget, "active") === true);
+    }
+
+    return null;
+};
+
+const isWidgetChecked = (widget: Gtk.Widget): boolean | null => {
+    const state = getWidgetCheckedState(widget);
+
+    return state === null || state === "mixed" ? null : state === "checked";
+};
+
 const getWidgetPressedState = (widget: Gtk.Widget): boolean | null => {
     if (widget instanceof Gtk.ToggleButton) {
         return widget.getActive();
@@ -224,11 +360,11 @@ const getWidgetExpandedState = (widget: Gtk.Widget): boolean | null => {
 };
 
 const getWidgetSelectedState = (widget: Gtk.Widget): boolean | null => {
-    if (widget instanceof Gtk.ListBoxRow) {
+    if (widget instanceof Gtk.ListBoxRow || widget instanceof Gtk.FlowBoxChild) {
         return widget.isSelected();
     }
 
-    if (widget.getAccessibleRole() === Gtk.AccessibleRole.ROW) {
+    if (SELECTABLE_ROLES.has(widget.getAccessibleRole())) {
         return (widget.getStateFlags() & Gtk.StateFlags.SELECTED) !== 0;
     }
 
@@ -239,12 +375,23 @@ const getWidgetLevel = (widget: Gtk.Widget): number | null => {
     return readAccessibleNumber(widget, "accessibleLevel");
 };
 
+/**
+ * Returns the accessible invalid state declared on a widget, or null when it declares none.
+ *
+ * @param widget The widget to read the state from.
+ */
 const getWidgetInvalidState = (widget: Gtk.Widget): Gtk.AccessibleInvalidState | null => {
     const value = readAccessibleNumber(widget, "accessibleInvalid");
 
     return value ?? null;
 };
 
+/**
+ * Returns the widgets a widget's accessible error-message relation points at, or null when it
+ * declares none.
+ *
+ * @param widget The widget to read the relation from.
+ */
 const getWidgetErrorMessage = (widget: Gtk.Widget): Gtk.Widget[] | null =>
     readAccessibleWidgets(widget, "accessibleErrorMessage");
 
@@ -346,6 +493,28 @@ const getWidgetLabelledByText = (widget: Gtk.Widget): string | null => {
     return texts.length > 0 ? texts.join(" ") : null;
 };
 
+const isTooltipUsedAsName = (widget: Gtk.Widget): boolean =>
+    readAccessibleString(widget, "accessibleLabel") === null &&
+    getWidgetNodeText(widget) === null &&
+    collectLabels(widget).length === 0;
+
+const getWidgetDescribedByText = (widget: Gtk.Widget): string | null => {
+    const targets = readAccessibleWidgets(widget, "accessibleDescribedBy");
+    const texts = targets === null ? [] : collectAccessibleNames(targets);
+
+    if (texts.length > 0) {
+        return texts.join(" ");
+    }
+
+    const description = readAccessibleString(widget, "accessibleDescription");
+
+    if (description !== null) {
+        return description;
+    }
+
+    return isTooltipUsedAsName(widget) ? null : callStringGetter(widget, "getTooltipText");
+};
+
 const isInaccessible = (widget: Gtk.Widget): boolean => {
     let current: Gtk.Widget | null = widget;
 
@@ -366,12 +535,20 @@ const isInaccessible = (widget: Gtk.Widget): boolean => {
 
 export {
     getWidgetNodeText,
+    getWidgetTextContent,
     getWidgetLabelText,
     getWidgetAccessibleName,
     getWidgetName,
     getWidgetPlaceholderText,
     getWidgetDisplayValue,
+    hasDisplayValue,
+    isWidgetDisabled,
+    isWidgetVisible,
+    getWidgetRequiredState,
+    getWidgetSelection,
+    getWidgetDescribedByText,
     getWidgetCheckedState,
+    isWidgetChecked,
     getWidgetPressedState,
     getWidgetExpandedState,
     getWidgetSelectedState,
@@ -384,5 +561,6 @@ export {
     getWidgetOwnLabel,
     getWidgetLabelledByText,
     isInaccessible,
+    type CheckedState,
     type WidgetValue,
 };

package/src/within.ts

@@ -26,7 +26,7 @@ const within = <Q extends QueryMap = Record<never, never>>(
     container: Container,
     queries?: Q,
 ): BoundQueries & BoundCustomQueries<Q> => ({
-    ...bindCustomQueries(builtinQueries, container),
+    ...(bindCustomQueries(builtinQueries, container) as BoundQueries),
     ...(queries ? bindCustomQueries(queries, container) : ({} as BoundCustomQueries<Q>)),
 });