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

package/src/act.ts

@@ -4,65 +4,74 @@ declare global {
     var IS_REACT_ACT_ENVIRONMENT: boolean | undefined;
 }
 
+type ActCallback<T> = () => T | PromiseLike<T>;
+type ActImplementation = <T>(callback: ActCallback<T>) => PromiseLike<T>;
+
+const actImplementation: ActImplementation = reactAct;
+/**
+ * Runs a callback inside React's act environment, flushing pending state
+ * updates and effects, and resolves once the work has settled.
+ *
+ * @param callback Work to run within the act environment.
+ * @returns A promise that resolves with the callback's result after updates flush.
+ */
+const act: ActImplementation = withGlobalActEnvironment(actImplementation);
+
 const getGlobalThis = (): typeof globalThis => {
-    if (typeof globalThis !== "undefined") return globalThis;
+    if (typeof globalThis !== "undefined") {
+        return globalThis;
+    }
+
     throw new Error("unable to locate global object");
 };
 
-export const getIsReactActEnvironment = (): boolean | undefined => getGlobalThis().IS_REACT_ACT_ENVIRONMENT;
+const getIsReactActEnvironment = (): boolean | undefined => getGlobalThis().IS_REACT_ACT_ENVIRONMENT;
 
-export const setIsReactActEnvironment = (value: boolean | undefined): void => {
+const setIsReactActEnvironment = (value: boolean | undefined): void => {
     getGlobalThis().IS_REACT_ACT_ENVIRONMENT = value;
 };
 
-type ActCallback<T> = () => T | PromiseLike<T>;
-type ActImplementation = <T>(callback: ActCallback<T>) => PromiseLike<T>;
-
 const isThenable = <T>(value: unknown): value is PromiseLike<T> =>
     value !== null && typeof value === "object" && typeof (value as PromiseLike<T>).then === "function";
 
-export const runWithActEnvironment = <T>(forced: boolean, fn: () => T | PromiseLike<T>): T | PromiseLike<T> => {
+const restoreAfter = async <T>(result: PromiseLike<T>, previous: boolean | undefined): Promise<T> => {
+    try {
+        return await result;
+    } finally {
+        setIsReactActEnvironment(previous);
+    }
+};
+
+const runWithActEnvironment = <T>(isForced: boolean, fn: () => T | PromiseLike<T>): Promise<T> => {
     const previousActEnvironment = getIsReactActEnvironment();
-    setIsReactActEnvironment(forced);
+    setIsReactActEnvironment(isForced);
+
     try {
-        const result = fn();
+        const result: T | PromiseLike<T> = fn();
+
         if (isThenable<T>(result)) {
-            return Promise.resolve(result).then(
-                (value) => {
-                    setIsReactActEnvironment(previousActEnvironment);
-                    return value;
-                },
-                (error) => {
-                    setIsReactActEnvironment(previousActEnvironment);
-                    throw error;
-                },
-            );
+            return restoreAfter(result, previousActEnvironment);
         }
+
         setIsReactActEnvironment(previousActEnvironment);
-        return result;
+
+        return Promise.resolve(result);
     } catch (error) {
         setIsReactActEnvironment(previousActEnvironment);
         throw error;
     }
 };
 
-const withGlobalActEnvironment =
-    (actImplementation: ActImplementation) =>
-    <T>(callback: ActCallback<T>): PromiseLike<T> => {
+function withGlobalActEnvironment(actImplementation: ActImplementation): ActImplementation {
+    return <T>(callback: ActCallback<T>): PromiseLike<T> => {
         const settled = runWithActEnvironment(true, () => actImplementation(() => callback()));
+
         return Promise.resolve(settled);
     };
+}
 
-const actImplementation: ActImplementation = reactAct as ActImplementation;
-
-/**
- * Runs a callback inside React's act environment, flushing pending state
- * updates and effects, and resolves once the work has settled.
- *
- * @param callback Work to run within the act environment.
- * @returns A promise that resolves with the callback's result after updates flush.
- */
-export const act: ActImplementation = withGlobalActEnvironment(actImplementation);
+const runInAct = async (callback: () => unknown): Promise<void> => {
+    await act(() => callback());
+};
 
-export const runInAct = (callback: () => unknown): Promise<void> =>
-    Promise.resolve(act(() => callback())).then(() => undefined);
+export { act, getIsReactActEnvironment, setIsReactActEnvironment, runWithActEnvironment, runInAct };

package/src/bound-queries.ts

@@ -1,20 +1,18 @@
 import type * as Gtk from "@gtkx/gi/gtk";
 import type { ReactNode } from "react";
-import type { builtinQueries } from "./queries.js";
 import type { Container } from "./traversal.js";
-import type { BoundCustomQueries, DebugUtilities, QueryMap } from "./types.js";
+import type { BoundCustomQueries, DebugUtilities, QueryFamilies, QueryMap } from "./types.js";
 
 /**
  * The set of built-in queries (getBy, findBy, queryBy, and their All variants)
  * bound to a specific container.
  */
-export type BoundQueries = BoundCustomQueries<typeof builtinQueries>;
-
+type BoundQueries = QueryFamilies<[]>;
 /**
  * The global screen object's shape: built-in queries scoped to the current
  * toplevels, plus debug utilities.
  */
-export type Screen = BoundQueries & DebugUtilities;
+type Screen = BoundQueries & DebugUtilities;
 
 /**
  * The result of a render call: queries scoped to the rendered tree, debug
@@ -22,7 +20,7 @@ export type Screen = BoundQueries & DebugUtilities;
  *
  * @typeParam Q Custom queries provided at render time, merged with the built-in ones.
  */
-export type RenderResult<Q extends QueryMap = Record<never, never>> = BoundQueries &
+type RenderResult<Q extends QueryMap = Record<never, never>> = BoundQueries &
     BoundCustomQueries<Q> &
     DebugUtilities & {
         /** The top-level widget the element was rendered into. */
@@ -34,3 +32,5 @@ export type RenderResult<Q extends QueryMap = Record<never, never>> = BoundQueri
         /** Re-renders the tree with a new element, reusing the same root. */
         rerender: (element: ReactNode) => Promise<void>;
     };
+
+export { type BoundQueries, type Screen, type RenderResult };

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 };