@gtkx/testing 1.0.0-rc.3 → 1.0.0

package/src/traversal.ts

@@ -1,5 +1,9 @@
 import * as Gtk from "@gtkx/gi/gtk";
 
+/**
+ * A scope that resolves to a single root widget: the widget itself, the widget a controller or
+ * layout manager is attached to, or a list item's or header's child.
+ */
 type QueryContainer = Gtk.Widget | Gtk.EventController | Gtk.LayoutManager | Gtk.ListItem | Gtk.ListHeader;
 /**
  * A scope that queries and traversal can run against: a widget, an event
@@ -8,26 +12,55 @@ type QueryContainer = Gtk.Widget | Gtk.EventController | Gtk.LayoutManager | Gtk
  */
 type Container = QueryContainer | Gtk.Application | typeof TOPLEVELS;
 
+/** Container sentinel that widens a query to every toplevel window currently open. */
 const TOPLEVELS: unique symbol = Symbol("gtkx.toplevels");
 
 const isApplication = (container: Container): container is Gtk.Application => container instanceof Gtk.Application;
+const isAnyWidget = (): boolean => true;
+const isOnScreen = (widget: Gtk.Widget): boolean => widget.getMapped();
+
+const traverseWidgetTree = function* (
+    root: Gtk.Widget,
+    isIncluded: (widget: Gtk.Widget) => boolean,
+): Generator<Gtk.Widget> {
+    if (isIncluded(root)) {
+        yield root;
+    }
 
-const traverseWidgetTree = function* (root: Gtk.Widget): Generator<Gtk.Widget> {
-    yield root;
     let child = root.getFirstChild();
 
     while (child) {
-        yield* traverseWidgetTree(child);
+        yield* traverseWidgetTree(child, isIncluded);
+        child = child.getNextSibling();
+    }
+};
+
+const children = function* (widget: Gtk.Widget): Generator<Gtk.Widget> {
+    let child = widget.getFirstChild();
+
+    while (child) {
+        yield child;
         child = child.getNextSibling();
     }
 };
 
 const descendants = function* (widget: Gtk.Widget): Generator<Gtk.Widget> {
-    const tree = traverseWidgetTree(widget);
+    const tree = traverseWidgetTree(widget, isAnyWidget);
     tree.next();
     yield* tree;
 };
 
+const relationCandidates = (widget: Gtk.Widget): Gtk.Accessible[] => {
+    const pool: Gtk.Accessible[] = [...widget.listMnemonicLabels(), ...descendants(widget)];
+    const root = widget.getRoot();
+
+    if (root instanceof Gtk.Widget) {
+        pool.push(...traverseWidgetTree(root, isAnyWidget));
+    }
+
+    return [...new Set(pool)];
+};
+
 const resolveRoot = (container: QueryContainer): Gtk.Widget | null => {
     if (container instanceof Gtk.Widget) {
         return container;
@@ -64,7 +97,7 @@ const roots = function* (container: Container): Generator<Gtk.Widget> {
 
 const traverse = function* (container: Container): Generator<Gtk.Widget> {
     for (const root of roots(container)) {
-        yield* traverseWidgetTree(root);
+        yield* traverseWidgetTree(root, isOnScreen);
     }
 };
 
@@ -80,4 +113,14 @@ const findAll = (container: Container, isMatch: (node: Gtk.Widget) => boolean):
     return results;
 };
 
-export { TOPLEVELS, descendants, roots, traverse, findAll, type Container };
+export {
+    TOPLEVELS,
+    children,
+    descendants,
+    findAll,
+    isOnScreen,
+    relationCandidates,
+    roots,
+    traverse,
+    type Container,
+};

package/src/types.ts

@@ -55,11 +55,19 @@ type MatcherOptions<T extends Gtk.Widget = Gtk.Widget> = {
     as?: WidgetType<T> | undefined;
 } & WaitForOptions;
 
-/** Constraints on a widget's numeric range value used by role queries. */
+/**
+ * Constraints on a widget's numeric range value used by role queries. The numbers come from the
+ * accessibility tree and match within 0.001, the resolution GTK keeps them to.
+ */
 type ByRoleValue = {
     /** The current value. */
     now?: number | undefined;
+    /** The lower bound of the value's range. */
     min?: number | undefined;
+    /**
+     * The highest value the widget can reach, which on a paged widget such as a scrollbar is its
+     * adjustment's upper bound less one page.
+     */
     max?: number | undefined;
     /** Matcher for the value's textual representation. */
     text?: Matcher | undefined;
@@ -67,17 +75,25 @@ type ByRoleValue = {
 
 /** Options for role queries: an accessible name matcher plus accessible state and value constraints. */
 type ByRoleOptions<T extends Gtk.Widget = Gtk.Widget> = MatcherOptions<T> & {
+    /** Matcher for the widget's accessible name. */
     name?: Matcher | undefined;
+    /** Required checked state; a mixed check button reads as neither, so it matches neither value. */
     checked?: boolean | undefined;
+    /** Required active state of a toggle button; any other widget matches neither value. */
     pressed?: boolean | undefined;
+    /** Required selected state of a row, list item, grid cell, option or tree item. */
     selected?: boolean | undefined;
+    /** Required expanded state of an expander or tree expander. */
     expanded?: boolean | undefined;
     /** Heading or hierarchy level. */
     level?: number | undefined;
+    /** Required busy state, which an unset state satisfies as false. */
     busy?: boolean | undefined;
+    /** Matcher for the widget's own accessible description, ignoring its `described-by` targets. */
     description?: Matcher | undefined;
+    /** Constraints on the widget's range value, each checked only when given. */
     value?: ByRoleValue | undefined;
-    /** When true, include widgets excluded from the accessibility tree. */
+    /** When true, include widgets excluded from the accessibility tree. Widgets that are not mapped stay excluded. */
     hidden?: boolean | undefined;
 };
 
@@ -86,26 +102,39 @@ type WrapperComponent = ComponentType<{
     children: ReactNode;
 }>;
 
+/** A custom query, taking the scope to search as its first argument and its matcher arguments after it. */
 type Query = (container: Container, ...args: never[]) => unknown;
+/** Custom queries keyed by the name each is bound under. */
 type QueryMap = Record<string, Query>;
 
+/** A query with its container argument already applied. */
 type BoundQuery<Q extends Query> = Q extends (container: Container, ...args: infer A) => infer R
     ? (...args: A) => R
     : never;
 
+/** Custom queries with their container argument already applied, keyed as they were passed in. */
 type BoundCustomQueries<Q extends QueryMap> = { [K in keyof Q]: BoundQuery<Q[K]> };
 
+/** What each variant of a query family yields for the widget type it matched. */
 type QueryFamilyReturns<T extends Gtk.Widget> = {
+    /** The single match, or null when nothing matched; throws when more than one matched. */
     queryBy: T | null;
+    /** Every match, empty when nothing matched. */
     queryAllBy: T[];
+    /** The single match; throws when nothing or more than one matched. */
     getBy: T;
+    /** Every match; throws when nothing matched. */
     getAllBy: T[];
+    /** The single match, retried until it appears or the timeout elapses. */
     findBy: Promise<T>;
+    /** Every match, retried until at least one appears or the timeout elapses. */
     findAllBy: Promise<T[]>;
 };
 
+/** What a query family matches against, which fixes the arguments it takes. */
 type QueryKind = "role" | "text" | "name" | "value";
 
+/** The arguments a query of the given kind takes after the family's leading ones. */
 type QueryArgs<Kind extends QueryKind, T extends Gtk.Widget> = Kind extends "role"
     ? [role: Gtk.AccessibleRole, options?: ByRoleOptions<T>]
     : Kind extends "name"
@@ -115,9 +144,8 @@ type QueryArgs<Kind extends QueryKind, T extends Gtk.Widget> = Kind extends "rol
             : [text: Matcher, options?: MatcherOptions<T>];
 
 /**
- * One query family (`queryBy`, `getBy`, `findBy` and their `All` variants) for a single suffix.
- * Each member takes an explicit widget type, as Testing Library's queries do, and also infers it
- * from an `as` option.
+ * One family's query variants, each named for its variant followed by `Suffix` and taking `Head`
+ * ahead of the family's own arguments.
  */
 type QueryFamily<Suffix extends string, Kind extends QueryKind, Head extends unknown[]> = {
     [K in keyof QueryFamilyReturns<Gtk.Widget> as `${K & string}${Suffix}`]: <T extends Gtk.Widget = Gtk.Widget>(
@@ -125,6 +153,10 @@ type QueryFamily<Suffix extends string, Kind extends QueryKind, Head extends unk
     ) => QueryFamilyReturns<T>[K];
 };
 
+/**
+ * Every built-in query, spanning the Role, LabelText, Text, Name, PlaceholderText, and DisplayValue
+ * families, with `Head` prepended to each signature.
+ */
 type QueryFamilies<Head extends unknown[]> = QueryFamily<"Role", "role", Head> &
     QueryFamily<"LabelText", "text", Head> &
     QueryFamily<"Text", "text", Head> &
@@ -137,14 +169,16 @@ type QueryFamilies<Head extends unknown[]> = QueryFamily<"Role", "role", Head> &
  * React behavior toggles, error callbacks, and custom queries to bind.
  */
 type RenderOptions<Q extends QueryMap = Record<never, never>> = {
+    /** Widget or root element to mount into; an undecorated harness window is created when omitted. */
     container?: Gtk.Widget | RootElement | undefined;
     /** Root of the subtree that bound queries search. */
     baseElement?: Container | undefined;
+    /** Component wrapped around the rendered element, such as a context provider. */
     wrapper?: WrapperComponent | undefined;
     /** Render inside React StrictMode. */
-    reactStrictMode?: boolean | undefined;
+    isReactStrictMode?: boolean | undefined;
     /** Enable widget animations during the test. */
-    animations?: boolean | undefined;
+    areAnimationsEnabled?: boolean | undefined;
     /** Called for errors caught by React error boundaries. */
     onCaughtError?: ((error: unknown, errorInfo: ErrorInfo) => void) | undefined;
     /** Called for errors React recovered from automatically. */
@@ -153,40 +187,52 @@ type RenderOptions<Q extends QueryMap = Record<never, never>> = {
     queries?: Q | undefined;
 };
 
+/** Console helpers bundled with the bound queries on {@link screen} and on a render result. */
 type DebugUtilities = {
+    /** Prints the widget tree of the given containers, or of the whole scope, to the console. */
     debug: (element?: Container | Container[], options?: PrettyWidgetOptions) => void;
+    /** Prints the accessible roles found in the scope, with the widgets carrying each one. */
     logRoles: () => void;
-    screenshot: (selector?: WindowSelector, options?: ScreenshotOptions) => Promise<ScreenshotResult>;
+    /**
+     * Captures what is on screen, which is the active toplevel window: GTK4 exposes no position for
+     * a toplevel, so windows cannot be composited into a single image.
+     */
+    screenshot: (options?: ScreenshotOptions) => Promise<ScreenshotResult>;
 };
 
 /** A captured screenshot: base64-encoded image data, its MIME type, and pixel dimensions. */
 type ScreenshotResult = {
+    /** Base64-encoded image bytes. */
     data: string;
+    /** MIME type of the encoded image, always `image/png`. */
     mimeType: string;
+    /** Image width in pixels, after the scale factor is applied. */
     width: number;
+    /** Image height in pixels, after the scale factor is applied. */
     height: number;
 };
 
-/** Options for capturing a screenshot: the poll timeout and interval, plus a rendering scale factor. */
+/**
+ * Options for capturing a screenshot: the poll timeout and interval, a rendering scale factor, and
+ * a file to write the PNG to.
+ */
 type ScreenshotOptions = Pick<WaitForOptions, "timeout" | "interval"> & {
     /** Device scale factor applied when rendering. */
-    scale?: number;
+    scale?: number | undefined;
+    /** File the PNG is written to, with its parent directories created as needed. */
+    path?: string | undefined;
 };
 
-/**
- * Selects the window to screenshot by index, or by title (exact string or regular expression);
- * undefined targets the default window.
- */
-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> = {
+    /** Component wrapped around the one calling the hook, such as a context provider. */
     wrapper?: WrapperComponent;
 } & (undefined extends Props
     ? {
+            /** Props the hook is invoked with until `rerender` is given new ones. */
             initialProps?: Props;
         }
     : {
@@ -198,9 +244,14 @@ type RenderHookOptions<Props> = {
  * props and to unmount.
  */
 type RenderHookResult<Result, Props> = {
-    /** Holds the most recent value returned by the hook under `current`. */
-    result: { current: Result };
+    /** Stable object the hook's return value is written to on every render. */
+    result: {
+        /** The hook's latest return value. */
+        current: Result;
+    };
+    /** Re-invokes the hook, keeping the previous props when none are given. */
     rerender: (newProps?: Props) => Promise<void>;
+    /** Unmounts the component that calls the hook. */
     unmount: () => Promise<void>;
 };
 
@@ -222,7 +273,6 @@ export {
     type DebugUtilities,
     type ScreenshotResult,
     type ScreenshotOptions,
-    type WindowSelector,
     type RenderHookOptions,
     type RenderHookResult,
 };

package/src/user-event/adjustment.ts

@@ -1,9 +1,12 @@
 import * as Gtk from "@gtkx/gi/gtk";
+import { scheduleNextFrame } from "../frame-sync.js";
 import { wrapEvent } from "./event-wrapper.js";
 
 /** A scroll distance in pixels along each axis. */
 type ScrollDelta = {
+    /** Distance added to the horizontal adjustment. */
     x?: number;
+    /** Distance added to the vertical adjustment. */
     y?: number;
 };
 
@@ -12,6 +15,11 @@ type ScrollAdjustments = {
     vertical: Gtk.Adjustment | null;
 };
 
+/**
+ * Emits a jump `change-value` so a Gtk.Range moves to the given value.
+ *
+ * @throws When the widget is not a Gtk.Range.
+ */
 const slide = (widget: Gtk.Widget, value: number): Promise<void> =>
     wrapEvent(widget, () => {
         if (!(widget instanceof Gtk.Range)) {
@@ -37,16 +45,47 @@ const resolveScrollAdjustments = (widget: Gtk.Widget): ScrollAdjustments | null
     return null;
 };
 
+const stepToward = (adjustment: Gtk.Adjustment, target: number, step: number): number => {
+    const value = adjustment.getValue();
+    adjustment.setValue(value < target ? Math.min(value + step, target) : Math.max(value - step, target));
+
+    return adjustment.getValue();
+};
+
+const rampTo = (adjustment: Gtk.Adjustment, target: number, step: number): void => {
+    let value = adjustment.getValue();
+
+    while (value !== target) {
+        const moved = stepToward(adjustment, target, step);
+
+        if (moved === value) {
+            return;
+        }
+
+        value = moved;
+    }
+};
+
 const applyScrollDelta = (adjustment: Gtk.Adjustment | null, delta: number): void => {
     if (!adjustment || delta === 0) {
         return;
     }
 
-    adjustment.setValue(adjustment.getValue() + delta);
+    const pageSize = adjustment.getPageSize();
+    rampTo(adjustment, adjustment.getValue() + delta, pageSize > 0 ? pageSize : Math.abs(delta));
 };
 
+/**
+ * Adds the delta to the adjustments of the widget itself, or of its nearest Gtk.ScrolledWindow or
+ * Gtk.Scrollable ancestor.
+ *
+ * Each adjustment advances in viewport-sized steps rather than one jump, so virtualized views such
+ * as Gtk.ListView, Gtk.GridView and Gtk.ColumnView re-anchor onto the rows the new offset shows.
+ *
+ * @throws When neither the widget nor any of its ancestors is scrollable.
+ */
 const scroll = (widget: Gtk.Widget, delta: ScrollDelta): Promise<void> =>
-    wrapEvent(widget, () => {
+    wrapEvent(widget, async () => {
         const adjustments = resolveScrollAdjustments(widget);
 
         if (!adjustments) {
@@ -57,6 +96,7 @@ const scroll = (widget: Gtk.Widget, delta: ScrollDelta): Promise<void> =>
 
         applyScrollDelta(adjustments.horizontal, delta.x ?? 0);
         applyScrollDelta(adjustments.vertical, delta.y ?? 0);
+        await scheduleNextFrame(widget);
     });
 
 export { slide, scroll, type ScrollDelta };