@gtkx/testing 0.21.0 → 1.0.0-rc.2

package/src/user-event/click.ts

@@ -0,0 +1,99 @@
+import * as Gtk from "@gtkx/gi/gtk";
+import { getOrCreateControllers, queryController } from "./controller.js";
+import { wrapEvent } from "./event-wrapper.js";
+
+const getPressPoint = (widget: Gtk.Widget): { x: number; y: number } => {
+    const width = widget.getWidth();
+    const height = widget.getHeight();
+
+    if (width > 0 && height > 0) {
+        return { x: width / 2, y: height / 2 };
+    }
+
+    return { x: 0, y: 0 };
+};
+
+const emitGesture = (widget: Gtk.Widget, controllers: Gtk.GestureClick[], nPress: number, signal: string): void => {
+    const { x, y } = getPressPoint(widget);
+
+    for (const controller of controllers) {
+        controller.emit(signal, nPress, x, y);
+    }
+};
+
+const emitPress = (widget: Gtk.Widget, controllers: Gtk.GestureClick[], nPress: number): void => {
+    emitGesture(widget, controllers, nPress, "pressed");
+};
+
+const emitRelease = (widget: Gtk.Widget, controllers: Gtk.GestureClick[], nPress: number): void => {
+    emitGesture(widget, controllers, nPress, "released");
+};
+
+const emitClickSequence = (widget: Gtk.Widget, target: Gtk.Widget, nPress: number): Promise<void> =>
+    wrapEvent(widget, () => {
+        const controllers = getOrCreateControllers(target, Gtk.GestureClick);
+
+        for (let i = 1; i <= nPress; i++) {
+            emitPress(target, controllers, i);
+            emitRelease(target, controllers, i);
+        }
+    });
+
+const findClickableAncestor = (widget: Gtk.Widget): Gtk.Widget | null => {
+    let current = widget.getParent();
+
+    while (current) {
+        if (current instanceof Gtk.Button || queryController(current, Gtk.GestureClick) !== null) {
+            return current;
+        }
+
+        current = current.getParent();
+    }
+
+    return null;
+};
+
+const tryActivate = async (widget: Gtk.Widget): Promise<boolean> => {
+    if (widget.getAccessibleRole() === Gtk.AccessibleRole.LABEL) {
+        return false;
+    }
+
+    let isActivated = false;
+
+    await wrapEvent(widget, () => {
+        isActivated = widget.activate();
+    });
+
+    return isActivated;
+};
+
+const click = async (widget: Gtk.Widget): Promise<void> => {
+    if (widget instanceof Gtk.Button) {
+        await emitClickSequence(widget, widget, 1);
+
+        return;
+    }
+
+    if (widget instanceof Gtk.Switch) {
+        await wrapEvent(widget, () => {
+            widget.setActive(!widget.getActive());
+        });
+
+        return;
+    }
+
+    if (await tryActivate(widget)) {
+        return;
+    }
+
+    const target = findClickableAncestor(widget);
+
+    if (target) {
+        await emitClickSequence(widget, target, 1);
+    }
+};
+
+const dblClick = (widget: Gtk.Widget): Promise<void> => emitClickSequence(widget, widget, 2);
+const tripleClick = (widget: Gtk.Widget): Promise<void> => emitClickSequence(widget, widget, 3);
+
+export { emitPress, emitRelease, click, dblClick, tripleClick };

package/src/user-event/controller.ts

@@ -0,0 +1,58 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+
+type ControllerConstructor<T extends Gtk.EventController> = new () => T;
+
+const queryAllControllers = <T extends Gtk.EventController>(
+    widget: Gtk.Widget,
+    controllerType: ControllerConstructor<T>,
+): T[] => {
+    const controllers = widget.observeControllers();
+    const nItems = controllers.getNItems();
+    const matches: T[] = [];
+
+    for (let i = 0; i < nItems; i++) {
+        const controller = controllers.getItem(i);
+
+        if (controller instanceof controllerType) {
+            matches.push(controller);
+        }
+    }
+
+    return matches;
+};
+
+const queryController = <T extends Gtk.EventController>(
+    widget: Gtk.Widget,
+    controllerType: ControllerConstructor<T>,
+): T | null => queryAllControllers(widget, controllerType)[0] ?? null;
+
+const getAllControllers = <T extends Gtk.EventController>(
+    widget: Gtk.Widget,
+    controllerType: ControllerConstructor<T>,
+): T[] => {
+    const controllers = queryAllControllers(widget, controllerType);
+
+    if (controllers.length === 0) {
+        throw new Error(`No ${controllerType.name} controller is attached to the widget`);
+    }
+
+    return controllers;
+};
+
+const getOrCreateControllers = <T extends Gtk.EventController>(
+    widget: Gtk.Widget,
+    controllerType: ControllerConstructor<T>,
+): T[] => {
+    const existing = queryAllControllers(widget, controllerType);
+
+    if (existing.length > 0) {
+        return existing;
+    }
+
+    const controller = new controllerType();
+    widget.addController(controller);
+
+    return [controller];
+};
+
+export { queryAllControllers, queryController, getAllControllers, getOrCreateControllers, type ControllerConstructor };

package/src/user-event/dispatch.ts

@@ -0,0 +1,25 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import { type ControllerConstructor, getAllControllers, getOrCreateControllers } from "./controller.js";
+import { wrapEvent } from "./event-wrapper.js";
+
+type ControllerEmit<T extends Gtk.EventController> = (controller: T) => void | PromiseLike<void>;
+
+const emitOnAll = async <T extends Gtk.EventController>(controllers: T[], emit: ControllerEmit<T>): Promise<void> => {
+    for (const controller of controllers) {
+        await emit(controller);
+    }
+};
+
+const dispatchOnOrCreateControllers = <T extends Gtk.EventController>(
+    widget: Gtk.Widget,
+    controllerType: ControllerConstructor<T>,
+    emit: ControllerEmit<T>,
+): Promise<void> => wrapEvent(widget, () => emitOnAll(getOrCreateControllers(widget, controllerType), emit));
+
+const dispatchOnControllers = <T extends Gtk.EventController>(
+    widget: Gtk.Widget,
+    controllerType: ControllerConstructor<T>,
+    emit: ControllerEmit<T>,
+): Promise<void> => wrapEvent(widget, () => emitOnAll(getAllControllers(widget, controllerType), emit));
+
+export { dispatchOnOrCreateControllers, dispatchOnControllers };

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

@@ -0,0 +1,80 @@
+import * as Gtk from "@gtkx/gi/gtk";
+import { runInAct } from "../act.js";
+import { getConfig } from "../config.js";
+import { formatRole } from "../role-helpers.js";
+
+const NOT_SENSITIVE = "it is not sensitive (the widget or one of its ancestors is disabled)";
+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 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;
+    }
+
+    if (!widget.getMapped()) {
+        return NOT_MAPPED;
+    }
+
+    if (canDisplayDeliverActivation(root) && !root.isActive()) {
+        return WINDOW_NOT_ACTIVE;
+    }
+
+    return null;
+};
+
+const findActionabilityFailure = (widget: Gtk.Widget): string | null => {
+    if (!widget.isSensitive()) {
+        return NOT_SENSITIVE;
+    }
+
+    const root = widget.getRoot();
+
+    if (!(root instanceof Gtk.Window) || !root.getVisible()) {
+        return null;
+    }
+
+    return findWindowActionabilityFailure(widget, root);
+};
+
+const describeWidget = (widget: Gtk.Widget): string => {
+    const tag = widget.constructor.name;
+    const name = widget.getName();
+    const nameAttribute = name && !name.endsWith(tag) ? ` name="${name}"` : "";
+
+    return `<${tag}${nameAttribute} role="${formatRole(widget.getAccessibleRole())}">`;
+};
+
+const waitForActionable = async (widget: Gtk.Widget): Promise<void> => {
+    const timeout = getConfig().actionabilityTimeout;
+    const deadline = Date.now() + timeout;
+    let failure = findActionabilityFailure(widget);
+
+    while (failure !== null && Date.now() < deadline) {
+        await actionableHop();
+        failure = findActionabilityFailure(widget);
+    }
+
+    if (failure !== null) {
+        throw new Error(
+            `Cannot dispatch user event: ${describeWidget(widget)} did not become actionable ` +
+            `within ${String(timeout)}ms because ${failure}`,
+        );
+    }
+};
+
+const wrapEvent = async (widget: Gtk.Widget, body: () => void | PromiseLike<void>): Promise<void> => {
+    await waitForActionable(widget);
+
+    await runInAct(async () => {
+        await body();
+    });
+};
+
+export { wrapEvent };

package/src/user-event/gesture.ts

@@ -0,0 +1,239 @@
+import * as GObject from "@gtkx/gi/gobject";
+import * as Gtk from "@gtkx/gi/gtk";
+import { getAllControllers } from "./controller.js";
+import { dispatchOnControllers, dispatchOnOrCreateControllers } from "./dispatch.js";
+import { wrapEvent } from "./event-wrapper.js";
+
+/** The value delivered to a drop target: a primitive (converted to a GObject.Value) or an explicit GObject.Value. */
+type DropContent = string | number | boolean | GObject.Value;
+
+/** Options for a drop: the drop coordinates within the target. */
+type DropOptions = {
+    x?: number;
+    y?: number;
+};
+
+/** A drag offset relative to the drag start point. */
+type DragOffset = {
+    x: number;
+    y: number;
+};
+
+/**
+ * Options for a drag gesture: the starting point, the number of interpolated drag updates, or
+ * explicit intermediate offsets emitted before the final one.
+ */
+type DragOptions = {
+    startX?: number;
+    startY?: number;
+    steps?: number;
+    offsets?: DragOffset[];
+};
+
+type DragInstancePatch = {
+    getStartPoint?: Gtk.GestureDrag["getStartPoint"] | undefined;
+    getOffset?: Gtk.GestureDrag["getOffset"] | undefined;
+};
+
+type SavedDragState = {
+    instance: DragInstancePatch;
+    ownsStartPoint: boolean;
+    ownsOffset: boolean;
+    previousStartPoint: DragInstancePatch["getStartPoint"];
+    previousOffset: DragInstancePatch["getOffset"];
+};
+
+const buildDropValue = (content: DropContent): GObject.Value => {
+    if (content instanceof GObject.Value) {
+        return content;
+    }
+
+    if (typeof content === "string") {
+        return GObject.buildValue(GObject.TYPE_STRING, (v) => {
+            v.setString(content);
+        });
+    }
+
+    if (typeof content === "boolean") {
+        return GObject.buildValue(GObject.TYPE_BOOLEAN, (v) => {
+            v.setBoolean(content);
+        });
+    }
+
+    return GObject.buildValue(GObject.TYPE_DOUBLE, (v) => {
+        v.setDouble(content);
+    });
+};
+
+const hover = (widget: Gtk.Widget): Promise<void> =>
+    dispatchOnOrCreateControllers(widget, Gtk.EventControllerMotion, (controller) => {
+        controller.emit("enter", 0, 0);
+    });
+
+const unhover = (widget: Gtk.Widget): Promise<void> =>
+    dispatchOnOrCreateControllers(widget, Gtk.EventControllerMotion, (controller) => {
+        controller.emit("leave");
+    });
+
+const rotate = (widget: Gtk.Widget, angle: number, deltaAngle: number = angle): Promise<void> =>
+    dispatchOnControllers(widget, Gtk.GestureRotate, (controller) => {
+        controller.emit("angle-changed", angle, deltaAngle);
+    },
+    );
+
+const zoom = (widget: Gtk.Widget, scale: number): Promise<void> =>
+    dispatchOnControllers(widget, Gtk.GestureZoom, (controller) => {
+        controller.emit("scale-changed", scale);
+    });
+
+const swipe = (widget: Gtk.Widget, velocityX: number, velocityY: number): Promise<void> =>
+    dispatchOnControllers(widget, Gtk.GestureSwipe, (controller) => {
+        controller.emit("swipe", velocityX, velocityY);
+    });
+
+const longPress = (widget: Gtk.Widget, x = 0, y = 0): Promise<void> =>
+    dispatchOnControllers(widget, Gtk.GestureLongPress, (controller) => {
+        controller.emit("pressed", x, y);
+    });
+
+const restoreDragState = (saved: SavedDragState): void => {
+    const { instance } = saved;
+
+    if (saved.ownsStartPoint) {
+        instance.getStartPoint = saved.previousStartPoint;
+    } else {
+        delete instance.getStartPoint;
+    }
+
+    if (saved.ownsOffset) {
+        instance.getOffset = saved.previousOffset;
+    } else {
+        delete instance.getOffset;
+    }
+};
+
+const patchDragState = (controller: Gtk.GestureDrag, start: DragOffset, offset: () => DragOffset): (() => void) => {
+    const instance: DragInstancePatch = controller;
+
+    const saved: SavedDragState = {
+        instance,
+        ownsStartPoint: Object.hasOwn(instance, "getStartPoint"),
+        ownsOffset: Object.hasOwn(instance, "getOffset"),
+        previousStartPoint: instance.getStartPoint,
+        previousOffset: instance.getOffset,
+    };
+
+    instance.getStartPoint = () => [true, start.x, start.y];
+
+    instance.getOffset = () => {
+        const current = offset();
+
+        return [true, current.x, current.y];
+    };
+
+    return () => {
+        restoreDragState(saved);
+    };
+};
+
+const emitToControllers = (controllers: Gtk.GestureDrag[], signal: string, x: number, y: number): void => {
+    for (const controller of controllers) {
+        controller.emit(signal, x, y);
+    }
+};
+
+const runDragSequence = (controllers: Gtk.GestureDrag[], start: DragOffset, updates: DragOffset[]): void => {
+    let current: DragOffset = { x: 0, y: 0 };
+    const restores = controllers.map((controller) => patchDragState(controller, start, () => current));
+
+    try {
+        emitToControllers(controllers, "drag-begin", start.x, start.y);
+
+        for (const update of updates) {
+            current = update;
+            emitToControllers(controllers, "drag-update", update.x, update.y);
+        }
+
+        emitToControllers(controllers, "drag-end", current.x, current.y);
+    } finally {
+        for (const restore of restores) {
+            restore();
+        }
+    }
+};
+
+const resolveDragUpdates = (dx: number, dy: number, options: DragOptions): DragOffset[] => {
+    if (options.offsets) {
+        return [...options.offsets, { x: dx, y: dy }];
+    }
+
+    const steps = Math.max(1, Math.floor(options.steps ?? 2));
+    const updates: DragOffset[] = [];
+
+    for (let i = 1; i <= steps; i++) {
+        updates.push({ x: (dx * i) / steps, y: (dy * i) / steps });
+    }
+
+    return updates;
+};
+
+const drag = async (widget: Gtk.Widget, dx: number, dy: number, options: DragOptions = {}): Promise<void> => {
+    if (widget instanceof Gtk.Range) {
+        throw new TypeError(
+            "userEvent.drag cannot drive a Gtk.Range's built-in slider " +
+            "(its drag reads pointer coordinates from the display); " +
+            "use userEvent.slide(range, value) or userEvent.keyboard for sliders",
+        );
+    }
+
+    const start = { x: options.startX ?? 0, y: options.startY ?? 0 };
+    const updates = resolveDragUpdates(dx, dy, options);
+
+    await wrapEvent(widget, () => {
+        runDragSequence(getAllControllers(widget, Gtk.GestureDrag), start, updates);
+    });
+};
+
+const emitDrop = (target: Gtk.Widget, content: DropContent, options: DropOptions): void => {
+    const dropTargets = getAllControllers(target, Gtk.DropTarget);
+
+    for (const dropTarget of dropTargets) {
+        dropTarget.emit("drop", buildDropValue(content), options.x ?? 0, options.y ?? 0);
+    }
+};
+
+const drop = (widget: Gtk.Widget, content: DropContent, options: DropOptions = {}): Promise<void> =>
+    wrapEvent(widget, () => {
+        emitDrop(widget, content, options);
+    });
+
+const dragAndDrop = async (
+    source: Gtk.Widget,
+    target: Gtk.Widget,
+    content: DropContent,
+    options: DropOptions = {},
+): Promise<void> => {
+    await wrapEvent(source, () => {
+        getAllControllers(source, Gtk.DragSource);
+    });
+
+    await wrapEvent(target, () => {
+        emitDrop(target, content, options);
+    });
+};
+
+export {
+    hover,
+    unhover,
+    rotate,
+    zoom,
+    swipe,
+    longPress,
+    drag,
+    drop,
+    dragAndDrop,
+    type DropContent,
+    type DropOptions,
+    type DragOffset,
+    type DragOptions,
+};

package/src/user-event/index.ts

@@ -0,0 +1,81 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+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 { clear, copy, cut, paste, type } from "./text.js";
+
+/**
+ * The set of user interaction helpers exposed by {@link userEvent}, covering clicks, typing,
+ * keyboard, pointer, gestures, selection, and scrolling.
+ */
+type UserEvent = {
+    click: typeof click;
+    dblClick: typeof dblClick;
+    tripleClick: typeof tripleClick;
+    tab: typeof tab;
+    type: typeof type;
+    clear: typeof clear;
+    copy: typeof copy;
+    cut: typeof cut;
+    paste: typeof paste;
+    selectOptions: typeof selectOptions;
+    deselectOptions: typeof deselectOptions;
+    hover: typeof hover;
+    unhover: typeof unhover;
+    rotate: typeof rotate;
+    zoom: typeof zoom;
+    swipe: typeof swipe;
+    longPress: typeof longPress;
+    drag: typeof drag;
+    drop: typeof drop;
+    dragAndDrop: typeof dragAndDrop;
+    slide: typeof slide;
+    scroll: typeof scroll;
+    keyboard: (widget: Gtk.Widget, input: string) => Promise<void>;
+    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.
+ */
+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),
+};
+
+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 };