@gtkx/testing 0.11.1 → 0.12.0

package/dist/screen.d.ts

@@ -1,5 +1,6 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
-import type { ByRoleOptions, TextMatch, TextMatchOptions } from "./types.js";
+import { type ScreenshotOptions } from "./screenshot.js";
+import type { ScreenshotResult } from "./types.js";
 /** @internal */
 export declare const setScreenRoot: (root: Gtk.Application | null) => void;
 /**
@@ -23,22 +24,42 @@ export declare const setScreenRoot: (root: Gtk.Application | null) => void;
  * @see {@link within} for scoped queries
  */
 export declare const screen: {
-    /** Find single element by accessible role */
-    findByRole: (role: Gtk.AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget>;
-    /** Find single element by label/text content */
-    findByLabelText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
-    /** Find single element by visible text */
-    findByText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
-    /** Find single element by test ID (widget name) */
-    findByTestId: (testId: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
-    /** Find all elements by accessible role */
-    findAllByRole: (role: Gtk.AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget[]>;
-    /** Find all elements by label/text content */
-    findAllByLabelText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
-    /** Find all elements by visible text */
-    findAllByText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
-    /** Find all elements by test ID (widget name) */
-    findAllByTestId: (testId: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
-    /** Print debug info to console */
+    /** Print the widget tree to console for debugging */
     debug: () => void;
+    /** Log all accessible roles to console for debugging */
+    logRoles: () => void;
+    /**
+     * Capture a screenshot of the application window, saving it to a temporary file and logging the file path.
+     *
+     * @param selector - Window selector: index (number), title substring (string), or title pattern (RegExp).
+     *                   If omitted, captures the first window.
+     * @param options - Optional timeout and interval configuration for waiting on widget rendering.
+     * @returns Screenshot result containing base64-encoded PNG data
+     * @throws Error if no windows are available or no matching window is found
+     *
+     * @example
+     * ```tsx
+     * await screen.screenshot();              // First window
+     * await screen.screenshot(0);             // Window at index 0
+     * await screen.screenshot("Settings");    // Window with title containing "Settings"
+     * await screen.screenshot(/^My App/);     // Window with title matching regex
+     * ```
+     */
+    screenshot: (selector?: number | string | RegExp, options?: ScreenshotOptions) => Promise<ScreenshotResult>;
+    queryByRole: (role: Gtk.AccessibleRole, options?: import("./types.js").ByRoleOptions) => Gtk.Widget | null;
+    queryByLabelText: (text: import("./types.js").TextMatch, options?: import("./types.js").TextMatchOptions) => Gtk.Widget | null;
+    queryByText: (text: import("./types.js").TextMatch, options?: import("./types.js").TextMatchOptions) => Gtk.Widget | null;
+    queryByTestId: (testId: import("./types.js").TextMatch, options?: import("./types.js").TextMatchOptions) => Gtk.Widget | null;
+    queryAllByRole: (role: Gtk.AccessibleRole, options?: import("./types.js").ByRoleOptions) => Gtk.Widget[];
+    queryAllByLabelText: (text: import("./types.js").TextMatch, options?: import("./types.js").TextMatchOptions) => Gtk.Widget[];
+    queryAllByText: (text: import("./types.js").TextMatch, options?: import("./types.js").TextMatchOptions) => Gtk.Widget[];
+    queryAllByTestId: (testId: import("./types.js").TextMatch, options?: import("./types.js").TextMatchOptions) => Gtk.Widget[];
+    findByRole: (role: Gtk.AccessibleRole, options?: import("./types.js").ByRoleOptions) => Promise<Gtk.Widget>;
+    findByLabelText: (text: import("./types.js").TextMatch, options?: import("./types.js").TextMatchOptions) => Promise<Gtk.Widget>;
+    findByText: (text: import("./types.js").TextMatch, options?: import("./types.js").TextMatchOptions) => Promise<Gtk.Widget>;
+    findByTestId: (testId: import("./types.js").TextMatch, options?: import("./types.js").TextMatchOptions) => Promise<Gtk.Widget>;
+    findAllByRole: (role: Gtk.AccessibleRole, options?: import("./types.js").ByRoleOptions) => Promise<Gtk.Widget[]>;
+    findAllByLabelText: (text: import("./types.js").TextMatch, options?: import("./types.js").TextMatchOptions) => Promise<Gtk.Widget[]>;
+    findAllByText: (text: import("./types.js").TextMatch, options?: import("./types.js").TextMatchOptions) => Promise<Gtk.Widget[]>;
+    findAllByTestId: (testId: import("./types.js").TextMatch, options?: import("./types.js").TextMatchOptions) => Promise<Gtk.Widget[]>;
 };

package/dist/screen.js

@@ -1,4 +1,25 @@
-import * as queries from "./queries.js";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { bindQueries } from "./bind-queries.js";
+import { prettyWidget } from "./pretty-widget.js";
+import { logRoles } from "./role-helpers.js";
+import { screenshot as screenshotWidget } from "./screenshot.js";
+const getScreenshotDir = () => {
+    const dir = join(tmpdir(), "gtkx-screenshots");
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+};
+const saveAndLogScreenshot = (result) => {
+    const dir = getScreenshotDir();
+    const filename = `${Date.now()}-screenshot.png`;
+    const filepath = join(dir, filename);
+    const buffer = Buffer.from(result.data, "base64");
+    writeFileSync(filepath, buffer);
+    console.log(`Screenshot saved: file://${filepath}`);
+};
 let currentRoot = null;
 /** @internal */
 export const setScreenRoot = (root) => {
@@ -10,6 +31,7 @@ const getRoot = () => {
     }
     return currentRoot;
 };
+const boundQueries = bindQueries(getRoot);
 /**
  * Global query object for accessing rendered components.
  *
@@ -31,24 +53,61 @@ const getRoot = () => {
  * @see {@link within} for scoped queries
  */
 export const screen = {
-    /** Find single element by accessible role */
-    findByRole: (role, options) => queries.findByRole(getRoot(), role, options),
-    /** Find single element by label/text content */
-    findByLabelText: (text, options) => queries.findByLabelText(getRoot(), text, options),
-    /** Find single element by visible text */
-    findByText: (text, options) => queries.findByText(getRoot(), text, options),
-    /** Find single element by test ID (widget name) */
-    findByTestId: (testId, options) => queries.findByTestId(getRoot(), testId, options),
-    /** Find all elements by accessible role */
-    findAllByRole: (role, options) => queries.findAllByRole(getRoot(), role, options),
-    /** Find all elements by label/text content */
-    findAllByLabelText: (text, options) => queries.findAllByLabelText(getRoot(), text, options),
-    /** Find all elements by visible text */
-    findAllByText: (text, options) => queries.findAllByText(getRoot(), text, options),
-    /** Find all elements by test ID (widget name) */
-    findAllByTestId: (testId, options) => queries.findAllByTestId(getRoot(), testId, options),
-    /** Print debug info to console */
+    ...boundQueries,
+    /** Print the widget tree to console for debugging */
     debug: () => {
-        console.log("Screen debug - root:", getRoot());
+        console.log(prettyWidget(getRoot()));
+    },
+    /** Log all accessible roles to console for debugging */
+    logRoles: () => {
+        logRoles(getRoot());
+    },
+    /**
+     * Capture a screenshot of the application window, saving it to a temporary file and logging the file path.
+     *
+     * @param selector - Window selector: index (number), title substring (string), or title pattern (RegExp).
+     *                   If omitted, captures the first window.
+     * @param options - Optional timeout and interval configuration for waiting on widget rendering.
+     * @returns Screenshot result containing base64-encoded PNG data
+     * @throws Error if no windows are available or no matching window is found
+     *
+     * @example
+     * ```tsx
+     * await screen.screenshot();              // First window
+     * await screen.screenshot(0);             // Window at index 0
+     * await screen.screenshot("Settings");    // Window with title containing "Settings"
+     * await screen.screenshot(/^My App/);     // Window with title matching regex
+     * ```
+     */
+    screenshot: async (selector, options) => {
+        const root = getRoot();
+        const windows = root.getWindows();
+        if (windows.length === 0) {
+            throw new Error("No windows available for screenshot");
+        }
+        let targetWindow;
+        if (selector === undefined) {
+            targetWindow = windows[0];
+        }
+        else if (typeof selector === "number") {
+            targetWindow = windows[selector];
+            if (!targetWindow) {
+                throw new Error(`Window at index ${selector} not found`);
+            }
+        }
+        else {
+            const isRegex = selector instanceof RegExp;
+            targetWindow = windows.find((w) => {
+                const title = w.getTitle() ?? "";
+                return isRegex ? selector.test(title) : title.includes(selector);
+            });
+            if (!targetWindow) {
+                const pattern = isRegex ? selector.toString() : `"${selector}"`;
+                throw new Error(`No window found with title matching ${pattern}`);
+            }
+        }
+        const result = await screenshotWidget(targetWindow, options);
+        saveAndLogScreenshot(result);
+        return result;
     },
 };

package/dist/screenshot.d.ts

@@ -0,0 +1,26 @@
+import * as Gtk from "@gtkx/ffi/gtk";
+import type { ScreenshotResult, WaitForOptions } from "./types.js";
+export type ScreenshotOptions = Pick<WaitForOptions, "timeout" | "interval">;
+/**
+ * Captures a screenshot of a GTK widget as a PNG image.
+ *
+ * This function will retry multiple times if the widget hasn't finished
+ * rendering, waiting for GTK to complete its paint cycle.
+ *
+ * @param widget - The widget to capture (typically a Window)
+ * @param options - Optional timeout and interval configuration
+ * @returns Screenshot result containing base64-encoded PNG data and dimensions
+ * @throws Error if widget has no size, is not realized, or rendering fails after timeout
+ *
+ * @example
+ * ```tsx
+ * import { render, screenshot } from "@gtkx/testing";
+ * import * as Gtk from "@gtkx/ffi/gtk";
+ *
+ * const { container } = await render(<MyApp />);
+ * const window = container.getWindows()[0];
+ * const result = await screenshot(window);
+ * console.log(result.mimeType); // "image/png"
+ * ```
+ */
+export declare const screenshot: (widget: Gtk.Widget, options?: ScreenshotOptions) => Promise<ScreenshotResult>;

package/dist/screenshot.js

@@ -0,0 +1,86 @@
+import { createRef } from "@gtkx/ffi";
+import * as Gsk from "@gtkx/ffi/gsk";
+import * as Gtk from "@gtkx/ffi/gtk";
+import { tick } from "./timing.js";
+import { waitFor } from "./wait-for.js";
+const bytesToBase64 = (bytes) => {
+    return Buffer.from(bytes).toString("base64");
+};
+const DEFAULT_SCREENSHOT_TIMEOUT = 100;
+const DEFAULT_SCREENSHOT_INTERVAL = 10;
+const captureSnapshot = (widget) => {
+    const paintable = new Gtk.WidgetPaintable(widget);
+    const width = paintable.getIntrinsicWidth();
+    const height = paintable.getIntrinsicHeight();
+    if (width <= 0 || height <= 0) {
+        throw new Error("Widget has no size - ensure it is realized and visible");
+    }
+    const snapshot = new Gtk.Snapshot();
+    paintable.snapshot(snapshot, width, height);
+    const renderNode = snapshot.toNode();
+    if (!renderNode) {
+        throw new Error("Widget produced no render content");
+    }
+    const display = widget.getDisplay();
+    if (!display) {
+        throw new Error("Widget has no display - ensure it is realized");
+    }
+    const renderer = new Gsk.CairoRenderer();
+    renderer.realizeForDisplay(display);
+    try {
+        const texture = renderer.renderTexture(renderNode);
+        const pngBytes = texture.saveToPngBytes();
+        const sizeRef = createRef(0);
+        const data = pngBytes.getData(sizeRef);
+        if (!data) {
+            throw new Error("Failed to serialize screenshot to PNG");
+        }
+        return {
+            data: bytesToBase64(data),
+            mimeType: "image/png",
+            width,
+            height,
+        };
+    }
+    finally {
+        renderer.unrealize();
+    }
+};
+/**
+ * Captures a screenshot of a GTK widget as a PNG image.
+ *
+ * This function will retry multiple times if the widget hasn't finished
+ * rendering, waiting for GTK to complete its paint cycle.
+ *
+ * @param widget - The widget to capture (typically a Window)
+ * @param options - Optional timeout and interval configuration
+ * @returns Screenshot result containing base64-encoded PNG data and dimensions
+ * @throws Error if widget has no size, is not realized, or rendering fails after timeout
+ *
+ * @example
+ * ```tsx
+ * import { render, screenshot } from "@gtkx/testing";
+ * import * as Gtk from "@gtkx/ffi/gtk";
+ *
+ * const { container } = await render(<MyApp />);
+ * const window = container.getWindows()[0];
+ * const result = await screenshot(window);
+ * console.log(result.mimeType); // "image/png"
+ * ```
+ */
+export const screenshot = async (widget, options) => {
+    await tick();
+    return waitFor(() => captureSnapshot(widget), {
+        timeout: options?.timeout ?? DEFAULT_SCREENSHOT_TIMEOUT,
+        interval: options?.interval ?? DEFAULT_SCREENSHOT_INTERVAL,
+        onTimeout: (error) => {
+            const paintable = new Gtk.WidgetPaintable(widget);
+            const width = paintable.getIntrinsicWidth();
+            const height = paintable.getIntrinsicHeight();
+            if (width <= 0 || height <= 0) {
+                return new Error("Widget has no size - ensure it is realized and visible");
+            }
+            return new Error(`Widget produced no render content after waiting for paint cycle. ${error.message}`);
+        },
+    });
+};

package/dist/traversal.d.ts

@@ -1,4 +1,5 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
-type Container = Gtk.Application | Gtk.Widget;
+export type Container = Gtk.Application | Gtk.Widget;
+export declare const isApplication: (container: Container) => container is Gtk.Application;
+export declare const traverse: (container: Container) => Generator<Gtk.Widget>;
 export declare const findAll: (container: Container, predicate: (node: Gtk.Widget) => boolean) => Gtk.Widget[];
-export {};

package/dist/traversal.js

@@ -1,4 +1,4 @@
-const isApplication = (container) => "getWindows" in container && typeof container.getWindows === "function";
+export const isApplication = (container) => "getWindows" in container && typeof container.getWindows === "function";
 const traverseWidgetTree = function* (root) {
     yield root;
     let child = root.getFirstChild();
@@ -13,7 +13,7 @@ const traverseApplication = function* (app) {
         yield* traverseWidgetTree(window);
     }
 };
-const traverse = function* (container) {
+export const traverse = function* (container) {
     if (isApplication(container)) {
         yield* traverseApplication(container);
     }

package/dist/types.d.ts

@@ -90,21 +90,37 @@ export type RenderOptions = {
  * @see {@link within} for scoped queries
  */
 export type BoundQueries = {
-    /** Find single element by accessible role */
+    /** Query single element by accessible role (returns null if not found) */
+    queryByRole: (role: Gtk.AccessibleRole, options?: ByRoleOptions) => Gtk.Widget | null;
+    /** Query single element by label/text content (returns null if not found) */
+    queryByLabelText: (text: TextMatch, options?: TextMatchOptions) => Gtk.Widget | null;
+    /** Query single element by visible text (returns null if not found) */
+    queryByText: (text: TextMatch, options?: TextMatchOptions) => Gtk.Widget | null;
+    /** Query single element by test ID (returns null if not found) */
+    queryByTestId: (testId: TextMatch, options?: TextMatchOptions) => Gtk.Widget | null;
+    /** Query all elements by accessible role (returns empty array if none found) */
+    queryAllByRole: (role: Gtk.AccessibleRole, options?: ByRoleOptions) => Gtk.Widget[];
+    /** Query all elements by label/text content (returns empty array if none found) */
+    queryAllByLabelText: (text: TextMatch, options?: TextMatchOptions) => Gtk.Widget[];
+    /** Query all elements by visible text (returns empty array if none found) */
+    queryAllByText: (text: TextMatch, options?: TextMatchOptions) => Gtk.Widget[];
+    /** Query all elements by test ID (returns empty array if none found) */
+    queryAllByTestId: (testId: TextMatch, options?: TextMatchOptions) => Gtk.Widget[];
+    /** Find single element by accessible role (waits and throws if not found) */
     findByRole: (role: Gtk.AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget>;
-    /** Find single element by label/text content */
+    /** Find single element by label/text content (waits and throws if not found) */
     findByLabelText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
-    /** Find single element by visible text */
+    /** Find single element by visible text (waits and throws if not found) */
     findByText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
-    /** Find single element by test ID (widget name) */
+    /** Find single element by test ID (waits and throws if not found) */
     findByTestId: (testId: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
-    /** Find all elements by accessible role */
+    /** Find all elements by accessible role (waits and throws if none found) */
     findAllByRole: (role: Gtk.AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget[]>;
-    /** Find all elements by label/text content */
+    /** Find all elements by label/text content (waits and throws if none found) */
     findAllByLabelText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
-    /** Find all elements by visible text */
+    /** Find all elements by visible text (waits and throws if none found) */
     findAllByText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
-    /** Find all elements by test ID (widget name) */
+    /** Find all elements by test ID (waits and throws if none found) */
     findAllByTestId: (testId: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
 };
 /**
@@ -122,3 +138,16 @@ export type RenderResult = BoundQueries & {
     /** Print the widget tree to console for debugging */
     debug: () => void;
 };
+/**
+ * Result returned by {@link screenshot} and screen.screenshot.
+ */
+export type ScreenshotResult = {
+    /** Base64-encoded PNG image data */
+    data: string;
+    /** MIME type of the image (always "image/png") */
+    mimeType: string;
+    /** Width of the captured image in pixels */
+    width: number;
+    /** Height of the captured image in pixels */
+    height: number;
+};

package/dist/user-event.d.ts

@@ -6,6 +6,7 @@ export type TabOptions = {
     /** Navigate backwards (Shift+Tab) instead of forwards */
     shift?: boolean;
 };
+export type PointerInput = "click" | "down" | "up" | "[MouseLeft]" | "[MouseLeft>]" | "[/MouseLeft]";
 /**
  * User interaction utilities for testing.
  *
@@ -47,12 +48,6 @@ export declare const userEvent: {
      * Emits three consecutive clicked signals. Useful for text selection.
      */
     tripleClick: (element: Gtk.Widget) => Promise<void>;
-    /**
-     * Activates a widget.
-     *
-     * Calls the widget's activate method.
-     */
-    activate: (element: Gtk.Widget) => Promise<void>;
     /**
      * Simulates Tab key navigation.
      *
@@ -94,4 +89,42 @@ export declare const userEvent: {
      * @param values - Index or array of indices to deselect
      */
     deselectOptions: (element: Gtk.Widget, values: number | number[]) => Promise<void>;
+    /**
+     * Simulates mouse entering a widget (hover).
+     *
+     * Triggers the "enter" signal on the widget's EventControllerMotion.
+     */
+    hover: (element: Gtk.Widget) => Promise<void>;
+    /**
+     * Simulates mouse leaving a widget (unhover).
+     *
+     * Triggers the "leave" signal on the widget's EventControllerMotion.
+     */
+    unhover: (element: Gtk.Widget) => Promise<void>;
+    /**
+     * Simulates keyboard input.
+     *
+     * Supports special keys in braces: `{Enter}`, `{Tab}`, `{Escape}`, etc.
+     * Use `{Key>}` to hold a key down, `{/Key}` to release.
+     *
+     * @example
+     * ```tsx
+     * await userEvent.keyboard(element, "hello");
+     * await userEvent.keyboard(element, "{Enter}");
+     * await userEvent.keyboard(element, "{Shift>}A{/Shift}");
+     * ```
+     */
+    keyboard: (element: Gtk.Widget, input: string) => Promise<void>;
+    /**
+     * Simulates pointer (mouse) input.
+     *
+     * Supports: `"click"`, `"[MouseLeft]"`, `"down"`, `"up"`.
+     *
+     * @example
+     * ```tsx
+     * await userEvent.pointer(element, "click");
+     * await userEvent.pointer(element, "[MouseLeft]");
+     * ```
+     */
+    pointer: (element: Gtk.Widget, input: PointerInput) => Promise<void>;
 };

package/dist/user-event.js

@@ -1,5 +1,7 @@
 import { getNativeObject } from "@gtkx/ffi";
+import * as Gdk from "@gtkx/ffi/gdk";
 import * as Gtk from "@gtkx/ffi/gtk";
+import { call } from "@gtkx/native";
 import { fireEvent } from "./fire-event.js";
 import { tick } from "./timing.js";
 import { isEditable } from "./widget.js";
@@ -42,15 +44,11 @@ const tripleClick = async (element) => {
     await fireEvent(element, "clicked");
     await fireEvent(element, "clicked");
 };
-const activate = async (element) => {
-    element.activate();
-    await tick();
-};
 const tab = async (element, options) => {
     const direction = options?.shift ? Gtk.DirectionType.TAB_BACKWARD : Gtk.DirectionType.TAB_FORWARD;
     const root = element.getRoot();
     if (root) {
-        getNativeObject(root.id).childFocus(direction);
+        getNativeObject(root.handle).childFocus(direction);
     }
     await tick();
 };
@@ -58,7 +56,7 @@ const type = async (element, text) => {
     if (!isEditable(element)) {
         throw new Error("Cannot type into element: expected editable widget (TEXT_BOX, SEARCH_BOX, or SPIN_BUTTON)");
     }
-    const editable = getNativeObject(element.id, Gtk.Editable);
+    const editable = getNativeObject(element.handle, Gtk.Editable);
     const currentText = editable.getText();
     editable.setText(currentText + text);
     await tick();
@@ -67,7 +65,7 @@ const clear = async (element) => {
     if (!isEditable(element)) {
         throw new Error("Cannot clear element: expected editable widget (TEXT_BOX, SEARCH_BOX, or SPIN_BUTTON)");
     }
-    getNativeObject(element.id, Gtk.Editable)?.setText("");
+    getNativeObject(element.handle, Gtk.Editable)?.setText("");
     await tick();
 };
 const SELECTABLE_ROLES = new Set([Gtk.AccessibleRole.COMBO_BOX, Gtk.AccessibleRole.LIST]);
@@ -155,6 +153,123 @@ const deselectOptions = async (element, values) => {
     }
     await tick();
 };
+const getOrCreateController = (element, controllerType) => {
+    const controllers = element.observeControllers();
+    const nItems = controllers.getNItems();
+    for (let i = 0; i < nItems; i++) {
+        const controller = controllers.getObject(i);
+        if (controller instanceof controllerType) {
+            return controller;
+        }
+    }
+    const controller = new controllerType();
+    element.addController(controller);
+    return controller;
+};
+const emitSignal = (target, signalName, ...args) => {
+    const signalArgs = args.map((arg) => {
+        if (arg.type === "float") {
+            return { type: { type: "float", size: 64 }, value: arg.value };
+        }
+        return { type: { type: "int", size: 32, unsigned: true }, value: arg.value };
+    });
+    call("libgobject-2.0.so.0", "g_signal_emit_by_name", [
+        { type: { type: "gobject", ownership: "borrowed" }, value: target.handle },
+        { type: { type: "string", ownership: "borrowed" }, value: signalName },
+        ...signalArgs,
+    ], { type: "undefined" });
+};
+const hover = async (element) => {
+    const controller = getOrCreateController(element, Gtk.EventControllerMotion);
+    emitSignal(controller, "enter", { type: "float", value: 0 }, { type: "float", value: 0 });
+    await tick();
+};
+const unhover = async (element) => {
+    const controller = getOrCreateController(element, Gtk.EventControllerMotion);
+    emitSignal(controller, "leave");
+    await tick();
+};
+const KEY_MAP = {
+    Enter: Gdk.KEY_Return,
+    Tab: Gdk.KEY_Tab,
+    Escape: Gdk.KEY_Escape,
+    Backspace: Gdk.KEY_BackSpace,
+    Delete: Gdk.KEY_Delete,
+    ArrowUp: Gdk.KEY_Up,
+    ArrowDown: Gdk.KEY_Down,
+    ArrowLeft: Gdk.KEY_Left,
+    ArrowRight: Gdk.KEY_Right,
+    Home: Gdk.KEY_Home,
+    End: Gdk.KEY_End,
+    PageUp: Gdk.KEY_Page_Up,
+    PageDown: Gdk.KEY_Page_Down,
+    Space: Gdk.KEY_space,
+    Shift: Gdk.KEY_Shift_L,
+    Control: Gdk.KEY_Control_L,
+    Alt: Gdk.KEY_Alt_L,
+    Meta: Gdk.KEY_Meta_L,
+};
+const parseKeyboardInput = (input) => {
+    const actions = [];
+    let i = 0;
+    while (i < input.length) {
+        if (input[i] === "{") {
+            const endBrace = input.indexOf("}", i);
+            if (endBrace === -1)
+                break;
+            let keyName = input.slice(i + 1, endBrace);
+            let press = true;
+            let release = true;
+            if (keyName.startsWith("/")) {
+                keyName = keyName.slice(1);
+                press = false;
+            }
+            else if (keyName.endsWith(">")) {
+                keyName = keyName.slice(0, -1);
+                release = false;
+            }
+            const keyval = KEY_MAP[keyName];
+            if (keyval === undefined) {
+                throw new Error(`Unknown key: {${keyName}}`);
+            }
+            if (press)
+                actions.push({ keyval, press: true });
+            if (release)
+                actions.push({ keyval, press: false });
+            i = endBrace + 1;
+        }
+        else {
+            const keyval = input.charCodeAt(i);
+            actions.push({ keyval, press: true });
+            actions.push({ keyval, press: false });
+            i++;
+        }
+    }
+    return actions;
+};
+const keyboard = async (element, input) => {
+    const controller = getOrCreateController(element, Gtk.EventControllerKey);
+    const actions = parseKeyboardInput(input);
+    for (const action of actions) {
+        const signalName = action.press ? "key-pressed" : "key-released";
+        emitSignal(controller, signalName, { type: "int", value: action.keyval }, { type: "int", value: 0 }, { type: "int", value: 0 });
+    }
+    await tick();
+};
+const pointer = async (element, input) => {
+    const controller = getOrCreateController(element, Gtk.GestureClick);
+    if (input === "[MouseLeft]" || input === "click") {
+        emitSignal(controller, "pressed", { type: "int", value: 1 }, { type: "float", value: 0 }, { type: "float", value: 0 });
+        emitSignal(controller, "released", { type: "int", value: 1 }, { type: "float", value: 0 }, { type: "float", value: 0 });
+    }
+    else if (input === "[MouseLeft>]" || input === "down") {
+        emitSignal(controller, "pressed", { type: "int", value: 1 }, { type: "float", value: 0 }, { type: "float", value: 0 });
+    }
+    else if (input === "[/MouseLeft]" || input === "up") {
+        emitSignal(controller, "released", { type: "int", value: 1 }, { type: "float", value: 0 }, { type: "float", value: 0 });
+    }
+    await tick();
+};
 /**
  * User interaction utilities for testing.
  *
@@ -196,12 +311,6 @@ export const userEvent = {
      * Emits three consecutive clicked signals. Useful for text selection.
      */
     tripleClick,
-    /**
-     * Activates a widget.
-     *
-     * Calls the widget's activate method.
-     */
-    activate,
     /**
      * Simulates Tab key navigation.
      *
@@ -243,4 +352,42 @@ export const userEvent = {
      * @param values - Index or array of indices to deselect
      */
     deselectOptions,
+    /**
+     * Simulates mouse entering a widget (hover).
+     *
+     * Triggers the "enter" signal on the widget's EventControllerMotion.
+     */
+    hover,
+    /**
+     * Simulates mouse leaving a widget (unhover).
+     *
+     * Triggers the "leave" signal on the widget's EventControllerMotion.
+     */
+    unhover,
+    /**
+     * Simulates keyboard input.
+     *
+     * Supports special keys in braces: `{Enter}`, `{Tab}`, `{Escape}`, etc.
+     * Use `{Key>}` to hold a key down, `{/Key}` to release.
+     *
+     * @example
+     * ```tsx
+     * await userEvent.keyboard(element, "hello");
+     * await userEvent.keyboard(element, "{Enter}");
+     * await userEvent.keyboard(element, "{Shift>}A{/Shift}");
+     * ```
+     */
+    keyboard,
+    /**
+     * Simulates pointer (mouse) input.
+     *
+     * Supports: `"click"`, `"[MouseLeft]"`, `"down"`, `"up"`.
+     *
+     * @example
+     * ```tsx
+     * await userEvent.pointer(element, "click");
+     * await userEvent.pointer(element, "[MouseLeft]");
+     * ```
+     */
+    pointer,
 };