@gtkx/testing 0.21.0 → 1.0.0-rc.2

package/src/suggestions.ts

@@ -0,0 +1,106 @@
+import * as Gtk from "@gtkx/gi/gtk";
+import { formatRole } from "./role-helpers.js";
+import {
+    getWidgetAccessibleName,
+    getWidgetDisplayValue,
+    getWidgetLabelledByText,
+    getWidgetLabelText,
+    getWidgetName,
+    getWidgetOwnLabel,
+    getWidgetPlaceholderText,
+} from "./widget-accessible-properties.js";
+
+/** The query variant a suggestion targets. */
+type Variant = "get" | "getAll" | "query" | "queryAll" | "find" | "findAll";
+/** The query family a suggestion targets. */
+type Method = "Role" | "LabelText" | "PlaceholderText" | "Text" | "DisplayValue" | "Name";
+
+/**
+ * A suggested query for reaching a widget, including its family, variant, method name, and a
+ * `toString` that renders the full call.
+ */
+type Suggestion = {
+    queryName: Method;
+    /** The full query function name, such as `getByRole`. */
+    queryMethod: string;
+    variant: Variant;
+    toString: () => string;
+};
+
+const makeSuggestion = (queryName: Method, variant: Variant, argsText: string): Suggestion => {
+    const queryMethod = `${variant}By${queryName}`;
+
+    return {
+        queryName,
+        queryMethod,
+        variant,
+        toString: () => `${queryMethod}(${argsText})`,
+    };
+};
+
+const roleSuggestion = (widget: Gtk.Widget, variant: Variant): Suggestion | undefined => {
+    const role = widget.getAccessibleRole();
+
+    if (role === Gtk.AccessibleRole.NONE || role === Gtk.AccessibleRole.GENERIC) {
+        return undefined;
+    }
+
+    const roleText = `Gtk.AccessibleRole.${formatRole(role).toUpperCase()}`;
+    const name = getWidgetAccessibleName(widget);
+
+    if (name === null) {
+        return makeSuggestion("Role", variant, roleText);
+    }
+
+    return makeSuggestion("Role", variant, `${roleText}, { name: '${name}' }`);
+};
+
+const textSuggestion = (queryName: Method, variant: Variant, value: string | null): Suggestion | undefined => {
+    if (value === null) {
+        return undefined;
+    }
+
+    return makeSuggestion(queryName, variant, `'${value}'`);
+};
+
+/**
+ * Computes the recommended query for reaching the given widget, preferring role, then label text,
+ * placeholder text, text, display value, and name.
+ * @param widget Widget to build a suggestion for.
+ * @param variant Query variant the suggestion should use.
+ * @param method Restrict the suggestion to a specific query family instead of choosing by priority.
+ * @returns The best available suggestion, or undefined when no query applies.
+ */
+const getSuggestedQuery = (
+    widget: Gtk.Widget,
+    variant: Variant = "get",
+    method?: Method,
+): Suggestion | undefined => {
+    const builders: Record<Method, () => Suggestion | undefined> = {
+        Role: () => roleSuggestion(widget, variant),
+        LabelText: () =>
+            textSuggestion("LabelText", variant, getWidgetOwnLabel(widget) ?? getWidgetLabelledByText(widget)),
+        PlaceholderText: () => textSuggestion("PlaceholderText", variant, getWidgetPlaceholderText(widget)),
+        Text: () => textSuggestion("Text", variant, getWidgetLabelText(widget)),
+        DisplayValue: () => textSuggestion("DisplayValue", variant, getWidgetDisplayValue(widget)),
+        Name: () => textSuggestion("Name", variant, getWidgetName(widget)),
+    };
+
+    if (method) {
+        return builders[method]();
+    }
+
+    const priority: Method[] = ["Role", "LabelText", "PlaceholderText", "Text", "DisplayValue", "Name"];
+
+    for (const candidate of priority) {
+        const suggestion = builders[candidate]();
+
+        if (suggestion) {
+            return suggestion;
+        }
+    }
+
+    return undefined;
+};
+
+export { getSuggestedQuery, type Variant, type Method, type Suggestion };

package/src/traversal.ts

@@ -1,49 +1,83 @@
-import * as Gtk from "@gtkx/ffi/gtk";
+import * as Gtk from "@gtkx/gi/gtk";
 
+type QueryContainer = Gtk.Widget | Gtk.EventController | Gtk.LayoutManager | Gtk.ListItem | Gtk.ListHeader;
 /**
- * Root element for scoping queries.
- *
- * When a `Gtk.Application` is provided, queries search across all toplevel
- * windows. When a `Gtk.Widget` is provided, queries are scoped to that
- * widget's subtree.
+ * A scope that queries and traversal can run against: a widget, an event
+ * controller, a layout manager, a list item or header, an application, or the
+ * sentinel representing all current toplevel windows.
  */
-export type Container = Gtk.Application | Gtk.Widget;
+type Container = QueryContainer | Gtk.Application | typeof TOPLEVELS;
 
-export const isApplication = (container: Container): container is Gtk.Application =>
-    "getWindows" in container && typeof container.getWindows === "function";
+const TOPLEVELS: unique symbol = Symbol("gtkx.toplevels");
+
+const isApplication = (container: Container): container is Gtk.Application => container instanceof Gtk.Application;
 
 const traverseWidgetTree = function* (root: Gtk.Widget): Generator<Gtk.Widget> {
     yield root;
-
     let child = root.getFirstChild();
+
     while (child) {
         yield* traverseWidgetTree(child);
         child = child.getNextSibling();
     }
 };
 
-const traverseWindows = function* (): Generator<Gtk.Widget> {
-    const windows = Gtk.Window.listToplevels();
-    for (const window of windows) {
-        yield* traverseWidgetTree(window);
+const descendants = function* (widget: Gtk.Widget): Generator<Gtk.Widget> {
+    const tree = traverseWidgetTree(widget);
+    tree.next();
+    yield* tree;
+};
+
+const resolveRoot = (container: QueryContainer): Gtk.Widget | null => {
+    if (container instanceof Gtk.Widget) {
+        return container;
+    }
+
+    if (container instanceof Gtk.EventController) {
+        return container.getWidget();
+    }
+
+    if (container instanceof Gtk.LayoutManager) {
+        return container.getWidget();
+    }
+
+    if (container instanceof Gtk.ListItem || container instanceof Gtk.ListHeader) {
+        return container.getChild();
+    }
+
+    return null;
+};
+
+const roots = function* (container: Container): Generator<Gtk.Widget> {
+    if (container === TOPLEVELS || isApplication(container)) {
+        yield* Gtk.Window.listToplevels();
+
+        return;
+    }
+
+    const root = resolveRoot(container);
+
+    if (root) {
+        yield root;
     }
 };
 
-export const traverse = function* (container: Container): Generator<Gtk.Widget> {
-    if (isApplication(container)) {
-        yield* traverseWindows();
-    } else {
-        yield* traverseWidgetTree(container);
+const traverse = function* (container: Container): Generator<Gtk.Widget> {
+    for (const root of roots(container)) {
+        yield* traverseWidgetTree(root);
     }
 };
 
-export const findAll = (container: Container, predicate: (node: Gtk.Widget) => boolean): Gtk.Widget[] => {
+const findAll = (container: Container, isMatch: (node: Gtk.Widget) => boolean): Gtk.Widget[] => {
     const results: Gtk.Widget[] = [];
+
     for (const node of traverse(container)) {
-        if (node.getAccessibleRole?.() === Gtk.AccessibleRole.LABEL) continue;
-        if (predicate(node)) {
+        if (isMatch(node)) {
             results.push(node);
         }
     }
+
     return results;
 };
+
+export { TOPLEVELS, descendants, roots, traverse, findAll, type Container };

package/src/types.ts

@@ -1,210 +1,182 @@
-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
+ * A custom matcher predicate: given a candidate widget's normalized text content and the widget
+ * itself, returns whether it matches.
  */
-export type TextMatchFunction = (content: string, widget: Gtk.Widget) => boolean;
+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}. */
+type Matcher = string | number | RegExp | MatcherFunction;
+/** Normalizes a widget's text before it is compared against a matcher. */
+type NormalizerFn = (text: string) => string;
 
-/**
- * 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.
- */
-export type NormalizerOptions = {
-    /** Remove leading/trailing whitespace (default: true) */
-    trim?: boolean;
-    /** Replace multiple whitespace characters with single space (default: true) */
-    collapseWhitespace?: boolean;
+/** Options controlling the default text normalizer. */
+type NormalizerOptions = {
+    /** 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. */
+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. */
+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. */
+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. */
+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.
- */
-export type WrapperComponent = ComponentType<{
+/** A React component that wraps rendered content, receiving it as its children. */
+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;
+type QueryMap = Record<string, Query>;
+
+type BoundQuery<Q extends Query> = Q extends (container: Container, ...args: infer A) => infer R
+    ? (...args: A) => R
+    : never;
+
+type BoundCustomQueries<Q extends QueryMap> = { [K in keyof Q]: BoundQuery<Q[K]> };
 
 /**
- * Query methods bound to a container.
- *
- * @see {@link screen} for global queries
- * @see {@link within} for scoped queries
+ * 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 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 widget name (returns null if not found) */
-    queryByName: (name: 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 widget name (returns empty array if none found) */
-    queryAllByName: (name: 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 widget name (waits and throws if not found) */
-    findByName: (name: 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 widget name (waits and throws if none found) */
-    findAllByName: (name: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
+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;
+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.
- */
-export type ScreenshotResult = {
-    /** Base64-encoded PNG image data */
+/** A captured screenshot: base64-encoded image data, its MIME type, and pixel dimensions. */
+type ScreenshotResult = {
     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 capturing a screenshot: the poll timeout and interval, plus a rendering scale factor. */
+type ScreenshotOptions = Pick<WaitForOptions, "timeout" | "interval"> & {
+    /** Device scale factor applied when rendering. */
+    scale?: number;
+};
+
 /**
- * Options for {@link renderHook}.
+ * Selects the window to screenshot by index, or by title (exact string or regular expression);
+ * undefined targets the default window.
  */
-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;
-};
+type WindowSelector = number | string | RegExp | undefined;
+
+/**
+ * Options for {@link renderHook}: an optional wrapper and the initial props (required unless the
+ * props type permits undefined).
+ */
+type RenderHookOptions<Props> = {
+    wrapper?: WrapperComponent;
+} & (undefined extends Props
+    ? {
+            initialProps?: Props;
+        }
+    : {
+            initialProps: Props;
+        });
 
 /**
- * Result returned by {@link renderHook}.
- *
- * Provides access to the hook result and utilities for re-rendering and cleanup.
+ * 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 */
+type RenderHookResult<Result, Props> = {
+    /** 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>;
 };
+
+export {
+    type MatcherFunction,
+    type Matcher,
+    type NormalizerFn,
+    type NormalizerOptions,
+    type WaitForOptions,
+    type MatcherOptions,
+    type ByRoleValue,
+    type ByRoleOptions,
+    type WrapperComponent,
+    type QueryMap,
+    type BoundCustomQueries,
+    type RenderOptions,
+    type DebugUtilities,
+    type ScreenshotResult,
+    type ScreenshotOptions,
+    type WindowSelector,
+    type RenderHookOptions,
+    type RenderHookResult,
+};

package/src/user-event/adjustment.ts

@@ -0,0 +1,62 @@
+import * as Gtk from "@gtkx/gi/gtk";
+import { wrapEvent } from "./event-wrapper.js";
+
+/** A scroll distance in pixels along each axis. */
+type ScrollDelta = {
+    x?: number;
+    y?: number;
+};
+
+type ScrollAdjustments = {
+    horizontal: Gtk.Adjustment | null;
+    vertical: Gtk.Adjustment | null;
+};
+
+const slide = (widget: Gtk.Widget, value: number): Promise<void> =>
+    wrapEvent(widget, () => {
+        if (!(widget instanceof Gtk.Range)) {
+            throw new TypeError(
+                `userEvent.slide requires a Gtk.Range (e.g. Gtk.Scale), got ${widget.constructor.name}`,
+            );
+        }
+
+        widget.emit("change-value", Gtk.ScrollType.JUMP, value);
+    });
+
+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);
+};
+
+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);
+    });
+
+export { slide, scroll, type ScrollDelta };