@gtkx/testing 0.20.0 → 1.0.0-rc.1

package/src/types.ts

@@ -1,210 +1,149 @@
-import type * as Gtk from "@gtkx/ffi/gtk";
-import type { ComponentType, ReactNode, Ref } from "react";
+import type * as Gtk from "@gtkx/gi/gtk";
+import type { RootElement } from "@gtkx/react";
+import type { ComponentType, ErrorInfo, ReactNode } from "react";
+import type { PrettyWidgetOptions } from "./pretty-widget.js";
 import type { Container } from "./traversal.js";
 
-/**
- * Custom function for matching text content.
- *
- * @param content - The normalized text content to match against
- * @param widget - The widget being tested
- * @returns `true` if the content matches
- */
-export type TextMatchFunction = (content: string, widget: Gtk.Widget) => boolean;
-
-/**
- * Text matching pattern.
- *
- * Can be a string for exact/substring matching, a RegExp for pattern matching,
- * or a custom function for advanced matching logic.
- */
-export type TextMatch = string | RegExp | TextMatchFunction;
-
-/**
- * Options for text normalization before matching.
- */
+/** A custom matcher predicate: given a candidate widget's normalized text content and the widget itself, returns whether it matches. */
+export type MatcherFunction = (content: string, widget: Gtk.Widget) => boolean;
+
+/** A value used to match widget text: a string or number, a regular expression, or a custom {@link MatcherFunction}. */
+export type Matcher = string | number | RegExp | MatcherFunction;
+
+/** Normalizes a widget's text before it is compared against a matcher. */
+export type NormalizerFn = (text: string) => string;
+
+/** Options controlling the default text normalizer. */
 export type NormalizerOptions = {
-    /** Remove leading/trailing whitespace (default: true) */
-    trim?: boolean;
-    /** Replace multiple whitespace characters with single space (default: true) */
-    collapseWhitespace?: boolean;
+    /** Trim leading and trailing whitespace. */
+    trim?: boolean | undefined;
+    /** Collapse runs of whitespace into a single space. */
+    collapseWhitespace?: boolean | undefined;
 };
 
-/**
- * Options for text-based queries.
- */
-export type TextMatchOptions = {
-    /** Require exact match vs substring match (default: true) */
-    exact?: boolean;
-    /** Custom text normalizer function */
-    normalizer?: (text: string) => string;
-    /** Remove leading/trailing whitespace (default: true) */
-    trim?: boolean;
-    /** Replace multiple whitespace with single space (default: true) */
-    collapseWhitespace?: boolean;
-    /** Timeout in milliseconds for async queries (default: 1000) */
-    timeout?: number;
+/** Options controlling how asynchronous queries and waits poll for a condition. */
+export type WaitForOptions = {
+    /** Maximum time in milliseconds to keep retrying before failing. */
+    timeout?: number | undefined;
+    /** Delay in milliseconds between retries. */
+    interval?: number | undefined;
+    /** Transforms the error thrown when the timeout elapses. */
+    onTimeout?: ((error: Error) => Error) | undefined;
+    /** Error whose stack trace attributes the timeout failure to the calling code. */
+    stackTraceError?: Error | undefined;
 };
 
-/**
- * Options for role-based queries.
- *
- * Extends text matching options with accessible state filters.
- */
-export type ByRoleOptions = TextMatchOptions & {
-    /** Filter by accessible name/label */
-    name?: TextMatch;
-    /** Filter by checked state (checkboxes, radios, toggles) */
-    checked?: boolean;
-    /** Filter by pressed state */
-    pressed?: boolean;
-    /** Filter by selected state */
-    selected?: boolean;
-    /** Filter by expanded state (expanders) */
-    expanded?: boolean;
-    /** Filter by heading level */
-    level?: number;
+/** Options controlling text matching and, for asynchronous queries, polling behavior. */
+export type MatcherOptions = {
+    /** When true (the default), require an exact match; when false, match case-insensitively as a substring. */
+    exact?: boolean | undefined;
+    /** Custom normalizer replacing the default; cannot be combined with `trim` or `collapseWhitespace`. */
+    normalizer?: NormalizerFn | undefined;
+    /** Forwarded to the default normalizer when no custom `normalizer` is given. */
+    trim?: boolean | undefined;
+    /** Forwarded to the default normalizer when no custom `normalizer` is given. */
+    collapseWhitespace?: boolean | undefined;
+    /** Whether to include a suggested better query in error messages. */
+    suggest?: boolean | undefined;
+} & WaitForOptions;
+
+/** Constraints on a widget's numeric range value used by role queries. */
+export type ByRoleValue = {
+    /** The current value. */
+    now?: number | undefined;
+    min?: number | undefined;
+    max?: number | undefined;
+    /** Matcher for the value's textual representation. */
+    text?: Matcher | undefined;
 };
 
-/**
- * Options for {@link waitFor} and {@link waitForElementToBeRemoved}.
- */
-export type WaitForOptions = {
-    /** Maximum time to wait in milliseconds (default: 1000) */
-    timeout?: number;
-    /** Polling interval in milliseconds (default: 50) */
-    interval?: number;
-    /** Custom error handler called on timeout */
-    onTimeout?: (error: Error) => Error;
+/** Options for role queries: an accessible name matcher plus accessible state and value constraints. */
+export type ByRoleOptions = MatcherOptions & {
+    name?: Matcher | undefined;
+    checked?: boolean | undefined;
+    pressed?: boolean | undefined;
+    selected?: boolean | undefined;
+    expanded?: boolean | undefined;
+    /** Heading or hierarchy level. */
+    level?: number | undefined;
+    busy?: boolean | undefined;
+    description?: Matcher | undefined;
+    value?: ByRoleValue | undefined;
+    /** When true, include widgets excluded from the accessibility tree. */
+    hidden?: boolean | undefined;
 };
 
-/**
- * A wrapper component that exposes its root GTK widget via `ref`.
- * Accept `ref` as a prop and pass it through to the root intrinsic element.
- */
+/** A React component that wraps rendered content, receiving it as its children. */
 export type WrapperComponent = ComponentType<{
     children: ReactNode;
-    ref?: Ref<Gtk.Widget>;
 }>;
 
-/**
- * Options for {@link render}.
- */
-export type RenderOptions = {
-    /**
-     * Wrapper component or boolean.
-     * - `true` (default): Wrap in GtkApplicationWindow
-     * - `false`: No wrapper
-     * - Component: Custom wrapper that passes `ref` to its root element
-     */
-    wrapper?: boolean | WrapperComponent;
-    /**
-     * The element queries are bound to.
-     * Defaults to the GTK Application (searches all toplevel windows).
-     * Provide a specific widget or application to scope queries.
-     */
-    baseElement?: Container;
-};
+type Query = (container: Container, ...args: never[]) => unknown;
+
+export type QueryMap = Record<string, Query>;
 
-/**
- * Query methods bound to a container.
- *
- * @see {@link screen} for global queries
- * @see {@link within} for scoped queries
- */
-export type BoundQueries = {
-    /** 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 (waits and throws if not found) */
-    findByLabelText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
-    /** 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 (waits and throws if not found) */
-    findByTestId: (testId: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
-    /** 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 (waits and throws if none found) */
-    findAllByLabelText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
-    /** 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 (waits and throws if none found) */
-    findAllByTestId: (testId: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
+type BoundQuery<Q extends Query> = Q extends (container: Container, ...args: infer A) => infer R
+    ? (...args: A) => R
+    : never;
+
+export type BoundCustomQueries<Q extends QueryMap> = { [K in keyof Q]: BoundQuery<Q[K]> };
+
+/** Options for {@link render}: the container and base element to mount into, an optional wrapper, React behavior toggles, error callbacks, and custom queries to bind. */
+export type RenderOptions<Q extends QueryMap = Record<never, never>> = {
+    container?: Gtk.Widget | RootElement | undefined;
+    /** Root of the subtree that bound queries search. */
+    baseElement?: Container | undefined;
+    wrapper?: WrapperComponent | undefined;
+    /** Render inside React StrictMode. */
+    reactStrictMode?: boolean | undefined;
+    /** Enable widget animations during the test. */
+    animations?: boolean | undefined;
+    /** Called for errors caught by React error boundaries. */
+    onCaughtError?: ((error: unknown, errorInfo: ErrorInfo) => void) | undefined;
+    /** Called for errors React recovered from automatically. */
+    onRecoverableError?: ((error: unknown, errorInfo: ErrorInfo) => void) | undefined;
+    /** Custom queries to bind to the rendered result. */
+    queries?: Q | undefined;
 };
 
-/**
- * Result returned by {@link render}.
- *
- * Provides query methods and utilities for testing rendered components.
- */
-export type RenderResult = BoundQueries & {
-    /** The direct container widget wrapping the rendered content */
-    container: Gtk.Widget;
-    /** The element queries are bound to (defaults to the GTK Application) */
-    baseElement: Container;
-    /** Unmount the rendered component */
-    unmount: () => Promise<void>;
-    /** Re-render with a new element */
-    rerender: (element: ReactNode) => Promise<void>;
-    /** Print the widget tree to console for debugging */
-    debug: () => void;
+export type DebugUtilities = {
+    debug: (element?: Container | Container[], options?: PrettyWidgetOptions) => void;
+    logRoles: () => void;
+    screenshot: (selector?: WindowSelector, options?: ScreenshotOptions) => Promise<ScreenshotResult>;
 };
 
-/**
- * Result returned by {@link screenshot} and screen.screenshot.
- */
+/** A captured screenshot: base64-encoded image data, its MIME type, and pixel dimensions. */
 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;
 };
 
-/**
- * Options for {@link renderHook}.
- */
-export type RenderHookOptions<Props> = {
-    /**
-     * Initial props passed to the hook callback.
-     */
-    initialProps?: Props;
-    /**
-     * Wrapper component or boolean.
-     * - `true` (default): Wrap in GtkApplicationWindow
-     * - `false`: No wrapper
-     * - Component: Custom wrapper that passes `ref` to its root element
-     */
-    wrapper?: boolean | WrapperComponent;
+/** Options for capturing a screenshot: the poll timeout and interval, plus a rendering scale factor. */
+export type ScreenshotOptions = Pick<WaitForOptions, "timeout" | "interval"> & {
+    /** Device scale factor applied when rendering. */
+    scale?: number;
 };
 
-/**
- * Result returned by {@link renderHook}.
- *
- * Provides access to the hook result and utilities for re-rendering and cleanup.
- */
+/** Selects the window to screenshot by index, or by title (exact string or regular expression); undefined targets the default window. */
+export type WindowSelector = number | string | RegExp | undefined;
+
+/** Options for {@link renderHook}: an optional wrapper and the initial props (required unless the props type permits undefined). */
+export type RenderHookOptions<Props> = {
+    wrapper?: WrapperComponent;
+} & (undefined extends Props
+    ? {
+          initialProps?: Props;
+      }
+    : {
+          initialProps: Props;
+      });
+
+/** The result of {@link renderHook}: the latest hook return value plus functions to rerender with new props and to unmount. */
 export type RenderHookResult<Result, Props> = {
-    /** Object containing the current hook return value */
+    /** Holds the most recent value returned by the hook under `current`. */
     result: { current: Result };
-    /** Re-render the hook with optional new props */
     rerender: (newProps?: Props) => Promise<void>;
-    /** Unmount the component containing the hook */
     unmount: () => Promise<void>;
 };

package/src/user-event/adjustment.ts

@@ -0,0 +1,49 @@
+import * as Gtk from "@gtkx/gi/gtk";
+import { wrapEvent } from "./event-wrapper.js";
+
+export type ScrollDelta = {
+    x?: number;
+    y?: number;
+};
+
+export const slide = (widget: Gtk.Widget, value: number): Promise<void> =>
+    wrapEvent(widget, () => {
+        if (!(widget instanceof Gtk.Range)) {
+            throw new Error(`userEvent.slide requires a Gtk.Range (e.g. Gtk.Scale), got ${widget.constructor.name}`);
+        }
+        widget.emit("change-value", Gtk.ScrollType.JUMP, value);
+    });
+
+type ScrollAdjustments = {
+    horizontal: Gtk.Adjustment | null;
+    vertical: Gtk.Adjustment | null;
+};
+
+const resolveScrollAdjustments = (widget: Gtk.Widget): ScrollAdjustments | null => {
+    for (let current: Gtk.Widget | null = widget; current; current = current.getParent()) {
+        if (current instanceof Gtk.ScrolledWindow) {
+            return { horizontal: current.getHadjustment(), vertical: current.getVadjustment() };
+        }
+        if (current instanceof Gtk.Scrollable) {
+            return { horizontal: current.getHadjustment(), vertical: current.getVadjustment() };
+        }
+    }
+    return null;
+};
+
+const applyScrollDelta = (adjustment: Gtk.Adjustment | null, delta: number): void => {
+    if (!adjustment || delta === 0) return;
+    adjustment.setValue(adjustment.getValue() + delta);
+};
+
+export const scroll = (widget: Gtk.Widget, delta: ScrollDelta): Promise<void> =>
+    wrapEvent(widget, () => {
+        const adjustments = resolveScrollAdjustments(widget);
+        if (!adjustments) {
+            throw new Error(
+                "userEvent.scroll: no Gtk.ScrolledWindow or Gtk.Scrollable found on the widget or its ancestors",
+            );
+        }
+        applyScrollDelta(adjustments.horizontal, delta.x ?? 0);
+        applyScrollDelta(adjustments.vertical, delta.y ?? 0);
+    });

package/src/user-event/click.ts

@@ -0,0 +1,70 @@
+import * as Gtk from "@gtkx/gi/gtk";
+import { getOrCreateControllers, queryController } from "./controller.js";
+import { wrapEvent } from "./event-wrapper.js";
+
+const pressPointOf = (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 };
+};
+
+export const emitPress = (widget: Gtk.Widget, controllers: Gtk.GestureClick[], nPress: number): void => {
+    const { x, y } = pressPointOf(widget);
+    for (const controller of controllers) {
+        controller.emit("pressed", nPress, x, y);
+    }
+};
+
+export const emitRelease = (widget: Gtk.Widget, controllers: Gtk.GestureClick[], nPress: number): void => {
+    const { x, y } = pressPointOf(widget);
+    for (const controller of controllers) {
+        controller.emit("released", nPress, x, y);
+    }
+};
+
+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;
+};
+
+export 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 (widget.getAccessibleRole() !== Gtk.AccessibleRole.LABEL) {
+        let activated = false;
+        await wrapEvent(widget, () => {
+            activated = widget.activate();
+        });
+        if (activated) return;
+    }
+    const target = findClickableAncestor(widget);
+    if (target) await emitClickSequence(widget, target, 1);
+};
+
+export const dblClick = (widget: Gtk.Widget): Promise<void> => emitClickSequence(widget, widget, 2);
+export const tripleClick = (widget: Gtk.Widget): Promise<void> => emitClickSequence(widget, widget, 3);

package/src/user-event/controller.ts

@@ -0,0 +1,44 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+
+export type ControllerConstructor<T extends Gtk.EventController> = new () => T;
+
+export 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;
+};
+
+export const queryController = <T extends Gtk.EventController>(
+    widget: Gtk.Widget,
+    controllerType: ControllerConstructor<T>,
+): T | null => queryAllControllers(widget, controllerType)[0] ?? null;
+
+export 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;
+};
+
+export 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];
+};

package/src/user-event/dispatch.ts

@@ -0,0 +1,23 @@
+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);
+    }
+};
+
+export const dispatchOnOrCreateControllers = <T extends Gtk.EventController>(
+    widget: Gtk.Widget,
+    controllerType: ControllerConstructor<T>,
+    emit: ControllerEmit<T>,
+): Promise<void> => wrapEvent(widget, () => emitOnAll(getOrCreateControllers(widget, controllerType), emit));
+
+export const dispatchOnControllers = <T extends Gtk.EventController>(
+    widget: Gtk.Widget,
+    controllerType: ControllerConstructor<T>,
+    emit: ControllerEmit<T>,
+): Promise<void> => wrapEvent(widget, () => emitOnAll(getAllControllers(widget, controllerType), emit));

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

@@ -0,0 +1,54 @@
+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 displayDeliversActivation = (window: Gtk.Window): boolean => window.getDisplay().getDefaultSeat() !== 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;
+    if (root.getAllocatedWidth() === 0) return WINDOW_NOT_ALLOCATED;
+    if (!widget.getMapped()) return NOT_MAPPED;
+    if (displayDeliversActivation(root) && !root.isActive()) return WINDOW_NOT_ACTIVE;
+    return null;
+};
+
+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 ${timeout}ms because ${failure}`,
+        );
+    }
+};
+
+export const wrapEvent = (widget: Gtk.Widget, body: () => void | PromiseLike<void>): Promise<void> =>
+    Promise.resolve()
+        .then(() => waitForActionable(widget))
+        .then(() =>
+            runInAct(async () => {
+                await body();
+            }),
+        );