@gtkx/testing 1.0.0 → 1.2.0

package/src/user-event/text.ts

@@ -12,6 +12,8 @@ type SignalWatchTarget = {
     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. */
@@ -24,67 +26,138 @@ 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();
+};
 
-    if (target instanceof Gtk.Text) {
-        target.emit("insert-at-cursor", text);
+const focusPlainEditable = (widget: Gtk.Editable): void => {
+    const [isSelected, start, end] = widget.getSelectionBounds();
+    widget.grabFocus();
+
+    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 => getWidgetSelection(widget) ?? "";
-
-const deleteSelection = (widget: EditableTarget): void => {
+const focusEditable = (widget: EditableTarget): void => {
     if (widget instanceof Gtk.TextView) {
-        widget.getBuffer().deleteSelection(false, true);
+        widget.grabFocus();
 
         return;
     }
 
-    widget.deleteSelection();
-};
+    const target = getDelegateText(widget);
 
-const deleteAllText = (widget: EditableTarget): void => {
-    if (widget instanceof Gtk.TextView) {
-        const buffer = widget.getBuffer();
-        buffer.deleteInteractive(buffer.getStartIter(), buffer.getEndIter(), widget.getEditable());
+    if (target === null) {
+        focusPlainEditable(widget);
 
         return;
     }
 
-    widget.deleteText(0, -1);
+    target.grabFocusWithoutSelecting();
+
+    if (!hasSelectedText(widget)) {
+        widget.setPosition(TEXT_END_POSITION);
+    }
 };
 
-const applyTextViewSelection = (widget: Gtk.TextView, start: number, end: number): void => {
+const insertTextViewText = (widget: Gtk.TextView, text: string, kind: InsertKind): void => {
     const buffer = widget.getBuffer();
-    buffer.selectRange(buffer.getIterAtOffset(start), buffer.getIterAtOffset(end));
+    const length = getSelectionLength(buffer);
+    buffer.beginUserAction();
+
+    if (length > 0) {
+        widget.emit("delete-from-cursor", Gtk.DeleteType.CHARS, SELECTION_DELETE_COUNT);
 
-    if (end !== start) {
-        deleteSelection(widget);
+        if (kind === "typing" && length > SINGLE_CHARACTER_LENGTH) {
+            buffer.endUserAction();
+            buffer.beginUserAction();
+        }
     }
+
+    widget.emit("insert-at-cursor", text);
+    buffer.endUserAction();
 };
 
-const applyEditableSelection = (widget: Gtk.Editable, start: number, end: number): void => {
-    widget.selectRegion(start, end);
+const insertDelegateText = (target: Gtk.Text, text: string): void => {
+    if (hasSelectedText(target)) {
+        target.emit("delete-from-cursor", Gtk.DeleteType.CHARS, SELECTION_DELETE_COUNT);
+    }
 
-    if (end !== start) {
+    target.emit("insert-at-cursor", text);
+};
+
+const insertPlainText = (widget: Gtk.Editable, text: string): void => {
+    if (!isWidgetEditable(widget)) {
+        return;
+    }
+
+    if (hasSelectedText(widget)) {
         widget.deleteSelection();
     }
 
-    widget.setPosition(start);
+    const position = widget.getPosition();
+    const newPosition = widget.insertText(text, text.length, position);
+    widget.setPosition(newPosition);
+};
+
+const insertEditableText = (widget: EditableTarget, text: string, kind: InsertKind): void => {
+    if (widget instanceof Gtk.TextView) {
+        insertTextViewText(widget, text, kind);
+
+        return;
+    }
+
+    const target = getDelegateText(widget);
+
+    if (target === null) {
+        insertPlainText(widget, text);
+
+        return;
+    }
+
+    insertDelegateText(target, text);
+};
+
+const deleteAllText = (widget: EditableTarget): void => {
+    if (widget instanceof Gtk.TextView) {
+        const buffer = widget.getBuffer();
+        buffer.deleteInteractive(buffer.getStartIter(), buffer.getEndIter(), widget.getEditable());
+
+        return;
+    }
+
+    widget.deleteText(0, -1);
 };
 
 const applyInitialSelection = (widget: EditableTarget, options: TypeOptions): void => {
@@ -96,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 => {
@@ -130,23 +204,24 @@ 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 isWidgetEditable = (widget: Gtk.Widget): boolean => callBooleanGetter(widget, "getEditable") ?? true;
-
 const hasNonEditableChar = (iter: Gtk.TextIter, isDefaultEditable: boolean): boolean => {
     while (!iter.isEnd()) {
         if (!iter.editable(isDefaultEditable)) {
@@ -205,7 +280,7 @@ const didDeleteAllText = (widget: EditableTarget): boolean => {
 
 const clearEditable = (editable: EditableTarget): void => {
     requireClearableText(editable);
-    editable.grabFocus();
+    focusEditable(editable);
 
     if (readEditableText(editable) === "") {
         return;
@@ -251,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.
  */
@@ -263,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);
         }
     }

package/src/widget-getters.ts

@@ -1,8 +1,53 @@
+import type * as GObject from "@gtkx/gi/gobject";
 import type * as Gtk from "@gtkx/gi/gtk";
-import { getInstanceType, typeName } from "@gtkx/runtime";
+import { getClassType, getInstanceType, TYPE_INVALID, typeName } from "@gtkx/runtime";
+import { resolveWrapperClass } from "@gtkx/runtime/internal";
+import { type AnyClass, walkClassChain } from "@gtkx/utils";
+
+const UNNAMED_TYPE_TAG = "Object";
 
 const getWidgetMethod = (widget: Gtk.Widget, name: string): unknown => Reflect.get(widget, name);
 const getWidgetTypeName = (widget: Gtk.Widget): string | null => typeName(getInstanceType(widget));
+const isClass = (value: unknown): value is AnyClass => typeof value === "function";
+
+const nonEmpty = (value: unknown): string | undefined =>
+    typeof value === "string" && value.length > 0 ? value : undefined;
+
+const getObjectClass = (object: GObject.Object): AnyClass | null => {
+    const cls: unknown = object.constructor;
+
+    return isClass(cls) ? cls : null;
+};
+
+const getNearestClassName = (object: GObject.Object): string | undefined =>
+    walkClassChain(getObjectClass(object), (ancestor) => nonEmpty(ancestor.name));
+
+const getUntypedClassName = (object: GObject.Object): string | undefined => {
+    const cls = getObjectClass(object);
+
+    return cls !== null && getClassType(cls) === TYPE_INVALID ? nonEmpty(cls.name) : undefined;
+};
+
+const getExactWrapperName = (type: bigint): string | undefined => {
+    const wrapper = resolveWrapperClass(type);
+
+    return wrapper !== null && getClassType(wrapper) === type ? nonEmpty(wrapper.name) : undefined;
+};
+
+const getTypeTag = (object: GObject.Object): string => {
+    const type = getInstanceType(object);
+
+    return (
+        getUntypedClassName(object) ??
+        getExactWrapperName(type) ??
+        nonEmpty(typeName(type)) ??
+        getNearestClassName(object) ??
+        UNNAMED_TYPE_TAG
+    );
+};
+
+const isDefaultWidgetName = (widget: Gtk.Widget, name: string): boolean =>
+    name.length === 0 || name === getWidgetTypeName(widget);
 
 const hasWidgetMethod = (widget: Gtk.Widget, name: string): boolean =>
     typeof getWidgetMethod(widget, name) === "function";
@@ -29,4 +74,12 @@ const callStringGetter = (widget: Gtk.Widget, method: string): string | null =>
     return typeof value === "string" ? value : null;
 };
 
-export { callBooleanGetter, callStringGetter, getCallableMethod, getWidgetTypeName, hasWidgetMethod };
+export {
+    callBooleanGetter,
+    callStringGetter,
+    getCallableMethod,
+    getTypeTag,
+    getWidgetTypeName,
+    hasWidgetMethod,
+    isDefaultWidgetName,
+};

package/src/window-state.ts

@@ -0,0 +1,70 @@
+import * as Gtk from "@gtkx/gi/gtk";
+
+const WINDOW_NOT_ALLOCATED = "it was never allocated a size";
+const WINDOW_NOT_ACTIVATED = "it never became active";
+const NO_WINDOW_ACTIVATED = "no window of the application ever became active";
+
+const canDisplayDeliverActivation = (window: Gtk.Window): boolean => window.getDisplay().getDefaultSeat() !== null;
+const isWindow = (widget: Gtk.Widget): widget is Gtk.Window => widget instanceof Gtk.Window;
+
+const mappedToplevels = (): Gtk.Window[] =>
+    Gtk.Window.listToplevels().filter((widget) => isWindow(widget)).filter((window) => window.getMapped());
+
+const isWindowAllocated = (window: Gtk.Window): boolean => {
+    const [isComputed, allocation] = window.computeBounds(window);
+
+    return isComputed && allocation.getWidth() > 0;
+};
+
+const activeToplevel = (): Gtk.Window | null => mappedToplevels().find((toplevel) => toplevel.isActive()) ?? null;
+
+const isWindowActivated = (window: Gtk.Window): boolean =>
+    !canDisplayDeliverActivation(window) || window.isActive();
+
+const isApplicationActivated = (window: Gtk.Window): boolean =>
+    !canDisplayDeliverActivation(window) || activeToplevel() !== null;
+
+const isTransientDescendant = (window: Gtk.Window, ancestor: Gtk.Window): boolean => {
+    for (let parent = window.getTransientFor(); parent !== null; parent = parent.getTransientFor()) {
+        if (parent === ancestor) {
+            return true;
+        }
+    }
+
+    return false;
+};
+
+const isModalGrabHeldOver = (modal: Gtk.Window, window: Gtk.Window): boolean =>
+    modal.getModal() &&
+    modal !== window &&
+    modal.getGroup() === window.getGroup() &&
+    !isTransientDescendant(window, modal);
+
+const isWindowBlockedByModal = (window: Gtk.Window): boolean =>
+    mappedToplevels().some((toplevel) => isModalGrabHeldOver(toplevel, window));
+
+const findPresentedWindowFailure = (window: Gtk.Window): string | null => {
+    if (!isWindowAllocated(window)) {
+        return WINDOW_NOT_ALLOCATED;
+    }
+
+    return isWindowActivated(window) ? null : WINDOW_NOT_ACTIVATED;
+};
+
+const findRenderedWindowFailure = (window: Gtk.Window): string | null => {
+    if (!isWindowAllocated(window)) {
+        return WINDOW_NOT_ALLOCATED;
+    }
+
+    return isApplicationActivated(window) ? null : NO_WINDOW_ACTIVATED;
+};
+
+export {
+    activeToplevel,
+    findPresentedWindowFailure,
+    findRenderedWindowFailure,
+    isWindowActivated,
+    isWindowAllocated,
+    isWindowBlockedByModal,
+    mappedToplevels,
+};