@gtkx/testing 1.0.0-rc.4 → 1.1.0

package/src/user-event/selection.ts

@@ -1,11 +1,23 @@
 import * as Gtk from "@gtkx/gi/gtk";
 import { formatRoleList } from "../role-helpers.js";
+import { getCallableMethod } from "../widget-getters.js";
 import { wrapEvent } from "./event-wrapper.js";
+import {
+    getChildAtIndex,
+    hasIndexedChildren,
+    isChildSelected,
+    selectContainerChild,
+    unselectContainerChild,
+} from "./indexed-children.js";
 
 type CollectionWidget = Gtk.ListView | Gtk.GridView | Gtk.ColumnView;
-type ListBoxRowAction = (listBox: Gtk.ListBox, row: Gtk.ListBoxRow) => void;
+type IndexedChildAction = (container: Gtk.Widget, child: Gtk.Widget) => void;
 
-const SELECTABLE_ROLES: Set<Gtk.AccessibleRole> = new Set([Gtk.AccessibleRole.COMBO_BOX, Gtk.AccessibleRole.LIST]);
+const SELECTABLE_ROLES: Set<Gtk.AccessibleRole> = new Set([
+    Gtk.AccessibleRole.COMBO_BOX,
+    Gtk.AccessibleRole.GRID,
+    Gtk.AccessibleRole.LIST,
+]);
 
 const isSelectable = (widget: Gtk.Widget): boolean => {
     return SELECTABLE_ROLES.has(widget.getAccessibleRole());
@@ -44,42 +56,40 @@ const selectListViewItems = (
 const isListView = (widget: Gtk.Widget): widget is CollectionWidget =>
     widget instanceof Gtk.ListView || widget instanceof Gtk.GridView || widget instanceof Gtk.ColumnView;
 
-const selectComboBoxOption = (widget: Gtk.Widget, valueArray: number[]): void => {
-    if (valueArray.length > 1) {
-        throw new Error("Cannot select multiple options: ComboBox only supports single selection");
-    }
+const getIndexSelector = (widget: Gtk.Widget): ((position: number) => void) | null =>
+    getCallableMethod<[number], unknown>(widget, "setSelected");
 
-    const [selection] = valueArray;
+const selectDropDownOption = (widget: Gtk.Widget, valueArray: number[]): void => {
+    const setSelected = getIndexSelector(widget);
 
-    if (selection === undefined) {
-        return;
+    if (!setSelected) {
+        throw new TypeError("Cannot select options: the COMBO_BOX role needs a widget exposing setSelected");
     }
 
-    if (widget instanceof Gtk.DropDown) {
-        widget.setSelected(selection);
-    } else if (widget instanceof Gtk.ComboBox) {
-        widget.setActive(selection);
+    if (valueArray.length > 1) {
+        throw new Error("Cannot select multiple options: a drop-down only supports single selection");
     }
-};
 
-const selectListBoxRow = (listBox: Gtk.ListBox, row: Gtk.ListBoxRow): void => {
-    listBox.selectRow(row);
-    row.activate();
+    const [selection] = valueArray;
+
+    if (selection !== undefined) {
+        setSelected(selection);
+    }
 };
 
-const unselectListBoxRow = (listBox: Gtk.ListBox, row: Gtk.ListBoxRow): void => {
-    listBox.unselectRow(row);
+const unselectChildRow = (container: Gtk.Widget, child: Gtk.Widget): void => {
+    if (isChildSelected(child)) {
+        unselectContainerChild(container, child);
+    }
 };
 
-const applyListBoxRows = (listBox: Gtk.ListBox, valueArray: number[], apply: ListBoxRowAction): void => {
+const applyIndexedChildren = (widget: Gtk.Widget, valueArray: number[], apply: IndexedChildAction): void => {
     for (const value of valueArray) {
-        const row = listBox.getRowAtIndex(value);
+        const child = getChildAtIndex(widget, value);
 
-        if (!row) {
-            continue;
+        if (child) {
+            apply(widget, child);
         }
-
-        apply(listBox, row);
     }
 };
 
@@ -102,18 +112,29 @@ const selectInListView = (widget: CollectionWidget, valueArray: number[]): void
     selectListViewItems(selectionModel, valueArray, !isMultiSelection);
 };
 
-const selectByRole = (widget: Gtk.Widget, valueArray: number[]): void => {
+const requireSelectableRole = (widget: Gtk.Widget, verb: string): void => {
     if (!isSelectable(widget)) {
-        throw new Error(`Cannot select options: expected selectable widget (${formatRoleList(SELECTABLE_ROLES)})`);
+        throw new Error(
+            `Cannot ${verb} options: expected selectable widget (${formatRoleList(SELECTABLE_ROLES)})`,
+        );
     }
+};
 
+const selectByRole = (widget: Gtk.Widget, valueArray: number[]): void => {
+    requireSelectableRole(widget, "select");
     const role = widget.getAccessibleRole();
 
     if (role === Gtk.AccessibleRole.COMBO_BOX) {
-        selectComboBoxOption(widget, valueArray);
-    } else if (widget instanceof Gtk.ListBox) {
-        applyListBoxRows(widget, valueArray, selectListBoxRow);
+        selectDropDownOption(widget, valueArray);
+
+        return;
+    }
+
+    if (!hasIndexedChildren(widget)) {
+        throw new TypeError("Cannot select options: the widget exposes no children to select by index");
     }
+
+    applyIndexedChildren(widget, valueArray, selectContainerChild);
 };
 
 const runSelectionEvent = (
@@ -136,11 +157,13 @@ const runSelectionEvent = (
 
 /**
  * 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.
+ * 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 is given more than one position, or
- * when the widget is neither a view nor something with the combo box or list role.
+ * @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.
  */
 const selectOptions = (widget: Gtk.Widget, values: number | number[]): Promise<void> =>
     runSelectionEvent(widget, values, selectInListView, selectByRole);
@@ -154,19 +177,22 @@ const deselectInListView = (widget: Gtk.ListView | Gtk.GridView | Gtk.ColumnView
 };
 
 const deselectByRole = (widget: Gtk.Widget, valueArray: number[]): void => {
-    if (!(widget instanceof Gtk.ListBox)) {
-        throw new TypeError("Cannot deselect options: only ListBox supports deselection");
+    requireSelectableRole(widget, "deselect");
+
+    if (!hasIndexedChildren(widget)) {
+        throw new TypeError("Cannot deselect options: the widget exposes no children to deselect by index");
     }
 
-    applyListBoxRows(widget, valueArray, unselectListBoxRow);
+    applyIndexedChildren(widget, valueArray, unselectChildRow);
 };
 
 /**
- * Unselects the items at the given positions in a list, grid, or column view, or the rows at those
- * indices in a Gtk.ListBox.
+ * 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, or when the widget is neither one of those views nor
- * a Gtk.ListBox.
+ * @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.
  */
 const deselectOptions = (widget: Gtk.Widget, values: number | number[]): Promise<void> =>
     runSelectionEvent(widget, values, deselectInListView, deselectByRole);

package/src/user-event/text.ts

@@ -1,10 +1,19 @@
 import * as Gdk from "@gtkx/gi/gdk";
 import * as GObject from "@gtkx/gi/gobject";
 import * as Gtk from "@gtkx/gi/gtk";
-import { EDITABLE_ROLES, type EditableTarget, getEditableDelegate, isEditable } from "../editable.js";
+import { EDITABLE_ROLES, type EditableTarget, getEditableDelegate, isEditable, readEditableText } from "../editable.js";
 import { formatRoleList } from "../role-helpers.js";
+import { getWidgetSelection } from "../widget-accessible-properties.js";
+import { callBooleanGetter } from "../widget-getters.js";
 import { wrapEvent } from "./event-wrapper.js";
 
+type SignalWatchTarget = {
+    on(signal: string, handler: (...args: unknown[]) => unknown, isAfter?: boolean): unknown;
+    off(signal: string, handler: (...args: unknown[]) => unknown): unknown;
+};
+
+type InsertKind = "typing" | "pasting";
+
 /** Options for `userEvent.type`. */
 type TypeOptions = {
     /** Focus the widget before typing; defaults to true. */
@@ -16,77 +25,139 @@ type TypeOptions = {
 };
 
 const EDITABLE_REQUIRED = `expected editable widget (${formatRoleList(EDITABLE_ROLES)})`;
+const CLEAR_REFUSED = "Cannot clear element: the widget refuses to delete part of its text";
+const SELECTION_DELETE_COUNT = 1;
+const SINGLE_CHARACTER_LENGTH = 1;
+const TEXT_END_POSITION = -1;
+
+const isWidgetEditable = (widget: Gtk.Widget): boolean => callBooleanGetter(widget, "getEditable") ?? true;
+const readSelection = (widget: EditableTarget): string => getWidgetSelection(widget) ?? "";
+const hasSelectedText = (widget: Gtk.Editable): boolean => widget.getSelectionBounds()[0];
+
+const getDelegateText = (widget: Gtk.Editable): Gtk.Text | null => {
+    const delegate = getEditableDelegate(widget) ?? widget;
+
+    return delegate instanceof Gtk.Text ? delegate : null;
+};
+
+const getSelectionLength = (buffer: Gtk.TextBuffer): number => {
+    const [isSelected, start, end] = buffer.getSelectionBounds();
+
+    return isSelected ? end.getOffset() - start.getOffset() : 0;
+};
 
-const insertEditableText = (widget: EditableTarget, text: string): void => {
+const deleteSelection = (widget: EditableTarget): void => {
     if (widget instanceof Gtk.TextView) {
-        widget.emit("insert-at-cursor", text);
+        widget.getBuffer().deleteSelection(false, true);
 
         return;
     }
 
-    const target = getEditableDelegate(widget) ?? widget;
+    widget.deleteSelection();
+};
+
+const focusPlainEditable = (widget: Gtk.Editable): void => {
+    const [isSelected, start, end] = widget.getSelectionBounds();
+    widget.grabFocus();
 
-    if (target instanceof Gtk.Text) {
-        target.emit("insert-at-cursor", text);
+    if (isSelected) {
+        widget.selectRegion(start, end);
 
         return;
     }
 
-    const position = widget.getPosition();
-    const newPosition = widget.insertText(text, text.length, position);
-    widget.setPosition(newPosition);
+    widget.setPosition(TEXT_END_POSITION);
 };
 
-const readSelection = (widget: EditableTarget): string => {
+const focusEditable = (widget: EditableTarget): void => {
     if (widget instanceof Gtk.TextView) {
-        const buffer = widget.getBuffer();
-        const [hasSelection, start, end] = buffer.getSelectionBounds();
+        widget.grabFocus();
+
+        return;
+    }
+
+    const target = getDelegateText(widget);
 
-        return hasSelection ? buffer.getText(start, end, true) : "";
+    if (target === null) {
+        focusPlainEditable(widget);
+
+        return;
     }
 
-    const [hasSelection, start, end] = widget.getSelectionBounds();
+    target.grabFocusWithoutSelecting();
 
-    return hasSelection ? widget.getChars(start, end) : "";
+    if (!hasSelectedText(widget)) {
+        widget.setPosition(TEXT_END_POSITION);
+    }
 };
 
-const deleteSelection = (widget: EditableTarget): void => {
-    if (widget instanceof Gtk.TextView) {
-        widget.getBuffer().deleteSelection(false, true);
+const insertTextViewText = (widget: Gtk.TextView, text: string, kind: InsertKind): void => {
+    const buffer = widget.getBuffer();
+    const length = getSelectionLength(buffer);
+    buffer.beginUserAction();
+
+    if (length > 0) {
+        widget.emit("delete-from-cursor", Gtk.DeleteType.CHARS, SELECTION_DELETE_COUNT);
+
+        if (kind === "typing" && length > SINGLE_CHARACTER_LENGTH) {
+            buffer.endUserAction();
+            buffer.beginUserAction();
+        }
+    }
 
+    widget.emit("insert-at-cursor", text);
+    buffer.endUserAction();
+};
+
+const insertDelegateText = (target: Gtk.Text, text: string): void => {
+    if (hasSelectedText(target)) {
+        target.emit("delete-from-cursor", Gtk.DeleteType.CHARS, SELECTION_DELETE_COUNT);
+    }
+
+    target.emit("insert-at-cursor", text);
+};
+
+const insertPlainText = (widget: Gtk.Editable, text: string): void => {
+    if (!isWidgetEditable(widget)) {
         return;
     }
 
-    widget.deleteSelection();
+    if (hasSelectedText(widget)) {
+        widget.deleteSelection();
+    }
+
+    const position = widget.getPosition();
+    const newPosition = widget.insertText(text, text.length, position);
+    widget.setPosition(newPosition);
 };
 
-const setEditableText = (widget: EditableTarget, text: string): void => {
+const insertEditableText = (widget: EditableTarget, text: string, kind: InsertKind): void => {
     if (widget instanceof Gtk.TextView) {
-        widget.getBuffer().setText(text, text.length);
+        insertTextViewText(widget, text, kind);
 
         return;
     }
 
-    widget.setText(text);
-};
+    const target = getDelegateText(widget);
 
-const applyTextViewSelection = (widget: Gtk.TextView, start: number, end: number): void => {
-    const buffer = widget.getBuffer();
-    buffer.selectRange(buffer.getIterAtOffset(start), buffer.getIterAtOffset(end));
+    if (target === null) {
+        insertPlainText(widget, text);
 
-    if (end !== start) {
-        deleteSelection(widget);
+        return;
     }
+
+    insertDelegateText(target, text);
 };
 
-const applyEditableSelection = (widget: Gtk.Editable, start: number, end: number): void => {
-    widget.selectRegion(start, end);
+const deleteAllText = (widget: EditableTarget): void => {
+    if (widget instanceof Gtk.TextView) {
+        const buffer = widget.getBuffer();
+        buffer.deleteInteractive(buffer.getStartIter(), buffer.getEndIter(), widget.getEditable());
 
-    if (end !== start) {
-        widget.deleteSelection();
+        return;
     }
 
-    widget.setPosition(start);
+    widget.deleteText(0, -1);
 };
 
 const applyInitialSelection = (widget: EditableTarget, options: TypeOptions): void => {
@@ -98,12 +169,13 @@ const applyInitialSelection = (widget: EditableTarget, options: TypeOptions): vo
     const end = options.initialSelectionEnd ?? start;
 
     if (widget instanceof Gtk.TextView) {
-        applyTextViewSelection(widget, start, end);
+        const buffer = widget.getBuffer();
+        buffer.selectRange(buffer.getIterAtOffset(start), buffer.getIterAtOffset(end));
 
         return;
     }
 
-    applyEditableSelection(widget, start, end);
+    widget.selectRegion(start, end);
 };
 
 const writeClipboardText = (widget: Gtk.Widget, text: string): void => {
@@ -132,30 +204,104 @@ const runEditableEvent = (
     });
 
 /**
- * Focuses the widget unless `shouldFocus` is false, applies any initial selection, and inserts the text
- * at the cursor.
+ * 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.
  */
 const type = (widget: Gtk.Widget, text: string, options?: TypeOptions): Promise<void> =>
     runEditableEvent(widget, "Cannot type into element", (editable) => {
         if (options?.shouldFocus ?? true) {
-            editable.grabFocus();
+            focusEditable(editable);
         }
 
         applyInitialSelection(editable, options ?? {});
-        insertEditableText(editable, text);
+        insertEditableText(editable, text, "typing");
+    });
+
+const hasNonEditableChar = (iter: Gtk.TextIter, isDefaultEditable: boolean): boolean => {
+    while (!iter.isEnd()) {
+        if (!iter.editable(isDefaultEditable)) {
+            return true;
+        }
+
+        if (!iter.forwardChar()) {
+            return false;
+        }
+    }
+
+    return false;
+};
+
+const hasProtectedText = (widget: EditableTarget): boolean =>
+    widget instanceof Gtk.TextView && hasNonEditableChar(widget.getBuffer().getStartIter(), widget.getEditable());
+
+const requireClearableText = (editable: EditableTarget): void => {
+    if (!isWidgetEditable(editable)) {
+        throw new Error("Cannot clear element: the widget is not editable");
+    }
+
+    if (hasProtectedText(editable)) {
+        throw new Error(CLEAR_REFUSED);
+    }
+};
+
+const deletionSignalFor = (widget: EditableTarget): [SignalWatchTarget, string] =>
+    widget instanceof Gtk.TextView ? [widget.getBuffer(), "delete-range"] : [widget, "delete-text"];
+
+const isDeletionApplied = (emitter: SignalWatchTarget, signal: string, apply: () => void): boolean => {
+    let isApplied = false;
+
+    const watch = (): void => {
+        isApplied = true;
+    };
+
+    emitter.on(signal, watch, true);
+
+    try {
+        apply();
+    } finally {
+        emitter.off(signal, watch);
+    }
+
+    return isApplied;
+};
+
+const didDeleteAllText = (widget: EditableTarget): boolean => {
+    const [emitter, signal] = deletionSignalFor(widget);
+
+    return isDeletionApplied(emitter, signal, () => {
+        deleteAllText(widget);
     });
+};
+
+const clearEditable = (editable: EditableTarget): void => {
+    requireClearableText(editable);
+    focusEditable(editable);
+
+    if (readEditableText(editable) === "") {
+        return;
+    }
+
+    if (!didDeleteAllText(editable)) {
+        throw new Error(CLEAR_REFUSED);
+    }
+};
 
 /**
- * Replaces an editable widget's text with the empty string.
+ * 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.
+ * @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.
  */
 const clear = (widget: Gtk.Widget): Promise<void> =>
-    runEditableEvent(widget, "Cannot clear element", (editable) => {
-        setEditableText(editable, "");
-    });
+    runEditableEvent(widget, "Cannot clear element", clearEditable);
 
 /**
  * Writes an editable widget's selected text to its clipboard, or the empty string when nothing is selected.
@@ -180,7 +326,7 @@ const cut = (widget: Gtk.Widget): Promise<void> =>
 
 /**
  * Inserts the given text at an editable widget's cursor, reading the clipboard instead when no text
- * is given.
+ * 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.
  */
@@ -192,7 +338,7 @@ const paste = async (widget: Gtk.Widget, text?: string): Promise<void> => {
     const content = text ?? (await widget.getClipboard().readTextAsync(null)) ?? "";
 
     await wrapEvent(widget, () => {
-        insertEditableText(widget, content);
+        insertEditableText(widget, content, "pasting");
     });
 };
 

package/src/wait-for.ts

@@ -3,6 +3,7 @@ import type { WaitForOptions } from "./types.js";
 import { runWithActEnvironment } from "./act.js";
 import { getConfig } from "./config.js";
 import { timeoutError } from "./errors.js";
+import { advanceFakeClock, delay, now } from "./timers.js";
 
 type PollResult<T> = { status: "resolved"; value: T } | { status: "timedout"; lastError: Error | null };
 /** Widgets watched for removal; null counts as already removed. */
@@ -13,8 +14,6 @@ type ElementOrCallback = Gtk.Widget | Gtk.Widget[] | (() => RemovalTarget);
 const DEFAULT_INTERVAL = 50;
 const ELEMENT_NOT_REMOVED = new Error("Element not yet removed");
 
-const delay = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
-
 const copyStackTrace = (target: Error, source: Error): void => {
     const { stack } = source;
 
@@ -38,10 +37,10 @@ const pollUntilSuccess = async <T>(
     timeout: number,
     interval: number,
 ): Promise<PollResult<T>> => {
-    const startTime = Date.now();
+    const startTime = now();
     let lastError: Error | null = null;
 
-    while (Date.now() - startTime < timeout) {
+    while (now() - startTime < timeout) {
         try {
             const result = await callback();
             await delay(0);
@@ -49,6 +48,7 @@ const pollUntilSuccess = async <T>(
             return { status: "resolved", value: result };
         } catch (error) {
             lastError = error as Error;
+            await advanceFakeClock(interval);
             await delay(interval);
         }
     }