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

package/src/build-queries.ts

@@ -1,21 +1,22 @@
 import type * as Gtk from "@gtkx/gi/gtk";
+import type { Container } from "./traversal.js";
+import type { MatcherOptions, WaitForOptions } from "./types.js";
 import { getConfig } from "./config.js";
 import { runWithExpensiveErrorDiagnosticsDisabled, suggestionError } from "./errors.js";
 import { getSuggestedQuery, type Method, type Variant } from "./suggestions.js";
-import type { Container } from "./traversal.js";
-import type { MatcherOptions, WaitForOptions } from "./types.js";
 import { waitFor } from "./wait-for.js";
 
-export type QueryAllBy<Args extends unknown[]> = (container: Container, ...args: Args) => Gtk.Widget[];
+type QueryAllBy<Args extends unknown[]> = (container: Container, ...args: Args) => Gtk.Widget[];
 
 type MultipleErrorBuilder<Args extends unknown[]> = (
     container: Container,
     matches: Gtk.Widget[],
     ...args: Args
 ) => Error;
+
 type MissingErrorBuilder<Args extends unknown[]> = (container: Container, ...args: Args) => Error;
 
-export type BuiltQueries<Args extends unknown[]> = {
+type BuiltQueries<Args extends unknown[]> = {
     queryBy: (container: Container, ...args: Args) => Gtk.Widget | null;
     getAllBy: QueryAllBy<Args>;
     getBy: (container: Container, ...args: Args) => Gtk.Widget;
@@ -23,20 +24,28 @@ export type BuiltQueries<Args extends unknown[]> = {
     findBy: (container: Container, ...args: Args) => Promise<Gtk.Widget>;
 };
 
+type FindQuery<Args extends unknown[]> = (container: Container, ...args: Args) => unknown;
+type SingleQuery<Args extends unknown[]> = (container: Container, ...args: Args) => Gtk.Widget | null;
+
 const extractWaitForOptions = (args: unknown[]): WaitForOptions => {
-    const last = args[args.length - 1];
+    const last = args.at(-1);
+
     if (last && typeof last === "object" && !(last instanceof RegExp)) {
         const { timeout, interval, onTimeout } = last as WaitForOptions;
+
         return { timeout, interval, onTimeout };
     }
+
     return {};
 };
 
 const extractSuggestOption = (args: unknown[]): boolean | undefined => {
-    const last = args[args.length - 1];
+    const last = args.at(-1);
+
     if (last && typeof last === "object" && !(last instanceof RegExp)) {
         return (last as MatcherOptions).suggest;
     }
+
     return undefined;
 };
 
@@ -49,16 +58,18 @@ const maybeThrowSuggestion = (options: {
 }): void => {
     const { container, match, queryName, variant, suggest } = options;
     const shouldSuggest = suggest ?? getConfig().throwSuggestions;
-    if (!shouldSuggest) return;
+
+    if (!shouldSuggest) {
+        return;
+    }
 
     const suggestion = getSuggestedQuery(match, variant);
+
     if (suggestion && suggestion.queryName !== queryName) {
         throw suggestionError(suggestion.toString(), container);
     }
 };
 
-type FindQuery<Args extends unknown[]> = (container: Container, ...args: Args) => unknown;
-
 const reRunForDiagnostics = <Args extends unknown[]>(
     query: FindQuery<Args>,
     container: Container,
@@ -68,8 +79,11 @@ const reRunForDiagnostics = <Args extends unknown[]>(
     try {
         query(container, ...args);
     } catch (error) {
-        if (error instanceof Error) return error;
+        if (error instanceof Error) {
+            return error;
+        }
     }
+
     return fallback;
 };
 
@@ -79,8 +93,10 @@ const findOptions = <Args extends unknown[]>(
     args: Args,
 ): WaitForOptions => {
     const userOptions = extractWaitForOptions(args);
+
     const onTimeout =
         userOptions.onTimeout ?? ((fallback: Error) => reRunForDiagnostics(query, container, args, fallback));
+
     return {
         stackTraceError: new Error("STACK_TRACE_MESSAGE"),
         onTimeout,
@@ -89,60 +105,80 @@ const findOptions = <Args extends unknown[]>(
     };
 };
 
-type SingleQuery<Args extends unknown[]> = (container: Container, ...args: Args) => Gtk.Widget | null;
-
 const singleFrom =
     <Args extends unknown[]>(
         allQuery: QueryAllBy<Args>,
         getMultipleError: MultipleErrorBuilder<Args>,
     ): SingleQuery<Args> =>
-    (container, ...args) => {
-        const matches = allQuery(container, ...args);
-        if (matches.length > 1) throw getMultipleError(container, matches, ...args);
-        return matches[0] ?? null;
-    };
+        (container, ...args) => {
+            const matches = allQuery(container, ...args);
+
+            if (matches.length > 1) {
+                throw getMultipleError(container, matches, ...args);
+            }
+
+            return matches[0] ?? null;
+        };
 
 const allOrThrow =
     <Args extends unknown[]>(
         allQuery: QueryAllBy<Args>,
         getMissingError: MissingErrorBuilder<Args>,
     ): QueryAllBy<Args> =>
-    (container, ...args) => {
-        const matches = allQuery(container, ...args);
-        if (matches.length === 0) throw getMissingError(container, ...args);
-        return matches;
-    };
+        (container, ...args) => {
+            const matches = allQuery(container, ...args);
+
+            if (matches.length === 0) {
+                throw getMissingError(container, ...args);
+            }
+
+            return matches;
+        };
 
 const wrapSingleWithSuggestion =
     <Args extends unknown[]>(query: SingleQuery<Args>, queryName: Method, variant: Variant): SingleQuery<Args> =>
-    (container, ...args) => {
-        const match = query(container, ...args);
-        if (match) {
-            maybeThrowSuggestion({ container, match, queryName, variant, suggest: extractSuggestOption(args) });
-        }
-        return match;
-    };
+        (container, ...args) => {
+            const match = query(container, ...args);
+
+            if (match) {
+                maybeThrowSuggestion({ container, match, queryName, variant, suggest: extractSuggestOption(args) });
+            }
+
+            return match;
+        };
 
 const wrapAllWithSuggestion =
     <Args extends unknown[]>(query: QueryAllBy<Args>, queryName: Method, variant: Variant): QueryAllBy<Args> =>
-    (container, ...args) => {
-        const matches = query(container, ...args);
-        const [first] = matches;
-        if (first !== undefined) {
-            maybeThrowSuggestion({ container, match: first, queryName, variant, suggest: extractSuggestOption(args) });
-        }
-        return matches;
-    };
+        (container, ...args) => {
+            const matches = query(container, ...args);
+            const [first] = matches;
+
+            if (first !== undefined) {
+                maybeThrowSuggestion({
+                    container,
+                    match: first,
+                    queryName,
+                    variant,
+                    suggest: extractSuggestOption(args),
+                });
+            }
+
+            return matches;
+        };
 
 const requireSingle =
     <Args extends unknown[]>(query: SingleQuery<Args>, getMissingError: MissingErrorBuilder<Args>) =>
-    (container: Container, ...args: Args): Gtk.Widget => {
-        const match = query(container, ...args);
-        if (match === null) throw getMissingError(container, ...args);
-        return match;
-    };
+        (container: Container, ...args: Args): Gtk.Widget => {
+            const match = query(container, ...args);
+
+            if (match === null) {
+                throw getMissingError(container, ...args);
+            }
 
-export const buildQueries = <Args extends unknown[]>(
+            return match;
+        };
+
+const buildQueries = <Args extends unknown[]>(
     queryName: Method,
     queryAllBy: QueryAllBy<Args>,
     getMultipleError: MultipleErrorBuilder<Args>,
@@ -156,10 +192,13 @@ export const buildQueries = <Args extends unknown[]>(
         queryName,
         "query",
     );
+
     const getAllByWithSuggestion = wrapAllWithSuggestion(getAllBy, queryName, "getAll");
+
     const getByWithSuggestion: (container: Container, ...args: Args) => Gtk.Widget = (container, ...args) => {
         const match = getBy(container, ...args);
         maybeThrowSuggestion({ container, match, queryName, variant: "get", suggest: extractSuggestOption(args) });
+
         return match;
     };
 
@@ -183,3 +222,5 @@ export const buildQueries = <Args extends unknown[]>(
         findBy,
     };
 };
+
+export { buildQueries, type QueryAllBy, type BuiltQueries };

package/src/cleanup-registry.ts

@@ -1,14 +1,27 @@
-export type CleanupFunction = () => void | Promise<void>;
+type CleanupFunction = () => void | Promise<void>;
 
-const cleanupQueue = new Set<CleanupFunction>();
+const cleanupQueue: Set<CleanupFunction> = new Set();
 
-export const addToCleanupQueue = (fn: CleanupFunction): void => {
+const addToCleanupQueue = (fn: CleanupFunction): void => {
     cleanupQueue.add(fn);
 };
 
-export const runCleanup = async (): Promise<void> => {
+const runCleanup = async (): Promise<void> => {
+    const failures: unknown[] = [];
+
     for (const fn of cleanupQueue) {
-        await fn();
+        try {
+            await fn();
+        } catch (error) {
+            failures.push(error);
+        }
     }
+
     cleanupQueue.clear();
+
+    if (failures.length > 0) {
+        throw new AggregateError(failures, "Cleanup failed");
+    }
 };
+
+export { addToCleanupQueue, runCleanup, type CleanupFunction };

package/src/config.ts

@@ -5,7 +5,7 @@ import type { Container } from "./traversal.js";
  * error formatting, and the timeouts used by async utilities and actionability
  * checks.
  */
-export type Config = {
+type Config = {
     throwSuggestions: boolean;
 
     /** Builds the error thrown when a query fails, given a message and optional container. */
@@ -22,13 +22,7 @@ export type Config = {
  * Function form of a configuration update: receives the current config and
  * returns the fields to override.
  */
-export type ConfigFn = (existingConfig: Config) => Partial<Config>;
-
-const defaultGetElementError = (message: string, _container?: Container): Error => {
-    const error = new Error(message);
-    error.name = "GtkxElementError";
-    return error;
-};
+type ConfigFn = (existingConfig: Config) => Partial<Config>;
 
 const defaultConfig: Config = {
     throwSuggestions: false,
@@ -37,12 +31,16 @@ const defaultConfig: Config = {
     actionabilityTimeout: 500,
 };
 
-let currentConfig: Config = { ...defaultConfig };
+const currentConfig: Config = { ...defaultConfig };
+
+function defaultGetElementError(message: string): Error {
+    return new GtkxElementError(message);
+}
 
 /**
  * Returns the current global testing configuration.
  */
-export const getConfig = (): Config => {
+const getConfig = (): Config => {
     return currentConfig;
 };
 
@@ -52,7 +50,13 @@ export const getConfig = (): Config => {
  * @param newConfig Either a partial config object or a function that receives
  * the current config and returns the fields to override.
  */
-export const configure = (newConfig: Partial<Config> | ConfigFn): void => {
+const configure = (newConfig: Partial<Config> | ConfigFn): void => {
     const updates = typeof newConfig === "function" ? newConfig(currentConfig) : newConfig;
-    currentConfig = { ...currentConfig, ...updates };
+    Object.assign(currentConfig, updates);
 };
+
+class GtkxElementError extends Error {
+    override name = "GtkxElementError";
+}
+
+export { getConfig, configure, type Config, type ConfigFn };

package/src/editable.ts

@@ -1,30 +1,37 @@
 import * as Gtk from "@gtkx/gi/gtk";
 
-export type EditableTarget = Gtk.Editable | Gtk.TextView;
+type EditableTarget = Gtk.Editable | Gtk.TextView;
 
-export const EDITABLE_ROLES: Set<Gtk.AccessibleRole> = new Set<Gtk.AccessibleRole>([
+const EDITABLE_ROLES: Set<Gtk.AccessibleRole> = new Set<Gtk.AccessibleRole>([
     Gtk.AccessibleRole.TEXT_BOX,
     Gtk.AccessibleRole.SEARCH_BOX,
     Gtk.AccessibleRole.SPIN_BUTTON,
 ]);
 
-export const isEditable = (widget: unknown): widget is EditableTarget =>
+const isEditable = (widget: unknown): widget is EditableTarget =>
     widget instanceof Gtk.Editable || widget instanceof Gtk.TextView;
 
-export const getEditableDelegate = (widget: Gtk.Widget): Gtk.Widget | null => {
-    if (!(widget instanceof Gtk.Editable)) return null;
+const getEditableDelegate = (widget: Gtk.Widget): Gtk.Widget | null => {
+    if (!(widget instanceof Gtk.Editable)) {
+        return null;
+    }
+
     return widget.getDelegate();
 };
 
 const readTextViewBufferText = (widget: Gtk.TextView): string => {
     const buffer = widget.getBuffer();
     const [start, end] = buffer.getBounds();
+
     return buffer.getText(start, end, true);
 };
 
-export const readEditableText = (widget: EditableTarget): string => {
+const readEditableText = (widget: EditableTarget): string => {
     if (widget instanceof Gtk.TextView) {
         return readTextViewBufferText(widget);
     }
+
     return widget.getText();
 };
+
+export { EDITABLE_ROLES, isEditable, getEditableDelegate, readEditableText, type EditableTarget };

package/src/errors.ts

@@ -1,94 +1,140 @@
 import type * as Gtk from "@gtkx/gi/gtk";
+import type { Container } from "./traversal.js";
+import type { ByRoleOptions, ByRoleValue, Matcher } from "./types.js";
 import { getConfig } from "./config.js";
 import { prettyWidget } from "./pretty-widget.js";
 import { formatRole, prettyRoles } from "./role-helpers.js";
-import type { Container } from "./traversal.js";
-import type { ByRoleOptions, ByRoleValue, Matcher } from "./types.js";
+
+type QueryDescriptor =
+    | { queryType: "role"; role: Gtk.AccessibleRole; options?: ByRoleOptions | undefined } |
+    { queryType: "text"; text: Matcher } |
+    { queryType: "labelText"; text: Matcher } |
+    { queryType: "name"; name: Matcher } |
+    { queryType: "placeholderText"; text: Matcher } |
+    { queryType: "displayValue"; value: Matcher };
+
+const roleOptionFormatters: ((options: ByRoleOptions) => string | null)[] = [
+    (o) => (o.name ? `name ${formatTextMatcher(o.name)}` : null),
+    (o) => (o.checked === undefined ? null : `checked=${String(o.checked)}`),
+    (o) => (o.pressed === undefined ? null : `pressed=${String(o.pressed)}`),
+    (o) => (o.selected === undefined ? null : `selected=${String(o.selected)}`),
+    (o) => (o.expanded === undefined ? null : `expanded=${String(o.expanded)}`),
+    (o) => (o.level === undefined ? null : `level=${String(o.level)}`),
+    (o) => (o.busy === undefined ? null : `busy=${String(o.busy)}`),
+    (o) => (o.description ? `description ${formatTextMatcher(o.description)}` : null),
+    (o) => (o.value ? `value ${formatByRoleValue(o.value)}` : null),
+    (o) => (o.hidden === undefined ? null : `hidden=${String(o.hidden)}`),
+];
+
+const expensiveErrorDiagnostics = { isDisabled: false };
 
 const formatTextMatcher = (text: Matcher): string => {
     if (typeof text === "function") {
         return "custom function";
     }
+
     if (text instanceof RegExp) {
         return text.toString();
     }
-    return `'${text}'`;
+
+    return `'${String(text)}'`;
 };
 
 const formatByRoleValue = (value: ByRoleValue): string => {
     const parts: string[] = [];
-    if (value.now !== undefined) parts.push(`now=${value.now}`);
-    if (value.min !== undefined) parts.push(`min=${value.min}`);
-    if (value.max !== undefined) parts.push(`max=${value.max}`);
-    if (value.text !== undefined) parts.push(`text ${formatTextMatcher(value.text)}`);
+
+    if (value.now !== undefined) {
+        parts.push(`now=${String(value.now)}`);
+    }
+
+    if (value.min !== undefined) {
+        parts.push(`min=${String(value.min)}`);
+    }
+
+    if (value.max !== undefined) {
+        parts.push(`max=${String(value.max)}`);
+    }
+
+    if (value.text !== undefined) {
+        parts.push(`text ${formatTextMatcher(value.text)}`);
+    }
+
     return parts.join(", ");
 };
 
+const roleOptionParts = (options: ByRoleOptions): string[] => {
+    const parts: string[] = [];
+
+    for (const formatter of roleOptionFormatters) {
+        const part = formatter(options);
+
+        if (part !== null) {
+            parts.push(part);
+        }
+    }
+
+    return parts;
+};
+
 const formatByRoleDescription = (role: Gtk.AccessibleRole, options?: ByRoleOptions): string => {
     const parts = [`role '${formatRole(role).toUpperCase()}'`];
-    if (options?.name) parts.push(`name ${formatTextMatcher(options.name)}`);
-    if (options?.checked !== undefined) parts.push(`checked=${options.checked}`);
-    if (options?.pressed !== undefined) parts.push(`pressed=${options.pressed}`);
-    if (options?.selected !== undefined) parts.push(`selected=${options.selected}`);
-    if (options?.expanded !== undefined) parts.push(`expanded=${options.expanded}`);
-    if (options?.level !== undefined) parts.push(`level=${options.level}`);
-    if (options?.busy !== undefined) parts.push(`busy=${options.busy}`);
-    if (options?.description) parts.push(`description ${formatTextMatcher(options.description)}`);
-    if (options?.value) parts.push(`value ${formatByRoleValue(options.value)}`);
-    if (options?.hidden !== undefined) parts.push(`hidden=${options.hidden}`);
+
+    if (options) {
+        parts.push(...roleOptionParts(options));
+    }
+
     return parts.join(" and ");
 };
 
-export type QueryDescriptor =
-    | { queryType: "role"; role: Gtk.AccessibleRole; options?: ByRoleOptions | undefined }
-    | { queryType: "text"; text: Matcher }
-    | { queryType: "labelText"; text: Matcher }
-    | { queryType: "name"; name: Matcher }
-    | { queryType: "placeholderText"; text: Matcher }
-    | { queryType: "displayValue"; value: Matcher };
-
 const formatQueryDescription = (descriptor: QueryDescriptor): string => {
     switch (descriptor.queryType) {
-        case "role":
+        case "role": {
             return formatByRoleDescription(descriptor.role, descriptor.options);
-        case "text":
+        }
+        case "text": {
             return `text ${formatTextMatcher(descriptor.text)}`;
-        case "labelText":
+        }
+        case "labelText": {
             return `label text ${formatTextMatcher(descriptor.text)}`;
-        case "name":
+        }
+        case "name": {
             return `name ${formatTextMatcher(descriptor.name)}`;
-        case "placeholderText":
+        }
+        case "placeholderText": {
             return `placeholder text ${formatTextMatcher(descriptor.text)}`;
-        case "displayValue":
+        }
+        case "displayValue": {
             return `display value ${formatTextMatcher(descriptor.value)}`;
+        }
     }
 };
 
-let expensiveErrorDiagnosticsDisabled = false;
+const runWithExpensiveErrorDiagnosticsDisabled = <T>(callback: () => T): T => {
+    const isPrevious = expensiveErrorDiagnostics.isDisabled;
+    expensiveErrorDiagnostics.isDisabled = true;
 
-export const runWithExpensiveErrorDiagnosticsDisabled = <T>(callback: () => T): T => {
-    const previous = expensiveErrorDiagnosticsDisabled;
-    expensiveErrorDiagnosticsDisabled = true;
     try {
         return callback();
     } finally {
-        expensiveErrorDiagnosticsDisabled = previous;
+        expensiveErrorDiagnostics.isDisabled = isPrevious;
     }
 };
 
 const buildElementError = (container: Container, headLines: string[]): Error => {
     const config = getConfig();
-    const lines = expensiveErrorDiagnosticsDisabled
+
+    const lines = expensiveErrorDiagnostics.isDisabled
         ? headLines
         : [...headLines, "", prettyWidget(container, { highlight: false })];
+
     return config.getElementError(lines.join("\n"), container);
 };
 
-export const notFoundError = (container: Container, descriptor: QueryDescriptor): Error => {
+const notFoundError = (container: Container, descriptor: QueryDescriptor): Error => {
     const description = formatQueryDescription(descriptor);
     const headLines = [`Unable to find an element with ${description}`];
 
-    if (!expensiveErrorDiagnosticsDisabled && descriptor.queryType === "role") {
+    if (!expensiveErrorDiagnostics.isDisabled && descriptor.queryType === "role") {
         headLines.push("", "Here are the accessible roles:", "", prettyRoles(container));
     }
 
@@ -97,34 +143,49 @@ export const notFoundError = (container: Container, descriptor: QueryDescriptor)
 
 const allByVariantHint = (descriptor: QueryDescriptor): string => {
     const variant = descriptor.queryType === "role" ? "getAllByRole" : "getAllBy*";
+
     return (
         "(If this is intentional, use the *AllBy* variant of the query, " +
         `e.g. queryAllBy*/getAllBy*/findAllBy*, such as ${variant}.)`
     );
 };
 
-export const multipleFoundError = (container: Container, descriptor: QueryDescriptor, matches: Gtk.Widget[]): Error => {
+const multipleFoundError = (container: Container, descriptor: QueryDescriptor, matches: Gtk.Widget[]): Error => {
     const description = formatQueryDescription(descriptor);
+
     const headLines = [
-        `Found ${matches.length} elements with ${description}, but expected only one`,
+        `Found ${String(matches.length)} elements with ${description}, but expected only one`,
         "",
         allByVariantHint(descriptor),
     ];
-    if (!expensiveErrorDiagnosticsDisabled) {
+
+    if (!expensiveErrorDiagnostics.isDisabled) {
         const renderedMatches = matches.map((widget) => prettyWidget(widget, { highlight: false }));
         headLines.push("", "Here are the matching elements:", "", ...renderedMatches);
     }
+
     return buildElementError(container, headLines);
 };
 
-export const suggestionError = (suggestion: string, container: Container): Error => {
+const suggestionError = (suggestion: string, container: Container): Error => {
     const config = getConfig();
     const message = `A better query is available, try this:\n${suggestion}\n`;
+
     return config.getElementError(message, container);
 };
 
-export const timeoutError = (timeout: number, lastError: Error | null): Error => {
-    const baseMessage = `Timed out after ${timeout}ms`;
+const timeoutError = (timeout: number, lastError: Error | null): Error => {
+    const baseMessage = `Timed out after ${String(timeout)}ms`;
     const message = lastError ? `${baseMessage}.\n\n${lastError.message}` : baseMessage;
+
     return getConfig().getElementError(message);
 };
+
+export {
+    runWithExpensiveErrorDiagnosticsDisabled,
+    notFoundError,
+    multipleFoundError,
+    suggestionError,
+    timeoutError,
+    type QueryDescriptor,
+};

package/src/fire-event.ts

@@ -9,8 +9,10 @@ import { runInAct } from "./act.js";
  * @param signalName Name of the signal to emit.
  * @param args Arguments passed to the signal handlers.
  */
-export const fireEvent = async (element: GObject.Object, signalName: string, ...args: unknown[]): Promise<void> => {
+const fireEvent = async (element: GObject.Object, signalName: string, ...args: unknown[]): Promise<void> => {
     await runInAct(() => {
         element.emit(signalName, ...args);
     });
 };
+
+export { fireEvent };