@gtkx/testing 1.5.0 → 2.0.0-beta.1

package/src/user-event/index.ts

@@ -15,73 +15,31 @@ type UserEventOptions = {
     delay?: number | null | undefined;
 };
 
-/**
- * The set of user interaction helpers exposed by {@link userEvent}, covering clicks, typing,
- * keyboard, pointer, gestures, selection, and scrolling.
- */
+/** User interactions exposed by {@link userEvent}. */
 type UserEvent = {
-    /**
-     * 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.
-     */
+    /** Creates an instance with shared keyboard and pointer state. */
     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.
-     */
+    /** Activates or presses and releases a widget. */
     click: typeof click;
-    /**
-     * 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.
-     */
+    /** Delivers a double-click gesture. */
     dblClick: typeof dblClick;
-    /**
-     * 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.
-     */
+    /** Delivers a triple-click gesture. */
     tripleClick: typeof tripleClick;
-    /** Moves focus within the widget's root, forward by default and backward with `isShiftHeld`. */
+    /** Moves focus forward or backward within the root. */
     tab: typeof tab;
-    /**
-     * 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.
-     */
+    /** Types into an editable widget. */
     type: typeof type;
-    /** Focuses an editable widget and deletes its whole text, leaving nothing selected. */
+    /** Deletes all text from an editable widget. */
     clear: typeof clear;
-    /** Writes an editable widget's current selection to the clipboard. */
+    /** Copies the current selection. */
     copy: typeof copy;
-    /** Writes an editable widget's current selection to the clipboard and deletes it. */
+    /** Cuts the current selection. */
     cut: typeof cut;
-    /**
-     * 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.
-     */
+    /** Pastes text or clipboard contents. */
     paste: typeof paste;
-    /**
-     * 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.
-     */
+    /** Selects positions without activating them. */
     selectOptions: typeof selectOptions;
-    /** Unselects the items at those positions, leaving list box and flow box children unactivated. */
+    /** Unselects positions without activating them. */
     deselectOptions: typeof deselectOptions;
     /** Emits a motion `enter` on the widget, adding a motion controller when it has none. */
     hover: typeof hover;
@@ -105,40 +63,13 @@ 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 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.
-     */
+    /** Sends a key sequence through GTK's propagation chain. */
     keyboard: (widget: Gtk.Widget, input: string) => Promise<void>;
-    /**
-     * 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.
-     */
+    /** Applies a pointer token while preserving held-button state. */
     pointer: (widget: Gtk.Widget, input: PointerInput) => Promise<void>;
 };
 
-/**
- * High-level helpers that drive widgets by dispatching the same events and gestures GTK4 delivers
- * when someone clicks, types, or drags. Call `setup` for an instance with its own keyboard and
- * pointer state.
- */
+/** User interactions that dispatch GTK events and gestures. */
 const userEvent: UserEvent = {
     ...createInstance(createInitialState(), {}),
     setup: (options?: UserEventOptions): UserEvent => createInstance(createInitialState(), options ?? {}),

package/src/user-event/keyboard.ts

@@ -65,7 +65,7 @@ const MODIFIER_KEYVAL_TO_MASK: Record<number, number> = {
     [Gdk.KEY_Meta_R]: Gdk.ModifierType.META_MASK,
 };
 
-/** Moves focus within the widget's root, forward by default and backward when `isShiftHeld` is set. */
+/** Moves focus within the widget's root. */
 const tab = (widget: Gtk.Widget, options?: TabOptions): Promise<void> =>
     wrapEvent(widget, () => {
         const direction = options?.isShiftHeld ? Gtk.DirectionType.TAB_BACKWARD : Gtk.DirectionType.TAB_FORWARD;

package/src/user-event/selection.ts

@@ -19,9 +19,7 @@ const SELECTABLE_ROLES: Set<Gtk.AccessibleRole> = new Set([
     Gtk.AccessibleRole.LIST,
 ]);
 
-const isSelectable = (widget: Gtk.Widget): boolean => {
-    return SELECTABLE_ROLES.has(widget.getAccessibleRole());
-};
+const isSelectable = (widget: Gtk.Widget): boolean => SELECTABLE_ROLES.has(widget.getAccessibleRole());
 
 const selectListViewItems = (
     selectionModel: Gtk.SelectionModel,
@@ -155,16 +153,7 @@ 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 selected position of a widget with the COMBO_BOX role, or by selecting the indexed
- * children of a list box or flow box through their container. An empty array clears a view's
- * selection. The children are never activated, so no row-activated handler runs.
- *
- * @throws When a view has no selection model, when a COMBO_BOX-role widget is given more than one
- * position or exposes no `setSelected`, or when the widget's role is none of COMBO_BOX, GRID, or
- * LIST.
- */
+/** Selects positions without activating them. */
 const selectOptions = (widget: Gtk.Widget, values: number | number[]): Promise<void> =>
     runSelectionEvent(widget, values, selectInListView, selectByRole);
 
@@ -186,14 +175,7 @@ const deselectByRole = (widget: Gtk.Widget, valueArray: number[]): void => {
     applyIndexedChildren(widget, valueArray, unselectChildRow);
 };
 
-/**
- * Unselects the items at the given positions in a list, grid, or column view, or unselects the
- * indexed children of a list box or flow box through their container. A child that is not selected
- * is left alone, and no child is activated.
- *
- * @throws When a view has no selection model, when the widget's role is none of COMBO_BOX, GRID, or
- * LIST, or when it exposes no indexed children.
- */
+/** Unselects positions without activating them. */
 const deselectOptions = (widget: Gtk.Widget, values: number | number[]): Promise<void> =>
     runSelectionEvent(widget, values, deselectInListView, deselectByRole);
 

package/src/user-event/text.ts

@@ -198,15 +198,7 @@ const runEditableEvent = (
         action(widget);
     });
 
-/**
- * Focuses the widget unless `shouldFocus` is false, applies any initial selection, and inserts the
- * text at the cursor, deleting the text the widget has selected first, the way typing over a
- * selection does in GTK4. Focusing works the way clicking into the widget does, leaving its text
- * unselected: a `Gtk.Editable` takes its caret to the end of its text, a `Gtk.TextView` keeps the
- * caret where it stands, and the replaced text stays on the widget's undo stack either way.
- *
- * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView.
- */
+/** Types into an editable widget. */
 const type = (widget: Gtk.Widget, text: string, options?: TypeOptions): Promise<void> =>
     runEditableEvent(widget, "Cannot type into element", (editable) => {
         if (options?.shouldFocus ?? true) {
@@ -286,45 +278,24 @@ const clearEditable = (editable: EditableTarget): void => {
     }
 };
 
-/**
- * Focuses an editable widget and deletes its whole text through the widget's own editing API, so the
- * deletion emits the signals an edit made by hand emits. Text a tag protects is detected before the
- * deletion runs, leaving such a widget untouched. A widget that writes a new value back in response
- * to the deletion, as an input mask does, is cleared successfully and keeps whatever it wrote.
- *
- * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView, when it refuses edits, when
- * a tag protects part of its text, or when a handler blocks the deletion.
- */
+/** Deletes all text from an editable widget. */
 const clear = (widget: Gtk.Widget): Promise<void> =>
     runEditableEvent(widget, "Cannot clear element", clearEditable);
 
-/**
- * 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.
- */
+/** Copies the current selection. */
 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.
- */
+/** Cuts the current selection. */
 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, and deleting the text the widget has selected first, the way a paste does in GTK4.
- *
- * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView.
- */
+/** Pastes text or clipboard contents. */
 const paste = async (widget: Gtk.Widget, text?: string): Promise<void> => {
     if (!isEditable(widget)) {
         throw new Error(`Cannot paste: ${EDITABLE_REQUIRED}`);

package/src/widget-accessible-properties.ts

@@ -4,10 +4,10 @@ import {
     readAccessibleBooleanProperty,
     readAccessibleFlag,
     readAccessibleInt,
+    readAccessibleNumber,
     readAccessibleRelation,
     readAccessibleState,
-    readAccessibleNumber as readNativeNumber,
-    readAccessibleString as readNativeString,
+    readAccessibleString,
 } from "./accessible-native.js";
 import { EDITABLE_ROLES, isEditable, readEditableText } from "./editable.js";
 import { isNameFromAuthor, isNameProhibited } from "./role-naming.js";
@@ -45,12 +45,6 @@ const VALUE_PROPERTIES: Record<WidgetValueField, Gtk.AccessibleProperty> = {
     max: Gtk.AccessibleProperty.VALUE_MAX,
 };
 
-const readAccessibleString = (widget: Gtk.Widget, property: Gtk.AccessibleProperty): string | null =>
-    readNativeString(widget, property);
-
-const readAccessibleNumber = (widget: Gtk.Widget, property: Gtk.AccessibleProperty): number | null =>
-    readNativeNumber(widget, property);
-
 const readAccessibleWidgets = (widget: Gtk.Widget, relation: Gtk.AccessibleRelation): Gtk.Widget[] | null => {
     const targets = readAccessibleRelation(widget, relation, relationCandidates(widget));
     const widgets = targets.filter((target): target is Gtk.Widget => target instanceof Gtk.Widget);
@@ -215,9 +209,7 @@ const getWidgetAccessibleName = (widget: Gtk.Widget): string | null => {
     return nameFromContent(widget) ?? callStringGetter(widget, "getTooltipText");
 };
 
-const getWidgetName = (widget: Gtk.Widget): string | null => {
-    return widget.getName();
-};
+const getWidgetName = (widget: Gtk.Widget): string | null => widget.getName();
 
 const nonEmptyText = (text: string | null): string | null => (text === null || text === "" ? null : text);
 
@@ -318,8 +310,6 @@ const readBoundedSelection = (widget: Gtk.Widget): string | null => {
 const getWidgetSelection = (widget: Gtk.Widget): string | null =>
     widget instanceof Gtk.TextView ? readTextViewSelection(widget) : readBoundedSelection(widget);
 
-const checkedFromActive = (isActive: boolean): CheckedState => (isActive ? "checked" : "unchecked");
-
 const isRadioToggle = (widget: Gtk.Widget): widget is Gtk.ToggleButton =>
     widget instanceof Gtk.ToggleButton && widget.getAccessibleRole() === Gtk.AccessibleRole.RADIO;
 
@@ -331,7 +321,11 @@ const getWidgetCheckedState = (widget: Gtk.Widget): CheckedState | null => {
         return state;
     }
 
-    return isRadioToggle(widget) ? checkedFromActive(widget.getActive()) : null;
+    if (!isRadioToggle(widget)) {
+        return null;
+    }
+
+    return widget.getActive() ? "checked" : "unchecked";
 };
 
 const isWidgetChecked = (widget: Gtk.Widget): boolean | null => {
@@ -368,26 +362,20 @@ const getWidgetSelectedState = (widget: Gtk.Widget): boolean | null => {
     return null;
 };
 
-const getWidgetLevel = (widget: Gtk.Widget): number | null => {
-    return readAccessibleInt(widget, Gtk.AccessibleProperty.LEVEL);
-};
+const getWidgetLevel = (widget: Gtk.Widget): number | null =>
+    readAccessibleInt(widget, Gtk.AccessibleProperty.LEVEL);
 
-const getWidgetInvalidState = (widget: Gtk.Widget): Gtk.AccessibleInvalidState | null => {
-    const value = readAccessibleState(widget, Gtk.AccessibleState.INVALID);
-
-    return value ?? null;
-};
+const getWidgetInvalidState = (widget: Gtk.Widget): Gtk.AccessibleInvalidState | null =>
+    readAccessibleState(widget, Gtk.AccessibleState.INVALID);
 
 const getWidgetErrorMessage = (widget: Gtk.Widget): Gtk.Widget[] | null =>
     readAccessibleWidgets(widget, Gtk.AccessibleRelation.ERROR_MESSAGE);
 
-const getWidgetBusyState = (widget: Gtk.Widget): boolean | null => {
-    return readAccessibleBoolean(widget, Gtk.AccessibleState.BUSY);
-};
+const getWidgetBusyState = (widget: Gtk.Widget): boolean | null =>
+    readAccessibleBoolean(widget, Gtk.AccessibleState.BUSY);
 
-const getWidgetDescription = (widget: Gtk.Widget): string | null => {
-    return readAccessibleString(widget, Gtk.AccessibleProperty.DESCRIPTION);
-};
+const getWidgetDescription = (widget: Gtk.Widget): string | null =>
+    readAccessibleString(widget, Gtk.AccessibleProperty.DESCRIPTION);
 
 const getWidgetValueNow = (widget: Gtk.Widget): number | null =>
     readAccessibleNumber(widget, Gtk.AccessibleProperty.VALUE_NOW);
@@ -398,23 +386,13 @@ const getWidgetValueText = (widget: Gtk.Widget): string | null =>
 const isWidgetValueMatch = (widget: Gtk.Widget, field: WidgetValueField, expected: number): boolean =>
     isAccessibleNumberMatch(widget, VALUE_PROPERTIES[field], expected);
 
-const getWidgetOwnLabel = (widget: Gtk.Widget): string | null => {
-    return readAccessibleString(widget, Gtk.AccessibleProperty.LABEL);
-};
-
-const collectAccessibleNames = (targets: Gtk.Widget[]): string[] => {
-    const texts: string[] = [];
+const getWidgetOwnLabel = (widget: Gtk.Widget): string | null =>
+    readAccessibleString(widget, Gtk.AccessibleProperty.LABEL);
 
-    for (const target of targets) {
-        const text = getWidgetAccessibleName(target);
-
-        if (text) {
-            texts.push(text);
-        }
-    }
-
-    return texts;
-};
+const collectAccessibleNames = (targets: Gtk.Widget[]): string[] =>
+    targets
+        .map((target) => getWidgetAccessibleName(target))
+        .filter((text): text is string => text !== null && text !== "");
 
 const isSelfLabelling = (widget: Gtk.Widget, targets: Gtk.Widget[]): boolean => {
     const own = new Set(descendants(widget));