@gtkx/testing 1.0.0-rc.4 → 1.1.0

package/src/user-event/event-wrapper.ts

@@ -2,33 +2,38 @@ import * as Gtk from "@gtkx/gi/gtk";
 import { runInAct } from "../act.js";
 import { getConfig } from "../config.js";
 import { formatRole } from "../role-helpers.js";
+import { delay, now } from "../timers.js";
+import { getWidgetAccessibleName } from "../widget-accessible-properties.js";
+import { getTypeTag, isDefaultWidgetName } from "../widget-getters.js";
+import { isWindowAllocated, isWindowBlockedByModal } from "../window-state.js";
 
 const NOT_SENSITIVE = "it is not sensitive (the widget or one of its ancestors is disabled)";
+const NOT_ROOTED = "it is not inside a toplevel (it was removed from the widget tree, or was never added to one)";
+const WINDOW_NOT_VISIBLE = "its window is not visible (it was hidden, or it was never shown)";
 const WINDOW_NOT_ALLOCATED = "its window has not been allocated a size";
 const NOT_MAPPED = "it is not mapped (it is not shown on screen, e.g. it is hidden or on a non-visible page)";
-const WINDOW_NOT_ACTIVE = "its window never became active";
+const BLOCKED_BY_MODAL = "its window is blocked by a modal window holding the grab";
+const ACTIONABLE_HOP_MS = 1;
 
-const actionableHop = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 1));
-
-const canDisplayDeliverActivation = (window: Gtk.Window): boolean =>
-    window.getDisplay().getDefaultSeat() !== null;
-
-const findWindowActionabilityFailure = (widget: Gtk.Widget, root: Gtk.Window): string | null => {
-    if (root.getAllocatedWidth() === 0) {
-        return WINDOW_NOT_ALLOCATED;
+const findWindowActionabilityFailure = (window: Gtk.Window): string | null => {
+    if (!window.getVisible()) {
+        return WINDOW_NOT_VISIBLE;
     }
 
-    if (!widget.getMapped()) {
-        return NOT_MAPPED;
+    if (!isWindowAllocated(window)) {
+        return WINDOW_NOT_ALLOCATED;
     }
 
-    if (canDisplayDeliverActivation(root) && !root.isActive()) {
-        return WINDOW_NOT_ACTIVE;
+    if (isWindowBlockedByModal(window)) {
+        return BLOCKED_BY_MODAL;
     }
 
     return null;
 };
 
+const findRootActionabilityFailure = (root: Gtk.Root): string | null =>
+    root instanceof Gtk.Window ? findWindowActionabilityFailure(root) : null;
+
 const findActionabilityFailure = (widget: Gtk.Widget): string | null => {
     if (!widget.isSensitive()) {
         return NOT_SENSITIVE;
@@ -36,28 +41,41 @@ const findActionabilityFailure = (widget: Gtk.Widget): string | null => {
 
     const root = widget.getRoot();
 
-    if (!(root instanceof Gtk.Window) || !root.getVisible()) {
-        return null;
+    if (root === null) {
+        return NOT_ROOTED;
+    }
+
+    const rootFailure = findRootActionabilityFailure(root);
+
+    if (rootFailure !== null) {
+        return rootFailure;
     }
 
-    return findWindowActionabilityFailure(widget, root);
+    return widget.getMapped() ? null : NOT_MAPPED;
 };
 
-const describeWidget = (widget: Gtk.Widget): string => {
-    const tag = widget.constructor.name;
+const attribute = (key: string, value: string | null): string => (value === null ? "" : ` ${key}="${value}"`);
+
+const widgetNameAttribute = (widget: Gtk.Widget): string => {
     const name = widget.getName();
-    const nameAttribute = name && !name.endsWith(tag) ? ` name="${name}"` : "";
 
-    return `<${tag}${nameAttribute} role="${formatRole(widget.getAccessibleRole())}">`;
+    return attribute("name", isDefaultWidgetName(widget, name) ? null : name);
+};
+
+const describeWidget = (widget: Gtk.Widget): string => {
+    const accessibleName = attribute("accessible-name", getWidgetAccessibleName(widget));
+    const role = attribute("role", formatRole(widget.getAccessibleRole()));
+
+    return `<${getTypeTag(widget)}${accessibleName}${widgetNameAttribute(widget)}${role}>`;
 };
 
 const waitForActionable = async (widget: Gtk.Widget): Promise<void> => {
     const timeout = getConfig().actionabilityTimeout;
-    const deadline = Date.now() + timeout;
+    const deadline = now() + timeout;
     let failure = findActionabilityFailure(widget);
 
-    while (failure !== null && Date.now() < deadline) {
-        await actionableHop();
+    while (failure !== null && now() < deadline) {
+        await delay(ACTIONABLE_HOP_MS);
         failure = findActionabilityFailure(widget);
     }
 

package/src/user-event/index.ts

@@ -1,42 +1,87 @@
 import type * as Gtk from "@gtkx/gi/gtk";
+import { delay } from "../timers.js";
 import { scroll, slide } from "./adjustment.js";
 import { click, dblClick, tripleClick } from "./click.js";
 import { drag, dragAndDrop, drop, hover, longPress, rotate, swipe, unhover, zoom } from "./gesture.js";
 import { keyboard, tab } from "./keyboard.js";
 import { pointer, type PointerInput } from "./pointer.js";
 import { deselectOptions, selectOptions } from "./selection.js";
-import { createInitialState } from "./state.js";
+import { createInitialState, type UserEventState } from "./state.js";
 import { clear, copy, cut, paste, type } from "./text.js";
 
+/** Options shared by every helper on a {@link UserEvent} instance. */
+type UserEventOptions = {
+    /** Milliseconds to wait after each helper resolves; null, the default, waits not at all. */
+    delay?: number | null | undefined;
+};
+
 /**
  * The set of user interaction helpers exposed by {@link userEvent}, covering clicks, typing,
  * keyboard, pointer, gestures, selection, and scrolling.
  */
 type UserEvent = {
     /**
-     * Clicks a button, toggles a switch, and otherwise activates the widget, falling back to a click
-     * gesture on its nearest clickable ancestor when activation does nothing.
+     * Returns a fresh instance whose helpers share one keyboard and pointer state, so held modifiers
+     * and buttons carry across its calls but not across instances.
+     */
+    setup: (options?: UserEventOptions) => UserEvent;
+    /**
+     * Activates a widget that neither claims the click nor carries a click gesture of its own, and
+     * otherwise presses and releases outwards from the clicked widget through every widget carrying
+     * a click gesture, stopping at the first button or indexed child. A list box row or flow box
+     * child receives its click gesture at the clicked position, passes one on to the gestures its
+     * container carries, and is then activated, or exclusively selected when its container does not
+     * activate on a single click. The press also stops at a widget whose click GTK4 implements
+     * itself, where the gestures that widget carries of its own still take the press and the same
+     * outcome is then applied through GTK's own public action: a list, grid, or column-view row is
+     * focused and selected, and activated as well when its view activates on a single click; an
+     * expandable tree expander that is itself the clicked widget toggles its expansion; a notebook
+     * tab, clicked directly or through its label, focuses its notebook and switches to its page; a
+     * column header sorts by its column. A column-view cell and the row carrying the column headers
+     * stand in the way of the click rather than taking it, so a click on either reaches the row or
+     * the view behind it.
      */
     click: typeof click;
-    /** Emits a two-press click gesture on the widget. */
+    /**
+     * Delivers a two-press click gesture along the same path a single click takes, without trying
+     * activation first, activating a list box row or flow box child on that path and replacing its
+     * container's selection whether or not that container activates on a single click. A widget
+     * whose click GTK4 implements itself receives that outcome once per press, so a row is selected
+     * and activated by the second press, a tree expander ends back where it started, a notebook tab
+     * stays on the page the first press opened, and a column header inverts its order after sorting.
+     */
     dblClick: typeof dblClick;
-    /** Emits a three-press click gesture on the widget. */
+    /**
+     * Delivers a three-press click gesture the same way a double click is delivered, applying the
+     * same outcome to a list box row or flow box child, and applying the outcome GTK4 implements
+     * itself once per press to a row, tree expander, notebook tab, or column header.
+     */
     tripleClick: typeof tripleClick;
     /** Moves focus within the widget's root, forward by default and backward with `isShiftHeld`. */
     tab: typeof tab;
-    /** Focuses an editable widget, applies any initial selection, and inserts the text at the cursor. */
+    /**
+     * Focuses an editable widget the way clicking into it does, leaving its text unselected, applies
+     * any initial selection, and inserts the text at the cursor, deleting the text the widget has
+     * selected first, the way GTK4 does.
+     */
     type: typeof type;
-    /** Empties an editable widget's text. */
+    /** Focuses an editable widget and deletes its whole text, leaving nothing selected. */
     clear: typeof clear;
     /** Writes an editable widget's current selection to the clipboard. */
     copy: typeof copy;
     /** Writes an editable widget's current selection to the clipboard and deletes it. */
     cut: typeof cut;
-    /** Inserts the given text, or the clipboard's text, at an editable widget's cursor. */
+    /**
+     * Inserts the given text, or the clipboard's text, at an editable widget's cursor, deleting the
+     * text the widget has selected first, the way GTK4 does.
+     */
     paste: typeof paste;
-    /** Selects the items at the given positions in a list view, drop-down, combo box, or list box. */
+    /**
+     * Selects the items at those positions in a view or drop-down, or selects the indexed children of
+     * a list box or flow box through their container, without activating them.
+     */
     selectOptions: typeof selectOptions;
-    /** Deselects the items at the given positions in a list view or list box. */
+    /** Unselects the items at those positions, leaving list box and flow box children unactivated. */
     deselectOptions: typeof deselectOptions;
     /** Emits a motion `enter` on the widget, adding a motion controller when it has none. */
     hover: typeof hover;
@@ -60,49 +105,94 @@ type UserEvent = {
     slide: typeof slide;
     /** Adds the delta to the adjustments of the widget itself, or of its nearest scrollable ancestor. */
     scroll: typeof scroll;
-    /** Sends a key sequence, dispatching matching shortcuts and tracking held modifiers across calls. */
+    /**
+     * Sends a key sequence along the chain GTK4 propagates a key event through: the application's
+     * accelerators first, then the capture-phase controllers from the root down to the event widget,
+     * the event widget's target-phase controllers, and the bubble-phase controllers from it back up
+     * to the root, so a key controller or shortcut controller a container or window above the widget
+     * carries receives the key too, each in the phase it declares. The event widget is the editable
+     * delegate GTK4 focuses when the widget has one, the `Gtk.Text` inside a `Gtk.Entry` for
+     * instance, so the delegate stands ahead of the widget in the chain. A shortcut controller whose
+     * scope is not local runs where it registered instead, the root for a global one and the nearest
+     * `Gtk.ShortcutManager` for a managed one, so it fires wherever focus sits inside that subtree
+     * and never at its own widget, while a shortcut whose widget is insensitive or unmapped stays
+     * inert wherever it sits. The first controller that handles a press ends the chain, and a
+     * `Gdk.KEY_Return` press none of them handled reaches an editable widget's activate handler.
+     * Built-in key bindings take part, since GTK4 carries them on a shortcut controller: a
+     * `Gtk.Text`'s arrow keys or a `Gtk.TextView`'s undo can consume a press before an ancestor
+     * sees it. Key controllers GTK4 attaches itself are the exception, since they read a GDK event
+     * that off-screen synthesis cannot produce, so only the key controllers the tree connected a
+     * `key-pressed` or `key-released` handler to take part. Held modifiers carry across calls.
+     */
     keyboard: (widget: Gtk.Widget, input: string) => Promise<void>;
-    /** Applies a pointer token, tracking whether the left button is held across calls. */
+    /**
+     * Applies a pointer token to the click gestures the widget already carries, tracking whether the
+     * left button is held across calls. On a widget whose click GTK4 implements itself, the release
+     * also applies GTK's own outcome, the way {@link UserEvent.click} does, and a column-view cell
+     * or the row carrying the column headers passes the token to the row or view behind it.
+     */
     pointer: (widget: Gtk.Widget, input: PointerInput) => Promise<void>;
 };
 
-const state = createInitialState();
-
 /**
  * High-level helpers that drive widgets by dispatching the same events and gestures GTK4 delivers
- * when someone clicks, types, or drags.
+ * when someone clicks, types, or drags. Call `setup` for an instance with its own keyboard and
+ * pointer state.
  */
 const userEvent: UserEvent = {
-    click,
-    dblClick,
-    tripleClick,
-    tab,
-    type,
-    clear,
-    copy,
-    cut,
-    paste,
-    selectOptions,
-    deselectOptions,
-    hover,
-    unhover,
-    rotate,
-    zoom,
-    swipe,
-    longPress,
-    drag,
-    drop,
-    dragAndDrop,
-    slide,
-    scroll,
-    keyboard: (widget: Gtk.Widget, input: string): Promise<void> => keyboard(state, widget, input),
-    pointer: (widget: Gtk.Widget, input: PointerInput): Promise<void> => pointer(state, widget, input),
+    ...createInstance(createInitialState(), {}),
+    setup: (options?: UserEventOptions): UserEvent => createInstance(createInitialState(), options ?? {}),
+};
+
+const settle = (ms: number | null | undefined): Promise<void> => {
+    if (ms === null || ms === undefined) {
+        return Promise.resolve();
+    }
+
+    return delay(ms);
 };
 
+function createInstance(state: UserEventState, options: UserEventOptions): UserEvent {
+    const after =
+        <Args extends unknown[]>(helper: (...args: Args) => Promise<void>) =>
+            async (...args: Args): Promise<void> => {
+                await helper(...args);
+                await settle(options.delay);
+            };
+
+    return {
+        setup: (overrides?: UserEventOptions): UserEvent => createInstance(state, { ...options, ...overrides }),
+        click: after(click),
+        dblClick: after(dblClick),
+        tripleClick: after(tripleClick),
+        tab: after(tab),
+        type: after(type),
+        clear: after(clear),
+        copy: after(copy),
+        cut: after(cut),
+        paste: after(paste),
+        selectOptions: after(selectOptions),
+        deselectOptions: after(deselectOptions),
+        hover: after(hover),
+        unhover: after(unhover),
+        rotate: after(rotate),
+        zoom: after(zoom),
+        swipe: after(swipe),
+        longPress: after(longPress),
+        drag: after(drag),
+        drop: after(drop),
+        dragAndDrop: after(dragAndDrop),
+        slide: after(slide),
+        scroll: after(scroll),
+        keyboard: after((widget: Gtk.Widget, input: string): Promise<void> => keyboard(state, widget, input)),
+        pointer: after((widget: Gtk.Widget, input: PointerInput): Promise<void> => pointer(state, widget, input)),
+    };
+}
+
 export type { ScrollDelta } from "./adjustment.js";
 export type { DragOffset, DragOptions, DropContent, DropOptions } from "./gesture.js";
 export type { TabOptions } from "./keyboard.js";
 export type { PointerInput } from "./pointer.js";
 export type { TypeOptions } from "./text.js";
 export { resetClipboard } from "./text.js";
-export { userEvent, type UserEvent };
+export { userEvent, type UserEvent, type UserEventOptions };

package/src/user-event/indexed-children.ts

@@ -0,0 +1,75 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import { callBooleanGetter, getCallableMethod, hasWidgetMethod } from "../widget-getters.js";
+
+const CHILD_AT_INDEX_GETTERS = ["getRowAtIndex", "getChildAtIndex"];
+const CHILD_SELECTORS = ["selectRow", "selectChild"];
+const CHILD_DESELECTORS = ["unselectRow", "unselectChild"];
+const SELECTED_CHILD_GETTERS = ["getSelectedRows", "getSelectedChildren"];
+const SELECTED_PROBE = "isSelected";
+
+const hasIndexedChildren = (widget: Gtk.Widget): boolean =>
+    CHILD_AT_INDEX_GETTERS.some((getter) => hasWidgetMethod(widget, getter));
+
+const getChildAtIndex = (widget: Gtk.Widget, index: number): Gtk.Widget | null => {
+    for (const getter of CHILD_AT_INDEX_GETTERS) {
+        const fn = getCallableMethod<[number], Gtk.Widget | null>(widget, getter);
+
+        if (fn) {
+            return fn(index) ?? null;
+        }
+    }
+
+    return null;
+};
+
+const applyChildMethod = (container: Gtk.Widget, names: string[], child: Gtk.Widget): void => {
+    for (const name of names) {
+        const fn = getCallableMethod<[Gtk.Widget], unknown>(container, name);
+
+        if (fn) {
+            fn(child);
+
+            return;
+        }
+    }
+};
+
+const selectContainerChild = (container: Gtk.Widget, child: Gtk.Widget): void => {
+    applyChildMethod(container, CHILD_SELECTORS, child);
+};
+
+const unselectContainerChild = (container: Gtk.Widget, child: Gtk.Widget): void => {
+    applyChildMethod(container, CHILD_DESELECTORS, child);
+};
+
+const isChildSelected = (child: Gtk.Widget): boolean => callBooleanGetter(child, SELECTED_PROBE) ?? false;
+
+const getSelectedChildren = (container: Gtk.Widget): Gtk.Widget[] => {
+    for (const getter of SELECTED_CHILD_GETTERS) {
+        const fn = getCallableMethod<[], Gtk.Widget[]>(container, getter);
+
+        if (fn) {
+            return fn();
+        }
+    }
+
+    return [];
+};
+
+const unselectOtherChildren = (container: Gtk.Widget, child: Gtk.Widget): void => {
+    for (const selected of getSelectedChildren(container)) {
+        if (selected !== child) {
+            unselectContainerChild(container, selected);
+        }
+    }
+};
+
+export {
+    getChildAtIndex,
+    hasIndexedChildren,
+    isChildSelected,
+    SELECTED_PROBE,
+    selectContainerChild,
+    unselectContainerChild,
+    unselectOtherChildren,
+};