@gtkx/testing 1.0.0-rc.1 → 1.0.0-rc.3

package/src/suggestions.ts

@@ -11,13 +11,15 @@ import {
 } from "./widget-accessible-properties.js";
 
 /** The query variant a suggestion targets. */
-export type Variant = "get" | "getAll" | "query" | "queryAll" | "find" | "findAll";
-
+type Variant = "get" | "getAll" | "query" | "queryAll" | "find" | "findAll";
 /** The query family a suggestion targets. */
-export type Method = "Role" | "LabelText" | "PlaceholderText" | "Text" | "DisplayValue" | "Name";
+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. */
-export type Suggestion = {
+/**
+ * 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;
@@ -27,6 +29,7 @@ export type Suggestion = {
 
 const makeSuggestion = (queryName: Method, variant: Variant, argsText: string): Suggestion => {
     const queryMethod = `${variant}By${queryName}`;
+
     return {
         queryName,
         queryMethod,
@@ -37,29 +40,38 @@ const makeSuggestion = (queryName: Method, variant: Variant, argsText: string):
 
 const roleSuggestion = (widget: Gtk.Widget, variant: Variant): Suggestion | undefined => {
     const role = widget.getAccessibleRole();
-    if (role === Gtk.AccessibleRole.NONE || role === Gtk.AccessibleRole.GENERIC) return undefined;
+
+    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;
+    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.
+ * 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.
  */
-export const getSuggestedQuery = (
+const getSuggestedQuery = (
     widget: Gtk.Widget,
     variant: Variant = "get",
     method?: Method,
@@ -79,9 +91,16 @@ export const getSuggestedQuery = (
     }
 
     const priority: Method[] = ["Role", "LabelText", "PlaceholderText", "Text", "DisplayValue", "Name"];
+
     for (const candidate of priority) {
         const suggestion = builders[candidate]();
-        if (suggestion) return suggestion;
+
+        if (suggestion) {
+            return suggestion;
+        }
     }
+
     return undefined;
 };
+
+export { getSuggestedQuery, type Variant, type Method, type Suggestion };

package/src/traversal.ts

@@ -1,63 +1,83 @@
 import * as Gtk from "@gtkx/gi/gtk";
 
-export const TOPLEVELS: unique symbol = Symbol("gtkx.toplevels");
-
 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
  * controller, a layout manager, a list item or header, an application, or the
  * sentinel representing all current toplevel windows.
  */
-export type Container = QueryContainer | Gtk.Application | typeof TOPLEVELS;
+type Container = QueryContainer | Gtk.Application | typeof TOPLEVELS;
+
+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();
     }
 };
 
-export const descendants = function* (widget: Gtk.Widget): Generator<Gtk.Widget> {
+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();
+    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;
 };
 
-export const roots = function* (container: Container): Generator<Gtk.Widget> {
+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;
+
+    if (root) {
+        yield root;
+    }
 };
 
-export const traverse = function* (container: Container): Generator<Gtk.Widget> {
+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 (predicate(node)) {
+        if (isMatch(node)) {
             results.push(node);
         }
     }
+
     return results;
 };
+
+export { TOPLEVELS, descendants, roots, traverse, findAll, type Container };

package/src/types.ts

@@ -4,17 +4,23 @@ import type { ComponentType, ErrorInfo, ReactNode } from "react";
 import type { PrettyWidgetOptions } from "./pretty-widget.js";
 import type { Container } from "./traversal.js";
 
-/** 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 custom matcher predicate: given a candidate widget's normalized text content and the widget
+ * itself, returns whether it matches.
+ */
+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;
-
+type Matcher = string | number | RegExp | MatcherFunction;
 /** Normalizes a widget's text before it is compared against a matcher. */
-export type NormalizerFn = (text: string) => string;
+type NormalizerFn = (text: string) => string;
+/**
+ * A widget class usable as a query's `as` constraint, such as `Gtk.Button`. Abstract classes and
+ * generated GInterface pseudo-classes are accepted.
+ */
+type WidgetType<T extends Gtk.Widget = Gtk.Widget> = abstract new (...args: never[]) => T;
 
 /** Options controlling the default text normalizer. */
-export type NormalizerOptions = {
+type NormalizerOptions = {
     /** Trim leading and trailing whitespace. */
     trim?: boolean | undefined;
     /** Collapse runs of whitespace into a single space. */
@@ -22,7 +28,7 @@ export type NormalizerOptions = {
 };
 
 /** Options controlling how asynchronous queries and waits poll for a condition. */
-export type WaitForOptions = {
+type WaitForOptions = {
     /** Maximum time in milliseconds to keep retrying before failing. */
     timeout?: number | undefined;
     /** Delay in milliseconds between retries. */
@@ -34,7 +40,7 @@ export type WaitForOptions = {
 };
 
 /** Options controlling text matching and, for asynchronous queries, polling behavior. */
-export type MatcherOptions = {
+type MatcherOptions<T extends Gtk.Widget = Gtk.Widget> = {
     /** 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`. */
@@ -45,10 +51,12 @@ export type MatcherOptions = {
     collapseWhitespace?: boolean | undefined;
     /** Whether to include a suggested better query in error messages. */
     suggest?: boolean | undefined;
+    /** Restricts matches to instances of this widget class, and narrows the query's return type to it. */
+    as?: WidgetType<T> | undefined;
 } & WaitForOptions;
 
 /** Constraints on a widget's numeric range value used by role queries. */
-export type ByRoleValue = {
+type ByRoleValue = {
     /** The current value. */
     now?: number | undefined;
     min?: number | undefined;
@@ -58,7 +66,7 @@ export type ByRoleValue = {
 };
 
 /** Options for role queries: an accessible name matcher plus accessible state and value constraints. */
-export type ByRoleOptions = MatcherOptions & {
+type ByRoleOptions<T extends Gtk.Widget = Gtk.Widget> = MatcherOptions<T> & {
     name?: Matcher | undefined;
     checked?: boolean | undefined;
     pressed?: boolean | undefined;
@@ -74,22 +82,61 @@ export type ByRoleOptions = MatcherOptions & {
 };
 
 /** A React component that wraps rendered content, receiving it as its children. */
-export type WrapperComponent = ComponentType<{
+type WrapperComponent = ComponentType<{
     children: ReactNode;
 }>;
 
 type Query = (container: Container, ...args: never[]) => unknown;
-
-export type QueryMap = Record<string, Query>;
+type QueryMap = Record<string, Query>;
 
 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]> };
+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>> = {
+type QueryFamilyReturns<T extends Gtk.Widget> = {
+    queryBy: T | null;
+    queryAllBy: T[];
+    getBy: T;
+    getAllBy: T[];
+    findBy: Promise<T>;
+    findAllBy: Promise<T[]>;
+};
+
+type QueryKind = "role" | "text" | "name" | "value";
+
+type QueryArgs<Kind extends QueryKind, T extends Gtk.Widget> = Kind extends "role"
+    ? [role: Gtk.AccessibleRole, options?: ByRoleOptions<T>]
+    : Kind extends "name"
+        ? [name: Matcher, options?: MatcherOptions<T>]
+        : Kind extends "value"
+            ? [value: Matcher, options?: MatcherOptions<T>]
+            : [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.
+ */
+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>(
+        ...args: [...Head, ...QueryArgs<Kind, T>]
+    ) => QueryFamilyReturns<T>[K];
+};
+
+type QueryFamilies<Head extends unknown[]> = QueryFamily<"Role", "role", Head> &
+    QueryFamily<"LabelText", "text", Head> &
+    QueryFamily<"Text", "text", Head> &
+    QueryFamily<"Name", "name", Head> &
+    QueryFamily<"PlaceholderText", "text", Head> &
+    QueryFamily<"DisplayValue", "value", Head>;
+
+/**
+ * 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.
+ */
+type RenderOptions<Q extends QueryMap = Record<never, never>> = {
     container?: Gtk.Widget | RootElement | undefined;
     /** Root of the subtree that bound queries search. */
     baseElement?: Container | undefined;
@@ -106,14 +153,14 @@ export type RenderOptions<Q extends QueryMap = Record<never, never>> = {
     queries?: Q | undefined;
 };
 
-export type DebugUtilities = {
+type DebugUtilities = {
     debug: (element?: Container | Container[], options?: PrettyWidgetOptions) => void;
     logRoles: () => void;
     screenshot: (selector?: WindowSelector, options?: ScreenshotOptions) => Promise<ScreenshotResult>;
 };
 
 /** A captured screenshot: base64-encoded image data, its MIME type, and pixel dimensions. */
-export type ScreenshotResult = {
+type ScreenshotResult = {
     data: string;
     mimeType: string;
     width: number;
@@ -121,29 +168,61 @@ export type ScreenshotResult = {
 };
 
 /** Options for capturing a screenshot: the poll timeout and interval, plus a rendering scale factor. */
-export type ScreenshotOptions = Pick<WaitForOptions, "timeout" | "interval"> & {
+type ScreenshotOptions = Pick<WaitForOptions, "timeout" | "interval"> & {
     /** Device scale factor applied when rendering. */
     scale?: number;
 };
 
-/** 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> = {
+/**
+ * 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> = {
     wrapper?: WrapperComponent;
 } & (undefined extends Props
     ? {
-          initialProps?: 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> = {
+            initialProps: Props;
+        });
+
+/**
+ * The result of {@link renderHook}: the latest hook return value plus functions to rerender with new
+ * props and to unmount.
+ */
+type RenderHookResult<Result, Props> = {
     /** Holds the most recent value returned by the hook under `current`. */
     result: { current: Result };
     rerender: (newProps?: Props) => Promise<void>;
     unmount: () => Promise<void>;
 };
+
+export {
+    type MatcherFunction,
+    type Matcher,
+    type NormalizerFn,
+    type NormalizerOptions,
+    type WaitForOptions,
+    type MatcherOptions,
+    type ByRoleValue,
+    type ByRoleOptions,
+    type WidgetType,
+    type WrapperComponent,
+    type QueryMap,
+    type BoundCustomQueries,
+    type QueryFamilies,
+    type RenderOptions,
+    type DebugUtilities,
+    type ScreenshotResult,
+    type ScreenshotOptions,
+    type WindowSelector,
+    type RenderHookOptions,
+    type RenderHookResult,
+};

package/src/user-event/adjustment.ts

@@ -1,49 +1,62 @@
 import * as Gtk from "@gtkx/gi/gtk";
 import { wrapEvent } from "./event-wrapper.js";
 
-export type ScrollDelta = {
+/** A scroll distance in pixels along each axis. */
+type ScrollDelta = {
     x?: number;
     y?: number;
 };
 
-export const slide = (widget: Gtk.Widget, value: number): Promise<void> =>
+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 Error(`userEvent.slide requires a Gtk.Range (e.g. Gtk.Scale), got ${widget.constructor.name}`);
+            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);
     });
 
-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;
+    if (!adjustment || delta === 0) {
+        return;
+    }
+
     adjustment.setValue(adjustment.getValue() + delta);
 };
 
-export const scroll = (widget: Gtk.Widget, delta: ScrollDelta): Promise<void> =>
+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 };

package/src/user-event/click.ts

@@ -2,25 +2,31 @@ 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 getPressPoint = (widget: Gtk.Widget): { x: number; y: number } => {
     const width = widget.getWidth();
     const height = widget.getHeight();
-    if (width > 0 && height > 0) return { x: width / 2, y: height / 2 };
+
+    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);
+const emitGesture = (widget: Gtk.Widget, controllers: Gtk.GestureClick[], nPress: number, signal: string): void => {
+    const { x, y } = getPressPoint(widget);
+
     for (const controller of controllers) {
-        controller.emit("pressed", nPress, x, y);
+        controller.emit(signal, 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 emitPress = (widget: Gtk.Widget, controllers: Gtk.GestureClick[], nPress: number): void => {
+    emitGesture(widget, controllers, nPress, "pressed");
+};
+
+const emitRelease = (widget: Gtk.Widget, controllers: Gtk.GestureClick[], nPress: number): void => {
+    emitGesture(widget, controllers, nPress, "released");
 };
 
 const emitClickSequence = (widget: Gtk.Widget, target: Gtk.Widget, nPress: number): Promise<void> =>
@@ -35,36 +41,59 @@ const emitClickSequence = (widget: Gtk.Widget, target: Gtk.Widget, nPress: numbe
 
 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> => {
+const tryActivate = async (widget: Gtk.Widget): Promise<boolean> => {
+    if (widget.getAccessibleRole() === Gtk.AccessibleRole.LABEL) {
+        return false;
+    }
+
+    let isActivated = false;
+
+    await wrapEvent(widget, () => {
+        isActivated = widget.activate();
+    });
+
+    return isActivated;
+};
+
+const click = async (widget: Gtk.Widget): Promise<void> => {
     if (widget instanceof Gtk.Button) {
         await emitClickSequence(widget, widget, 1);
+
         return;
     }
+
     if (widget instanceof Gtk.Switch) {
         await wrapEvent(widget, () => {
             widget.setActive(!widget.getActive());
         });
+
         return;
     }
-    if (widget.getAccessibleRole() !== Gtk.AccessibleRole.LABEL) {
-        let activated = false;
-        await wrapEvent(widget, () => {
-            activated = widget.activate();
-        });
-        if (activated) return;
+
+    if (await tryActivate(widget)) {
+        return;
     }
+
     const target = findClickableAncestor(widget);
-    if (target) await emitClickSequence(widget, target, 1);
+
+    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);
+const dblClick = (widget: Gtk.Widget): Promise<void> => emitClickSequence(widget, widget, 2);
+const tripleClick = (widget: Gtk.Widget): Promise<void> => emitClickSequence(widget, widget, 3);
+
+export { emitPress, emitRelease, click, dblClick, tripleClick };