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

package/src/queries.ts

@@ -1,12 +1,19 @@
 import * as Gtk from "@gtkx/gi/gtk";
-import type { ByRoleOptions, ByRoleValue, Matcher, MatcherOptions, NormalizerFn, NormalizerOptions } from "./types.js";
+import type {
+    ByRoleOptions,
+    ByRoleValue,
+    Matcher,
+    MatcherOptions,
+    NormalizerFn,
+    QueryFamilies,
+} from "./types.js";
 import { buildQueries, type BuiltQueries, type QueryAllBy } from "./build-queries.js";
 import { multipleFoundError, notFoundError } from "./errors.js";
+import { getDefaultNormalizer } from "./normalize.js";
 import { type Container, findAll, traverse } from "./traversal.js";
 import {
     getWidgetAccessibleName,
     getWidgetBusyState,
-    getWidgetCheckedState,
     getWidgetDescription,
     getWidgetDisplayValue,
     getWidgetExpandedState,
@@ -20,30 +27,10 @@ import {
     getWidgetSelectedState,
     getWidgetValue,
     isInaccessible,
+    isWidgetChecked,
 } from "./widget-accessible-properties.js";
 
-type QueryFamilyReturns = {
-    queryBy: Gtk.Widget | null;
-    queryAllBy: Gtk.Widget[];
-    getBy: Gtk.Widget;
-    getAllBy: Gtk.Widget[];
-    findBy: Promise<Gtk.Widget>;
-    findAllBy: Promise<Gtk.Widget[]>;
-};
-
-type NamedFamily<Suffix extends string, Args extends unknown[]> = {
-    [K in keyof QueryFamilyReturns as `${K & string}${Suffix}`]: (
-        container: Container,
-        ...args: Args
-    ) => QueryFamilyReturns[K];
-};
-
-type BuiltinQueries = NamedFamily<"Role", [role: Gtk.AccessibleRole, options?: ByRoleOptions]> &
-    NamedFamily<"LabelText", [text: Matcher, options?: MatcherOptions]> &
-    NamedFamily<"Text", [text: Matcher, options?: MatcherOptions]> &
-    NamedFamily<"Name", [name: Matcher, options?: MatcherOptions]> &
-    NamedFamily<"PlaceholderText", [text: Matcher, options?: MatcherOptions]> &
-    NamedFamily<"DisplayValue", [value: Matcher, options?: MatcherOptions]>;
+type BuiltinQueries = QueryFamilies<[container: Container]>;
 
 const roleQueries = nameQueryFamily(
     "Role",
@@ -112,167 +99,132 @@ const displayValueQueries = nameQueryFamily(
     ),
 );
 
-const builtinQueries: BuiltinQueries = {
+const builtinQueries = {
     ...roleQueries,
     ...labelTextQueries,
     ...textQueries,
     ...nameQueries,
     ...placeholderTextQueries,
     ...displayValueQueries,
-};
+} as BuiltinQueries;
 
 /**
  * Returns the single widget with a matching accessible role and options, or null when none match.
  * Throws when more than one matches.
  */
-const queryByRole: BuiltinQueries["queryByRole"] = roleQueries.queryByRole;
+const queryByRole: BuiltinQueries["queryByRole"] = builtinQueries.queryByRole;
 /** Returns every widget with a matching accessible role and options. Throws when none match. */
-const getAllByRole: BuiltinQueries["getAllByRole"] = roleQueries.getAllByRole;
+const getAllByRole: BuiltinQueries["getAllByRole"] = builtinQueries.getAllByRole;
 /**
  * Returns the single widget with a matching accessible role and options.
  * Throws when none or more than one matches.
  */
-const getByRole: BuiltinQueries["getByRole"] = roleQueries.getByRole;
+const getByRole: BuiltinQueries["getByRole"] = builtinQueries.getByRole;
 /**
  * Waits for and returns every widget with a matching accessible role and options, retrying until at
  * least one appears or the timeout elapses.
  */
-const findAllByRole: BuiltinQueries["findAllByRole"] = roleQueries.findAllByRole;
+const findAllByRole: BuiltinQueries["findAllByRole"] = builtinQueries.findAllByRole;
 /**
  * Waits for and returns the single widget with a matching accessible role and options, retrying
  * until it appears or the timeout elapses. Rejects when none or more than one matches.
  */
-const findByRole: BuiltinQueries["findByRole"] = roleQueries.findByRole;
+const findByRole: BuiltinQueries["findByRole"] = builtinQueries.findByRole;
 /**
  * Returns the single widget with matching associated label text, or null when none match.
  * Throws when more than one matches.
  */
-const queryByLabelText: BuiltinQueries["queryByLabelText"] = labelTextQueries.queryByLabelText;
+const queryByLabelText: BuiltinQueries["queryByLabelText"] = builtinQueries.queryByLabelText;
 /** Returns every widget with matching associated label text. Throws when none match. */
-const getAllByLabelText: BuiltinQueries["getAllByLabelText"] = labelTextQueries.getAllByLabelText;
+const getAllByLabelText: BuiltinQueries["getAllByLabelText"] = builtinQueries.getAllByLabelText;
 /** Returns the single widget with matching associated label text. Throws when none or more than one matches. */
-const getByLabelText: BuiltinQueries["getByLabelText"] = labelTextQueries.getByLabelText;
+const getByLabelText: BuiltinQueries["getByLabelText"] = builtinQueries.getByLabelText;
 /**
  * Waits for and returns every widget with matching associated label text, retrying until at least
  * one appears or the timeout elapses.
  */
-const findAllByLabelText: BuiltinQueries["findAllByLabelText"] = labelTextQueries.findAllByLabelText;
+const findAllByLabelText: BuiltinQueries["findAllByLabelText"] = builtinQueries.findAllByLabelText;
 /**
  * Waits for and returns the single widget with matching associated label text, retrying until it
  * appears or the timeout elapses. Rejects when none or more than one matches.
  */
-const findByLabelText: BuiltinQueries["findByLabelText"] = labelTextQueries.findByLabelText;
+const findByLabelText: BuiltinQueries["findByLabelText"] = builtinQueries.findByLabelText;
 /**
  * Returns the single widget with matching rendered text content, or null when none match.
  * Throws when more than one matches.
  */
-const queryByText: BuiltinQueries["queryByText"] = textQueries.queryByText;
+const queryByText: BuiltinQueries["queryByText"] = builtinQueries.queryByText;
 /** Returns every widget with matching rendered text content. Throws when none match. */
-const getAllByText: BuiltinQueries["getAllByText"] = textQueries.getAllByText;
+const getAllByText: BuiltinQueries["getAllByText"] = builtinQueries.getAllByText;
 /** Returns the single widget with matching rendered text content. Throws when none or more than one matches. */
-const getByText: BuiltinQueries["getByText"] = textQueries.getByText;
+const getByText: BuiltinQueries["getByText"] = builtinQueries.getByText;
 /**
  * Waits for and returns every widget with matching rendered text content, retrying until at least
  * one appears or the timeout elapses.
  */
-const findAllByText: BuiltinQueries["findAllByText"] = textQueries.findAllByText;
+const findAllByText: BuiltinQueries["findAllByText"] = builtinQueries.findAllByText;
 /**
  * Waits for and returns the single widget with matching rendered text content, retrying until it
  * appears or the timeout elapses. Rejects when none or more than one matches.
  */
-const findByText: BuiltinQueries["findByText"] = textQueries.findByText;
+const findByText: BuiltinQueries["findByText"] = builtinQueries.findByText;
 /**
  * Returns the single widget with a matching widget name, or null when none match.
  * Throws when more than one matches.
  */
-const queryByName: BuiltinQueries["queryByName"] = nameQueries.queryByName;
+const queryByName: BuiltinQueries["queryByName"] = builtinQueries.queryByName;
 /** Returns every widget with a matching widget name. Throws when none match. */
-const getAllByName: BuiltinQueries["getAllByName"] = nameQueries.getAllByName;
+const getAllByName: BuiltinQueries["getAllByName"] = builtinQueries.getAllByName;
 /** Returns the single widget with a matching widget name. Throws when none or more than one matches. */
-const getByName: BuiltinQueries["getByName"] = nameQueries.getByName;
+const getByName: BuiltinQueries["getByName"] = builtinQueries.getByName;
 /**
  * Waits for and returns every widget with a matching widget name, retrying until at least one
  * appears or the timeout elapses.
  */
-const findAllByName: BuiltinQueries["findAllByName"] = nameQueries.findAllByName;
+const findAllByName: BuiltinQueries["findAllByName"] = builtinQueries.findAllByName;
 /**
  * Waits for and returns the single widget with a matching widget name, retrying until it appears or
  * the timeout elapses. Rejects when none or more than one matches.
  */
-const findByName: BuiltinQueries["findByName"] = nameQueries.findByName;
-
+const findByName: BuiltinQueries["findByName"] = builtinQueries.findByName;
 /**
  * Returns the single widget with matching placeholder text, or null when none match.
  * Throws when more than one matches.
  */
-const queryByPlaceholderText: BuiltinQueries["queryByPlaceholderText"] =
-    placeholderTextQueries.queryByPlaceholderText;
-
+const queryByPlaceholderText: BuiltinQueries["queryByPlaceholderText"] = builtinQueries.queryByPlaceholderText;
 /** Returns every widget with matching placeholder text. Throws when none match. */
-const getAllByPlaceholderText: BuiltinQueries["getAllByPlaceholderText"] =
-    placeholderTextQueries.getAllByPlaceholderText;
-
+const getAllByPlaceholderText: BuiltinQueries["getAllByPlaceholderText"] = builtinQueries.getAllByPlaceholderText;
 /** Returns the single widget with matching placeholder text. Throws when none or more than one matches. */
-const getByPlaceholderText: BuiltinQueries["getByPlaceholderText"] = placeholderTextQueries.getByPlaceholderText;
-
+const getByPlaceholderText: BuiltinQueries["getByPlaceholderText"] = builtinQueries.getByPlaceholderText;
 /**
  * Waits for and returns every widget with matching placeholder text, retrying until at least one
  * appears or the timeout elapses.
  */
-const findAllByPlaceholderText: BuiltinQueries["findAllByPlaceholderText"] =
-    placeholderTextQueries.findAllByPlaceholderText;
-
+const findAllByPlaceholderText: BuiltinQueries["findAllByPlaceholderText"] = builtinQueries.findAllByPlaceholderText;
 /**
  * Waits for and returns the single widget with matching placeholder text, retrying until it appears
  * or the timeout elapses. Rejects when none or more than one matches.
  */
-const findByPlaceholderText: BuiltinQueries["findByPlaceholderText"] =
-    placeholderTextQueries.findByPlaceholderText;
-
+const findByPlaceholderText: BuiltinQueries["findByPlaceholderText"] = builtinQueries.findByPlaceholderText;
 /**
  * Returns the single widget with a matching display value, or null when none match.
  * Throws when more than one matches.
  */
-const queryByDisplayValue: BuiltinQueries["queryByDisplayValue"] = displayValueQueries.queryByDisplayValue;
+const queryByDisplayValue: BuiltinQueries["queryByDisplayValue"] = builtinQueries.queryByDisplayValue;
 /** Returns every widget with a matching display value. Throws when none match. */
-const getAllByDisplayValue: BuiltinQueries["getAllByDisplayValue"] = displayValueQueries.getAllByDisplayValue;
+const getAllByDisplayValue: BuiltinQueries["getAllByDisplayValue"] = builtinQueries.getAllByDisplayValue;
 /** Returns the single widget with a matching display value. Throws when none or more than one matches. */
-const getByDisplayValue: BuiltinQueries["getByDisplayValue"] = displayValueQueries.getByDisplayValue;
+const getByDisplayValue: BuiltinQueries["getByDisplayValue"] = builtinQueries.getByDisplayValue;
 /**
  * Waits for and returns every widget with a matching display value, retrying until at least one
  * appears or the timeout elapses.
  */
-const findAllByDisplayValue: BuiltinQueries["findAllByDisplayValue"] = displayValueQueries.findAllByDisplayValue;
+const findAllByDisplayValue: BuiltinQueries["findAllByDisplayValue"] = builtinQueries.findAllByDisplayValue;
 /**
  * Waits for and returns the single widget with a matching display value, retrying until it appears
  * or the timeout elapses. Rejects when none or more than one matches.
  */
-const findByDisplayValue: BuiltinQueries["findByDisplayValue"] = displayValueQueries.findByDisplayValue;
-
-/**
- * Builds the default text normalizer, which optionally trims surrounding whitespace and collapses
- * runs of whitespace into single spaces.
- * @param options Toggles for trimming and whitespace collapsing.
- * @returns A function that normalizes a string for comparison against a matcher.
- */
-const getDefaultNormalizer = ({
-    trim = true,
-    collapseWhitespace = true,
-}: NormalizerOptions = {}): NormalizerFn => {
-    return (text: string): string => {
-        let result = text;
-
-        if (trim) {
-            result = result.trim();
-        }
-
-        if (collapseWhitespace) {
-            result = result.replaceAll(/\s+/g, " ");
-        }
-
-        return result;
-    };
-};
+const findByDisplayValue: BuiltinQueries["findByDisplayValue"] = builtinQueries.findByDisplayValue;
 
 const buildNormalizer = (options?: MatcherOptions): NormalizerFn => {
     const { normalizer, trim, collapseWhitespace } = options ?? {};
@@ -361,7 +313,7 @@ const hasMatchingAccessibleValue = (widget: Gtk.Widget, value: ByRoleValue, opti
 
 const hasMatchingBooleanStates = (widget: Gtk.Widget, options: ByRoleOptions): boolean => {
     const stateChecks: [boolean | undefined, () => boolean | null][] = [
-        [options.checked, () => getWidgetCheckedState(widget)],
+        [options.checked, () => isWidgetChecked(widget)],
         [options.pressed, () => getWidgetPressedState(widget)],
         [options.expanded, () => getWidgetExpandedState(widget)],
         [options.selected, () => getWidgetSelectedState(widget)],
@@ -393,20 +345,27 @@ const hasMatchingAccessibleStates = (widget: Gtk.Widget, options: ByRoleOptions)
     hasMatchingDescriptionState(widget, options) &&
     hasMatchingValueState(widget, options);
 
+const isMatchingWidgetType = (widget: Gtk.Widget, options?: MatcherOptions): boolean =>
+    options?.as === undefined || widget instanceof options.as;
+
 const hasMatchingByRoleOptions = (widget: Gtk.Widget, options?: ByRoleOptions): boolean => {
     if (!options) {
         return true;
     }
 
-    return hasMatchingAccessibleName(widget, options) && hasMatchingAccessibleStates(widget, options);
+    return (
+        isMatchingWidgetType(widget, options) &&
+        hasMatchingAccessibleName(widget, options) &&
+        hasMatchingAccessibleStates(widget, options)
+    );
 };
 
-function nameQueryFamily<Suffix extends string, Args extends unknown[]>(
-    suffix: Suffix,
+function nameQueryFamily<Args extends unknown[]>(
+    suffix: string,
     queryAllBy: QueryAllBy<Args>,
     built: BuiltQueries<Args>,
-): NamedFamily<Suffix, Args> {
-    const family = {
+): Record<string, unknown> {
+    return {
         [`queryBy${suffix}`]: built.queryBy,
         [`queryAllBy${suffix}`]: queryAllBy,
         [`getBy${suffix}`]: built.getBy,
@@ -414,8 +373,6 @@ function nameQueryFamily<Suffix extends string, Args extends unknown[]>(
         [`findBy${suffix}`]: built.findBy,
         [`findAllBy${suffix}`]: built.findAllBy,
     };
-
-    return family as NamedFamily<Suffix, Args>;
 }
 
 /**
@@ -502,7 +459,7 @@ function queryAllByLabelText(container: Container, text: Matcher, options?: Matc
         collectLabelMatches(results, widget, text, options);
     }
 
-    return [...results];
+    return [...results].filter((widget) => isMatchingWidgetType(widget, options));
 }
 
 /**
@@ -513,7 +470,11 @@ function queryAllByLabelText(container: Container, text: Matcher, options?: Matc
  * @returns Every matching widget, or an empty array when none match.
  */
 function queryAllByText(container: Container, text: Matcher, options?: MatcherOptions): Gtk.Widget[] {
-    return findAll(container, (widget) => isTextMatch(getWidgetLabelText(widget), text, widget, options));
+    return findAll(
+        container,
+        (widget) =>
+            isMatchingWidgetType(widget, options) && isTextMatch(getWidgetLabelText(widget), text, widget, options),
+    );
 }
 
 /**
@@ -524,7 +485,10 @@ function queryAllByText(container: Container, text: Matcher, options?: MatcherOp
  * @returns Every matching widget, or an empty array when none match.
  */
 function queryAllByName(container: Container, name: Matcher, options?: MatcherOptions): Gtk.Widget[] {
-    return findAll(container, (widget) => isTextMatch(getWidgetName(widget), name, widget, options));
+    return findAll(
+        container,
+        (widget) => isMatchingWidgetType(widget, options) && isTextMatch(getWidgetName(widget), name, widget, options),
+    );
 }
 
 /**
@@ -539,7 +503,12 @@ function queryAllByPlaceholderText(
     text: Matcher,
     options?: MatcherOptions,
 ): Gtk.Widget[] {
-    return findAll(container, (widget) => isTextMatch(getWidgetPlaceholderText(widget), text, widget, options));
+    return findAll(
+        container,
+        (widget) =>
+            isMatchingWidgetType(widget, options) &&
+            isTextMatch(getWidgetPlaceholderText(widget), text, widget, options),
+    );
 }
 
 /**
@@ -550,7 +519,12 @@ function queryAllByPlaceholderText(
  * @returns Every matching widget, or an empty array when none match.
  */
 function queryAllByDisplayValue(container: Container, value: Matcher, options?: MatcherOptions): Gtk.Widget[] {
-    return findAll(container, (widget) => isTextMatch(getWidgetDisplayValue(widget), value, widget, options));
+    return findAll(
+        container,
+        (widget) =>
+            isMatchingWidgetType(widget, options) &&
+            isTextMatch(getWidgetDisplayValue(widget), value, widget, options),
+    );
 }
 
 export {
@@ -585,7 +559,6 @@ export {
     getByDisplayValue,
     findAllByDisplayValue,
     findByDisplayValue,
-    getDefaultNormalizer,
     queryAllByRole,
     queryAllByLabelText,
     queryAllByText,

package/src/render.tsx

@@ -97,7 +97,7 @@ const resolveContainer = (container: RenderOptions["container"]): ResolvedContai
     }
 
     const window = new Gtk.Window({ defaultWidth: HARNESS_WINDOW_WIDTH, defaultHeight: HARNESS_WINDOW_HEIGHT });
-    window.setTitlebar(new Gtk.HeaderBar({ showTitleButtons: false }));
+    window.setDecorated(false);
 
     return { containerInfo: window, window };
 };

package/src/types.ts

@@ -13,6 +13,11 @@ type MatcherFunction = (content: string, widget: Gtk.Widget) => boolean;
 type Matcher = string | number | RegExp | MatcherFunction;
 /** Normalizes a widget's text before it is compared against a matcher. */
 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. */
 type NormalizerOptions = {
@@ -35,7 +40,7 @@ type WaitForOptions = {
 };
 
 /** Options controlling text matching and, for asynchronous queries, polling behavior. */
-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`. */
@@ -46,6 +51,8 @@ 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. */
@@ -59,7 +66,7 @@ type ByRoleValue = {
 };
 
 /** Options for role queries: an accessible name matcher plus accessible state and value constraints. */
-type ByRoleOptions = MatcherOptions & {
+type ByRoleOptions<T extends Gtk.Widget = Gtk.Widget> = MatcherOptions<T> & {
     name?: Matcher | undefined;
     checked?: boolean | undefined;
     pressed?: boolean | undefined;
@@ -88,6 +95,43 @@ type BoundQuery<Q extends Query> = Q extends (container: Container, ...args: inf
 
 type BoundCustomQueries<Q extends QueryMap> = { [K in keyof Q]: BoundQuery<Q[K]> };
 
+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.
@@ -169,9 +213,11 @@ export {
     type MatcherOptions,
     type ByRoleValue,
     type ByRoleOptions,
+    type WidgetType,
     type WrapperComponent,
     type QueryMap,
     type BoundCustomQueries,
+    type QueryFamilies,
     type RenderOptions,
     type DebugUtilities,
     type ScreenshotResult,

package/src/user-event/controller.ts

@@ -39,6 +39,19 @@ const getAllControllers = <T extends Gtk.EventController>(
     return controllers;
 };
 
+const getController = <T extends Gtk.EventController>(
+    widget: Gtk.Widget,
+    controllerType: ControllerConstructor<T>,
+): T => {
+    const [controller] = getAllControllers(widget, controllerType);
+
+    if (controller === undefined) {
+        throw new Error(`No ${controllerType.name} controller is attached to the widget`);
+    }
+
+    return controller;
+};
+
 const getOrCreateControllers = <T extends Gtk.EventController>(
     widget: Gtk.Widget,
     controllerType: ControllerConstructor<T>,
@@ -55,4 +68,11 @@ const getOrCreateControllers = <T extends Gtk.EventController>(
     return [controller];
 };
 
-export { queryAllControllers, queryController, getAllControllers, getOrCreateControllers, type ControllerConstructor };
+export {
+    queryAllControllers,
+    queryController,
+    getAllControllers,
+    getController,
+    getOrCreateControllers,
+    type ControllerConstructor,
+};