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

package/src/queries.ts

@@ -1,12 +1,19 @@
 import * as Gtk from "@gtkx/gi/gtk";
-import { type BuiltQueries, buildQueries, type QueryAllBy } from "./build-queries.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 type { ByRoleOptions, ByRoleValue, Matcher, MatcherOptions, NormalizerFn, NormalizerOptions } from "./types.js";
 import {
     getWidgetAccessibleName,
     getWidgetBusyState,
-    getWidgetCheckedState,
     getWidgetDescription,
     getWidgetDisplayValue,
     getWidgetExpandedState,
@@ -20,30 +27,204 @@ import {
     getWidgetSelectedState,
     getWidgetValue,
     isInaccessible,
+    isWidgetChecked,
 } from "./widget-accessible-properties.js";
 
-/**
- * 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.
- */
-export const getDefaultNormalizer = ({
-    trim = true,
-    collapseWhitespace = true,
-}: NormalizerOptions = {}): NormalizerFn => {
-    return (text: string): string => {
-        let result = text;
-        if (trim) {
-            result = result.trim();
-        }
+type BuiltinQueries = QueryFamilies<[container: Container]>;
 
-        if (collapseWhitespace) {
-            result = result.replaceAll(/\s+/g, " ");
-        }
+const roleQueries = nameQueryFamily(
+    "Role",
+    queryAllByRole,
+    buildQueries<[role: Gtk.AccessibleRole, options?: ByRoleOptions]>(
+        "Role",
+        queryAllByRole,
+        (container, matches, role, options) =>
+            multipleFoundError(container, { queryType: "role", role, options }, matches),
+        (container, role, options) => notFoundError(container, { queryType: "role", role, options }),
+    ),
+);
 
-        return result;
-    };
-};
+const labelTextQueries = nameQueryFamily(
+    "LabelText",
+    queryAllByLabelText,
+    buildQueries<[text: Matcher, options?: MatcherOptions]>(
+        "LabelText",
+        queryAllByLabelText,
+        (container, matches, text) => multipleFoundError(container, { queryType: "labelText", text }, matches),
+        (container, text) => notFoundError(container, { queryType: "labelText", text }),
+    ),
+);
+
+const textQueries = nameQueryFamily(
+    "Text",
+    queryAllByText,
+    buildQueries<[text: Matcher, options?: MatcherOptions]>(
+        "Text",
+        queryAllByText,
+        (container, matches, text) => multipleFoundError(container, { queryType: "text", text }, matches),
+        (container, text) => notFoundError(container, { queryType: "text", text }),
+    ),
+);
+
+const nameQueries = nameQueryFamily(
+    "Name",
+    queryAllByName,
+    buildQueries<[name: Matcher, options?: MatcherOptions]>(
+        "Name",
+        queryAllByName,
+        (container, matches, name) => multipleFoundError(container, { queryType: "name", name }, matches),
+        (container, name) => notFoundError(container, { queryType: "name", name }),
+    ),
+);
+
+const placeholderTextQueries = nameQueryFamily(
+    "PlaceholderText",
+    queryAllByPlaceholderText,
+    buildQueries<[text: Matcher, options?: MatcherOptions]>(
+        "PlaceholderText",
+        queryAllByPlaceholderText,
+        (container, matches, text) => multipleFoundError(container, { queryType: "placeholderText", text }, matches),
+        (container, text) => notFoundError(container, { queryType: "placeholderText", text }),
+    ),
+);
+
+const displayValueQueries = nameQueryFamily(
+    "DisplayValue",
+    queryAllByDisplayValue,
+    buildQueries<[value: Matcher, options?: MatcherOptions]>(
+        "DisplayValue",
+        queryAllByDisplayValue,
+        (container, matches, value) => multipleFoundError(container, { queryType: "displayValue", value }, matches),
+        (container, value) => notFoundError(container, { queryType: "displayValue", value }),
+    ),
+);
+
+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"] = builtinQueries.queryByRole;
+/** Returns every widget with a matching accessible role and options. Throws when none match. */
+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"] = 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"] = 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"] = 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"] = builtinQueries.queryByLabelText;
+/** Returns every widget with matching associated label text. Throws when none match. */
+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"] = 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"] = 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"] = 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"] = builtinQueries.queryByText;
+/** Returns every widget with matching rendered text content. Throws when none match. */
+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"] = 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"] = 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"] = 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"] = builtinQueries.queryByName;
+/** Returns every widget with a matching widget name. Throws when none match. */
+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"] = 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"] = 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"] = 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"] = builtinQueries.queryByPlaceholderText;
+/** Returns every widget with matching placeholder text. Throws when none match. */
+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"] = 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"] = 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"] = 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"] = builtinQueries.queryByDisplayValue;
+/** Returns every widget with a matching display value. Throws when none match. */
+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"] = 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"] = 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"] = builtinQueries.findByDisplayValue;
 
 const buildNormalizer = (options?: MatcherOptions): NormalizerFn => {
     const { normalizer, trim, collapseWhitespace } = options ?? {};
@@ -55,8 +236,8 @@ const buildNormalizer = (options?: MatcherOptions): NormalizerFn => {
     if (trim !== undefined || collapseWhitespace !== undefined) {
         throw new Error(
             "trim and collapseWhitespace are not supported with a normalizer. " +
-                "If you want to use the default trim and collapseWhitespace logic in your normalizer, " +
-                'use "getDefaultNormalizer({ trim, collapseWhitespace })" and compose that into your normalizer',
+            "If you want to use the default trim and collapseWhitespace logic in your normalizer, " +
+            "use \"getDefaultNormalizer({ trim, collapseWhitespace })\" and compose that into your normalizer",
         );
     }
 
@@ -65,11 +246,19 @@ const buildNormalizer = (options?: MatcherOptions): NormalizerFn => {
 
 const normalizeText = (text: string, options?: MatcherOptions): string => {
     const normalizer = buildNormalizer(options);
+
     return normalizer(text);
 };
 
-const matchText = (actual: string | null, expected: Matcher, widget: Gtk.Widget, options?: MatcherOptions): boolean => {
-    if (actual === null) return false;
+const isTextMatch = (
+    actual: string | null,
+    expected: Matcher,
+    widget: Gtk.Widget,
+    options?: MatcherOptions,
+): boolean => {
+    if (actual === null) {
+        return false;
+    }
 
     const normalizedActual = normalizeText(actual, options);
 
@@ -79,77 +268,104 @@ const matchText = (actual: string | null, expected: Matcher, widget: Gtk.Widget,
 
     if (expected instanceof RegExp) {
         expected.lastIndex = 0;
+
         return expected.test(normalizedActual);
     }
 
     const normalizedExpected = normalizeText(String(expected), options);
-    const exact = options?.exact ?? true;
-    return exact
+    const isExact = options?.exact ?? true;
+
+    return isExact
         ? normalizedActual === normalizedExpected
         : normalizedActual.toLowerCase().includes(normalizedExpected.toLowerCase());
 };
 
-const matchAccessibleName = (widget: Gtk.Widget, options: ByRoleOptions): boolean => {
-    if (options.name === undefined) return true;
+const hasMatchingAccessibleName = (widget: Gtk.Widget, options: ByRoleOptions): boolean => {
+    if (options.name === undefined) {
+        return true;
+    }
+
     const text = getWidgetAccessibleName(widget);
-    return matchText(text, options.name, widget, options);
+
+    return isTextMatch(text, options.name, widget, options);
 };
 
-const matchAccessibleValue = (widget: Gtk.Widget, value: ByRoleValue, options: ByRoleOptions): boolean => {
+const isNumericValueMatch = (expected: number | undefined, actual: number | null): boolean =>
+    expected === undefined || actual === expected;
+
+const hasMatchingAccessibleValue = (widget: Gtk.Widget, value: ByRoleValue, options: ByRoleOptions): boolean => {
     const actual = getWidgetValue(widget);
-    if (value.now !== undefined && actual.now !== value.now) return false;
-    if (value.min !== undefined && actual.min !== value.min) return false;
-    if (value.max !== undefined && actual.max !== value.max) return false;
-    if (value.text !== undefined && !matchText(actual.text, value.text, widget, options)) return false;
-    return true;
-};
 
-const matchBooleanStates = (widget: Gtk.Widget, options: ByRoleOptions): boolean => {
-    if (options.checked !== undefined && getWidgetCheckedState(widget) !== options.checked) return false;
-    if (options.pressed !== undefined && getWidgetPressedState(widget) !== options.pressed) return false;
-    if (options.expanded !== undefined && getWidgetExpandedState(widget) !== options.expanded) return false;
-    if (options.selected !== undefined && getWidgetSelectedState(widget) !== options.selected) return false;
-    if (options.busy !== undefined && (getWidgetBusyState(widget) ?? false) !== options.busy) return false;
-    return true;
+    const numericChecks: [number | undefined, number | null][] = [
+        [value.now, actual.now],
+        [value.min, actual.min],
+        [value.max, actual.max],
+    ];
+
+    for (const [expected, current] of numericChecks) {
+        if (!isNumericValueMatch(expected, current)) {
+            return false;
+        }
+    }
+
+    return value.text === undefined || isTextMatch(actual.text, value.text, widget, options);
 };
 
-const matchAccessibleStates = (widget: Gtk.Widget, options: ByRoleOptions): boolean => {
-    if (!matchBooleanStates(widget, options)) return false;
-    if (options.level !== undefined && getWidgetLevel(widget) !== options.level) return false;
-    if (
-        options.description !== undefined &&
-        !matchText(getWidgetDescription(widget), options.description, widget, options)
-    )
-        return false;
-    if (options.value !== undefined && !matchAccessibleValue(widget, options.value, options)) return false;
+const hasMatchingBooleanStates = (widget: Gtk.Widget, options: ByRoleOptions): boolean => {
+    const stateChecks: [boolean | undefined, () => boolean | null][] = [
+        [options.checked, () => isWidgetChecked(widget)],
+        [options.pressed, () => getWidgetPressedState(widget)],
+        [options.expanded, () => getWidgetExpandedState(widget)],
+        [options.selected, () => getWidgetSelectedState(widget)],
+        [options.busy, () => getWidgetBusyState(widget) ?? false],
+    ];
+
+    for (const [expected, getActual] of stateChecks) {
+        if (expected !== undefined && getActual() !== expected) {
+            return false;
+        }
+    }
+
     return true;
 };
 
-const matchByRoleOptions = (widget: Gtk.Widget, options?: ByRoleOptions): boolean => {
-    if (!options) return true;
-    return matchAccessibleName(widget, options) && matchAccessibleStates(widget, options);
-};
+const hasMatchingLevelState = (widget: Gtk.Widget, options: ByRoleOptions): boolean =>
+    options.level === undefined || getWidgetLevel(widget) === options.level;
+
+const hasMatchingDescriptionState = (widget: Gtk.Widget, options: ByRoleOptions): boolean =>
+    options.description === undefined ||
+    isTextMatch(getWidgetDescription(widget), options.description, widget, options);
 
-type NamedFamily<Suffix extends string, Args extends unknown[]> = {
-    [P in `queryBy${Suffix}`]: (container: Container, ...args: Args) => Gtk.Widget | null;
-} & {
-    [P in `queryAllBy${Suffix}`]: (container: Container, ...args: Args) => Gtk.Widget[];
-} & {
-    [P in `getBy${Suffix}`]: (container: Container, ...args: Args) => Gtk.Widget;
-} & {
-    [P in `getAllBy${Suffix}`]: (container: Container, ...args: Args) => Gtk.Widget[];
-} & {
-    [P in `findBy${Suffix}`]: (container: Container, ...args: Args) => Promise<Gtk.Widget>;
-} & {
-    [P in `findAllBy${Suffix}`]: (container: Container, ...args: Args) => Promise<Gtk.Widget[]>;
+const hasMatchingValueState = (widget: Gtk.Widget, options: ByRoleOptions): boolean =>
+    options.value === undefined || hasMatchingAccessibleValue(widget, options.value, options);
+
+const hasMatchingAccessibleStates = (widget: Gtk.Widget, options: ByRoleOptions): boolean =>
+    hasMatchingBooleanStates(widget, options) &&
+    hasMatchingLevelState(widget, options) &&
+    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 (
+        isMatchingWidgetType(widget, options) &&
+        hasMatchingAccessibleName(widget, options) &&
+        hasMatchingAccessibleStates(widget, options)
+    );
 };
 
-const 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,
@@ -157,8 +373,7 @@ const nameQueryFamily = <Suffix extends string, Args extends unknown[]>(
         [`findBy${suffix}`]: built.findBy,
         [`findAllBy${suffix}`]: built.findAllBy,
     };
-    return family as NamedFamily<Suffix, Args>;
-};
+}
 
 /**
  * Finds every widget under the container whose accessible role matches `role` and that satisfies the given options.
@@ -168,70 +383,84 @@ const nameQueryFamily = <Suffix extends string, Args extends unknown[]>(
  * @param options Additional accessible name, state, and value constraints.
  * @returns Every matching widget, or an empty array when none match.
  */
-export const queryAllByRole = (container: Container, role: Gtk.AccessibleRole, options?: ByRoleOptions): Gtk.Widget[] =>
-    findAll(container, (widget) => {
-        if (widget.getAccessibleRole() !== role) return false;
-        if (!options?.hidden && isInaccessible(widget)) return false;
-        return matchByRoleOptions(widget, options);
-    });
+function queryAllByRole(
+    container: Container,
+    role: Gtk.AccessibleRole,
+    options?: ByRoleOptions,
+): Gtk.Widget[] {
+    return findAll(container, (widget) => {
+        if (widget.getAccessibleRole() !== role) {
+            return false;
+        }
 
-const roleQueries = nameQueryFamily(
-    "Role",
-    queryAllByRole,
-    buildQueries<[role: Gtk.AccessibleRole, options?: ByRoleOptions]>(
-        "Role",
-        queryAllByRole,
-        (container, matches, role, options) =>
-            multipleFoundError(container, { queryType: "role", role, options }, matches),
-        (container, role, options) => notFoundError(container, { queryType: "role", role, options }),
-    ),
-);
+        if (!options?.hidden && isInaccessible(widget)) {
+            return false;
+        }
+
+        return hasMatchingByRoleOptions(widget, options);
+    });
+}
 
 const collectMnemonicMatch = (
     widget: Gtk.Widget,
     text: Matcher,
     options: MatcherOptions | undefined,
 ): Gtk.Widget | null => {
-    if (!(widget instanceof Gtk.Label)) return null;
+    if (!(widget instanceof Gtk.Label)) {
+        return null;
+    }
+
     const labelText = widget.getLabel();
-    if (!labelText || !matchText(labelText, text, widget, options)) return null;
+
+    if (!labelText || !isTextMatch(labelText, text, widget, options)) {
+        return null;
+    }
+
     return widget.getMnemonicWidget();
 };
 
+const collectLabelMatches = (
+    results: Set<Gtk.Widget>,
+    widget: Gtk.Widget,
+    text: Matcher,
+    options: MatcherOptions | undefined,
+): void => {
+    const mnemonicTarget = collectMnemonicMatch(widget, text, options);
+
+    if (mnemonicTarget) {
+        results.add(mnemonicTarget);
+    }
+
+    const ownLabel = getWidgetOwnLabel(widget);
+
+    if (ownLabel !== null && isTextMatch(ownLabel, text, widget, options)) {
+        results.add(widget);
+    }
+
+    const labelledByText = getWidgetLabelledByText(widget);
+
+    if (labelledByText !== null && isTextMatch(labelledByText, text, widget, options)) {
+        results.add(widget);
+    }
+};
+
 /**
- * Finds every widget associated with a label whose text matches: a Gtk.Label mnemonic target, the widget's own accessible label, or its labelled-by relation.
+ * Finds every widget associated with a label whose text matches: a Gtk.Label mnemonic target, the
+ * widget's own accessible label, or its labelled-by relation.
  * @param container Widget subtree to search.
  * @param text Matcher for the label text.
  * @param options Text matching options.
  * @returns Every matching widget, or an empty array when none match.
  */
-export const queryAllByLabelText = (container: Container, text: Matcher, options?: MatcherOptions): Gtk.Widget[] => {
-    const results = new Set<Gtk.Widget>();
+function queryAllByLabelText(container: Container, text: Matcher, options?: MatcherOptions): Gtk.Widget[] {
+    const results: Set<Gtk.Widget> = new Set();
 
     for (const widget of traverse(container)) {
-        const mnemonicTarget = collectMnemonicMatch(widget, text, options);
-        if (mnemonicTarget) results.add(mnemonicTarget);
-
-        const ownLabel = getWidgetOwnLabel(widget);
-        if (ownLabel !== null && matchText(ownLabel, text, widget, options)) results.add(widget);
-
-        const labelledByText = getWidgetLabelledByText(widget);
-        if (labelledByText !== null && matchText(labelledByText, text, widget, options)) results.add(widget);
+        collectLabelMatches(results, widget, text, options);
     }
 
-    return [...results];
-};
-
-const labelTextQueries = nameQueryFamily(
-    "LabelText",
-    queryAllByLabelText,
-    buildQueries<[text: Matcher, options?: MatcherOptions]>(
-        "LabelText",
-        queryAllByLabelText,
-        (container, matches, text) => multipleFoundError(container, { queryType: "labelText", text }, matches),
-        (container, text) => notFoundError(container, { queryType: "labelText", text }),
-    ),
-);
+    return [...results].filter((widget) => isMatchingWidgetType(widget, options));
+}
 
 /**
  * Finds every widget whose rendered text content matches.
@@ -240,19 +469,13 @@ const labelTextQueries = nameQueryFamily(
  * @param options Text matching options.
  * @returns Every matching widget, or an empty array when none match.
  */
-export const queryAllByText = (container: Container, text: Matcher, options?: MatcherOptions): Gtk.Widget[] =>
-    findAll(container, (widget) => matchText(getWidgetLabelText(widget), text, widget, options));
-
-const textQueries = nameQueryFamily(
-    "Text",
-    queryAllByText,
-    buildQueries<[text: Matcher, options?: MatcherOptions]>(
-        "Text",
-        queryAllByText,
-        (container, matches, text) => multipleFoundError(container, { queryType: "text", text }, matches),
-        (container, text) => notFoundError(container, { queryType: "text", text }),
-    ),
-);
+function queryAllByText(container: Container, text: Matcher, options?: MatcherOptions): Gtk.Widget[] {
+    return findAll(
+        container,
+        (widget) =>
+            isMatchingWidgetType(widget, options) && isTextMatch(getWidgetLabelText(widget), text, widget, options),
+    );
+}
 
 /**
  * Finds every widget whose widget name matches.
@@ -261,19 +484,12 @@ const textQueries = nameQueryFamily(
  * @param options Text matching options.
  * @returns Every matching widget, or an empty array when none match.
  */
-export const queryAllByName = (container: Container, name: Matcher, options?: MatcherOptions): Gtk.Widget[] =>
-    findAll(container, (widget) => matchText(getWidgetName(widget), name, widget, options));
-
-const nameQueries = nameQueryFamily(
-    "Name",
-    queryAllByName,
-    buildQueries<[name: Matcher, options?: MatcherOptions]>(
-        "Name",
-        queryAllByName,
-        (container, matches, name) => multipleFoundError(container, { queryType: "name", name }, matches),
-        (container, name) => notFoundError(container, { queryType: "name", name }),
-    ),
-);
+function queryAllByName(container: Container, name: Matcher, options?: MatcherOptions): Gtk.Widget[] {
+    return findAll(
+        container,
+        (widget) => isMatchingWidgetType(widget, options) && isTextMatch(getWidgetName(widget), name, widget, options),
+    );
+}
 
 /**
  * Finds every widget whose placeholder text matches.
@@ -282,22 +498,18 @@ const nameQueries = nameQueryFamily(
  * @param options Text matching options.
  * @returns Every matching widget, or an empty array when none match.
  */
-export const queryAllByPlaceholderText = (
+function queryAllByPlaceholderText(
     container: Container,
     text: Matcher,
     options?: MatcherOptions,
-): Gtk.Widget[] => findAll(container, (widget) => matchText(getWidgetPlaceholderText(widget), text, widget, options));
-
-const placeholderTextQueries = nameQueryFamily(
-    "PlaceholderText",
-    queryAllByPlaceholderText,
-    buildQueries<[text: Matcher, options?: MatcherOptions]>(
-        "PlaceholderText",
-        queryAllByPlaceholderText,
-        (container, matches, text) => multipleFoundError(container, { queryType: "placeholderText", text }, matches),
-        (container, text) => notFoundError(container, { queryType: "placeholderText", text }),
-    ),
-);
+): Gtk.Widget[] {
+    return findAll(
+        container,
+        (widget) =>
+            isMatchingWidgetType(widget, options) &&
+            isTextMatch(getWidgetPlaceholderText(widget), text, widget, options),
+    );
+}
 
 /**
  * Finds every widget whose current display value matches.
@@ -306,102 +518,52 @@ const placeholderTextQueries = nameQueryFamily(
  * @param options Text matching options.
  * @returns Every matching widget, or an empty array when none match.
  */
-export const queryAllByDisplayValue = (container: Container, value: Matcher, options?: MatcherOptions): Gtk.Widget[] =>
-    findAll(container, (widget) => matchText(getWidgetDisplayValue(widget), value, widget, options));
-
-const displayValueQueries = nameQueryFamily(
-    "DisplayValue",
+function queryAllByDisplayValue(container: Container, value: Matcher, options?: MatcherOptions): Gtk.Widget[] {
+    return findAll(
+        container,
+        (widget) =>
+            isMatchingWidgetType(widget, options) &&
+            isTextMatch(getWidgetDisplayValue(widget), value, widget, options),
+    );
+}
+
+export {
+    builtinQueries,
+    queryByRole,
+    getAllByRole,
+    getByRole,
+    findAllByRole,
+    findByRole,
+    queryByLabelText,
+    getAllByLabelText,
+    getByLabelText,
+    findAllByLabelText,
+    findByLabelText,
+    queryByText,
+    getAllByText,
+    getByText,
+    findAllByText,
+    findByText,
+    queryByName,
+    getAllByName,
+    getByName,
+    findAllByName,
+    findByName,
+    queryByPlaceholderText,
+    getAllByPlaceholderText,
+    getByPlaceholderText,
+    findAllByPlaceholderText,
+    findByPlaceholderText,
+    queryByDisplayValue,
+    getAllByDisplayValue,
+    getByDisplayValue,
+    findAllByDisplayValue,
+    findByDisplayValue,
+    queryAllByRole,
+    queryAllByLabelText,
+    queryAllByText,
+    queryAllByName,
+    queryAllByPlaceholderText,
     queryAllByDisplayValue,
-    buildQueries<[value: Matcher, options?: MatcherOptions]>(
-        "DisplayValue",
-        queryAllByDisplayValue,
-        (container, matches, value) => multipleFoundError(container, { queryType: "displayValue", value }, matches),
-        (container, value) => notFoundError(container, { queryType: "displayValue", value }),
-    ),
-);
-
-export 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]>;
-
-export const builtinQueries: BuiltinQueries = {
-    ...roleQueries,
-    ...labelTextQueries,
-    ...textQueries,
-    ...nameQueries,
-    ...placeholderTextQueries,
-    ...displayValueQueries,
+    type BuiltinQueries,
 };
-
-/** Returns the single widget with a matching accessible role and options, or null when none match. Throws when more than one matches. */
-export const queryByRole: BuiltinQueries["queryByRole"] = roleQueries.queryByRole;
-/** Returns every widget with a matching accessible role and options. Throws when none match. */
-export const getAllByRole: BuiltinQueries["getAllByRole"] = roleQueries.getAllByRole;
-/** Returns the single widget with a matching accessible role and options. Throws when none or more than one matches. */
-export const getByRole: BuiltinQueries["getByRole"] = roleQueries.getByRole;
-/** Waits for and returns every widget with a matching accessible role and options, retrying until at least one appears or the timeout elapses. */
-export const findAllByRole: BuiltinQueries["findAllByRole"] = roleQueries.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. */
-export const findByRole: BuiltinQueries["findByRole"] = roleQueries.findByRole;
-
-/** Returns the single widget with matching associated label text, or null when none match. Throws when more than one matches. */
-export const queryByLabelText: BuiltinQueries["queryByLabelText"] = labelTextQueries.queryByLabelText;
-/** Returns every widget with matching associated label text. Throws when none match. */
-export const getAllByLabelText: BuiltinQueries["getAllByLabelText"] = labelTextQueries.getAllByLabelText;
-/** Returns the single widget with matching associated label text. Throws when none or more than one matches. */
-export const getByLabelText: BuiltinQueries["getByLabelText"] = labelTextQueries.getByLabelText;
-/** Waits for and returns every widget with matching associated label text, retrying until at least one appears or the timeout elapses. */
-export const findAllByLabelText: BuiltinQueries["findAllByLabelText"] = labelTextQueries.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. */
-export const findByLabelText: BuiltinQueries["findByLabelText"] = labelTextQueries.findByLabelText;
-
-/** Returns the single widget with matching rendered text content, or null when none match. Throws when more than one matches. */
-export const queryByText: BuiltinQueries["queryByText"] = textQueries.queryByText;
-/** Returns every widget with matching rendered text content. Throws when none match. */
-export const getAllByText: BuiltinQueries["getAllByText"] = textQueries.getAllByText;
-/** Returns the single widget with matching rendered text content. Throws when none or more than one matches. */
-export const getByText: BuiltinQueries["getByText"] = textQueries.getByText;
-/** Waits for and returns every widget with matching rendered text content, retrying until at least one appears or the timeout elapses. */
-export const findAllByText: BuiltinQueries["findAllByText"] = textQueries.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. */
-export const findByText: BuiltinQueries["findByText"] = textQueries.findByText;
-
-/** Returns the single widget with a matching widget name, or null when none match. Throws when more than one matches. */
-export const queryByName: BuiltinQueries["queryByName"] = nameQueries.queryByName;
-/** Returns every widget with a matching widget name. Throws when none match. */
-export const getAllByName: BuiltinQueries["getAllByName"] = nameQueries.getAllByName;
-/** Returns the single widget with a matching widget name. Throws when none or more than one matches. */
-export const getByName: BuiltinQueries["getByName"] = nameQueries.getByName;
-/** Waits for and returns every widget with a matching widget name, retrying until at least one appears or the timeout elapses. */
-export const findAllByName: BuiltinQueries["findAllByName"] = nameQueries.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. */
-export const findByName: BuiltinQueries["findByName"] = nameQueries.findByName;
-
-/** Returns the single widget with matching placeholder text, or null when none match. Throws when more than one matches. */
-export const queryByPlaceholderText: BuiltinQueries["queryByPlaceholderText"] =
-    placeholderTextQueries.queryByPlaceholderText;
-/** Returns every widget with matching placeholder text. Throws when none match. */
-export const getAllByPlaceholderText: BuiltinQueries["getAllByPlaceholderText"] =
-    placeholderTextQueries.getAllByPlaceholderText;
-/** Returns the single widget with matching placeholder text. Throws when none or more than one matches. */
-export const getByPlaceholderText: BuiltinQueries["getByPlaceholderText"] = placeholderTextQueries.getByPlaceholderText;
-/** Waits for and returns every widget with matching placeholder text, retrying until at least one appears or the timeout elapses. */
-export const findAllByPlaceholderText: BuiltinQueries["findAllByPlaceholderText"] =
-    placeholderTextQueries.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. */
-export const findByPlaceholderText: BuiltinQueries["findByPlaceholderText"] =
-    placeholderTextQueries.findByPlaceholderText;
-
-/** Returns the single widget with a matching display value, or null when none match. Throws when more than one matches. */
-export const queryByDisplayValue: BuiltinQueries["queryByDisplayValue"] = displayValueQueries.queryByDisplayValue;
-/** Returns every widget with a matching display value. Throws when none match. */
-export const getAllByDisplayValue: BuiltinQueries["getAllByDisplayValue"] = displayValueQueries.getAllByDisplayValue;
-/** Returns the single widget with a matching display value. Throws when none or more than one matches. */
-export const getByDisplayValue: BuiltinQueries["getByDisplayValue"] = displayValueQueries.getByDisplayValue;
-/** Waits for and returns every widget with a matching display value, retrying until at least one appears or the timeout elapses. */
-export const findAllByDisplayValue: BuiltinQueries["findAllByDisplayValue"] = displayValueQueries.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. */
-export const findByDisplayValue: BuiltinQueries["findByDisplayValue"] = displayValueQueries.findByDisplayValue;