@gtkx/testing 0.21.0 → 1.0.0-rc.2

package/dist/within.d.ts

@@ -1,30 +1,14 @@
-import type * as Gtk from "@gtkx/ffi/gtk";
-import type { BoundQueries } from "./types.js";
+import type { BoundQueries } from "./bound-queries.js";
+import type { Container } from "./traversal.js";
+import type { BoundCustomQueries, QueryMap } from "./types.js";
 /**
- * Creates scoped query methods for a container widget.
+ * Binds the built-in queries, and any custom queries, to a specific container
+ * so they search only within that scope.
  *
- * Use this to query within a specific section of your UI rather than
- * the entire application.
- *
- * @param container - The widget to scope queries to
- * @returns Object with query methods bound to the container
- *
- * @example
- * ```tsx
- * import { render, within } from "@gtkx/testing";
- *
- * test("scoped queries", async () => {
- *   await render(<MyPage />);
- *
- *   const sidebar = await screen.findByRole(Gtk.AccessibleRole.NAVIGATION);
- *   const sidebarQueries = within(sidebar);
- *
- *   // Only searches within the sidebar
- *   const navButton = await sidebarQueries.findByRole(Gtk.AccessibleRole.BUTTON);
- * });
- * ```
- *
- * @see {@link screen} for global queries
+ * @param container The scope the returned queries operate on.
+ * @param queries Optional custom queries to bind alongside the built-in ones.
+ * @returns The queries bound to the container.
  */
-export declare const within: (container: Gtk.Widget) => BoundQueries;
+declare const within: <Q extends QueryMap = Record<never, never>>(container: Container, queries?: Q) => BoundQueries & BoundCustomQueries<Q>;
+export { within };
 //# sourceMappingURL=within.d.ts.map

package/dist/within.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"within.d.ts","sourceRoot":"","sources":["../src/within.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,GAAG,MAAM,eAAe,CAAC;AAE1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,MAAM,GAAI,WAAW,GAAG,CAAC,MAAM,KAAG,YAAsC,CAAC"}
+{"version":3,"file":"within.d.ts","sourceRoot":"","sources":["../src/within.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAc/D;;;;;;;GAOG;AACH,QAAA,MAAM,MAAM,GAAI,CAAC,SAAS,QAAQ,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EACrD,WAAW,SAAS,EACpB,UAAU,CAAC,KACZ,YAAY,GAAG,kBAAkB,CAAC,CAAC,CAGpC,CAAC;AAEH,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist/within.js

@@ -1,29 +1,20 @@
-import { bindQueries } from "./bind-queries.js";
+import { builtinQueries } from "./queries.js";
+const bindQuery = (query, container) => (...args) => query(container, ...args);
+const bindCustomQueries = (customQueries, container) => {
+    const entries = Object.entries(customQueries).map(([key, query]) => [key, bindQuery(query, container)]);
+    return Object.fromEntries(entries);
+};
 /**
- * Creates scoped query methods for a container widget.
+ * Binds the built-in queries, and any custom queries, to a specific container
+ * so they search only within that scope.
  *
- * Use this to query within a specific section of your UI rather than
- * the entire application.
- *
- * @param container - The widget to scope queries to
- * @returns Object with query methods bound to the container
- *
- * @example
- * ```tsx
- * import { render, within } from "@gtkx/testing";
- *
- * test("scoped queries", async () => {
- *   await render(<MyPage />);
- *
- *   const sidebar = await screen.findByRole(Gtk.AccessibleRole.NAVIGATION);
- *   const sidebarQueries = within(sidebar);
- *
- *   // Only searches within the sidebar
- *   const navButton = await sidebarQueries.findByRole(Gtk.AccessibleRole.BUTTON);
- * });
- * ```
- *
- * @see {@link screen} for global queries
+ * @param container The scope the returned queries operate on.
+ * @param queries Optional custom queries to bind alongside the built-in ones.
+ * @returns The queries bound to the container.
  */
-export const within = (container) => bindQueries(container);
+const within = (container, queries) => ({
+    ...bindCustomQueries(builtinQueries, container),
+    ...(queries ? bindCustomQueries(queries, container) : {}),
+});
+export { within };
 //# sourceMappingURL=within.js.map

package/dist/within.js.map

@@ -1 +1 @@
-{"version":3,"file":"within.js","sourceRoot":"","sources":["../src/within.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,SAAqB,EAAgB,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC"}
+{"version":3,"file":"within.js","sourceRoot":"","sources":["../src/within.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,SAAS,GACX,CAAiC,KAAsD,EAAE,SAAoB,EAAE,EAAE,CAC7G,CAAC,GAAG,IAAU,EAAU,EAAE,CACtB,KAAK,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,CAAC;AAEtC,MAAM,iBAAiB,GAAG,CAAqB,aAAgB,EAAE,SAAoB,EAAyB,EAAE;IAC5G,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,CAAU,CAAC,CAAC;IAEjH,OAAO,MAAM,CAAC,WAAW,CAAC,OAAO,CAA0B,CAAC;AAChE,CAAC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,GAAG,CACX,SAAoB,EACpB,OAAW,EACyB,EAAE,CAAC,CAAC;IACxC,GAAG,iBAAiB,CAAC,cAAc,EAAE,SAAS,CAAC;IAC/C,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,CAAE,EAA4B,CAAC;CACvF,CAAC,CAAC;AAEH,OAAO,EAAE,MAAM,EAAE,CAAC","sourcesContent":["import type { BoundQueries } from \"./bound-queries.js\";\nimport type { Container } from \"./traversal.js\";\nimport type { BoundCustomQueries, QueryMap } from \"./types.js\";\nimport { builtinQueries } from \"./queries.js\";\n\nconst bindQuery =\n    <Args extends unknown[], Result>(query: (container: Container, ...args: Args) => Result, container: Container) =>\n        (...args: Args): Result =>\n            query(container, ...args);\n\nconst bindCustomQueries = <Q extends QueryMap>(customQueries: Q, container: Container): BoundCustomQueries<Q> => {\n    const entries = Object.entries(customQueries).map(([key, query]) => [key, bindQuery(query, container)] as const);\n\n    return Object.fromEntries(entries) as BoundCustomQueries<Q>;\n};\n\n/**\n * Binds the built-in queries, and any custom queries, to a specific container\n * so they search only within that scope.\n *\n * @param container The scope the returned queries operate on.\n * @param queries Optional custom queries to bind alongside the built-in ones.\n * @returns The queries bound to the container.\n */\nconst within = <Q extends QueryMap = Record<never, never>>(\n    container: Container,\n    queries?: Q,\n): BoundQueries & BoundCustomQueries<Q> => ({\n    ...bindCustomQueries(builtinQueries, container),\n    ...(queries ? bindCustomQueries(queries, container) : ({} as BoundCustomQueries<Q>)),\n});\n\nexport { within };\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gtkx/testing",
-  "version": "0.21.0",
-  "description": "Testing utilities for GTKX applications",
+  "version": "1.0.0-rc.2",
+  "description": "Testing Library-style queries, user events, and screenshots for GTK4 widget trees rendered by GTKX",
   "keywords": [
     "gtkx",
     "gtk",
@@ -19,7 +19,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/gtkx-org/gtkx.git",
+    "url": "git+https://github.com/gtkx-org/gtkx.git",
     "directory": "packages/testing"
   },
   "license": "MPL-2.0",
@@ -32,23 +32,34 @@
       "default": "./dist/index.js"
     }
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "./src/register-test-hooks.ts",
+    "./dist/register-test-hooks.js"
+  ],
   "files": [
     "dist",
     "src"
   ],
+  "engines": {
+    "node": ">=24"
+  },
   "dependencies": {
-    "@gtkx/ffi": "0.21.0",
-    "@gtkx/react": "0.21.0"
+    "@gtkx/react": "1.0.0-rc.2",
+    "@gtkx/runtime": "1.0.0-rc.2",
+    "@gtkx/utils": "1.0.0-rc.2"
+  },
+  "peerDependencies": {
+    "@types/react": "^19.2",
+    "react": "^19.2"
   },
   "devDependencies": {
-    "@types/react-reconciler": "^0.33.0",
-    "react-reconciler": "^0.33.0",
-    "@gtkx/vitest": "0.21.0"
+    "@types/react": "^19.2.17",
+    "@vitest/expect": "^4.1.10",
+    "vitest": "^4.1.10",
+    "@gtkx/vitest": "1.0.0-rc.2",
+    "@gtkx/config": "1.0.0-rc.2"
   },
   "scripts": {
-    "build": "tsc -b && cp ../../README.md .",
-    "test": "vitest run",
-    "typecheck": "tsc -b --emitDeclarationOnly"
+    "release": "tsx ../../scripts/release-package.ts"
   }
 }

package/src/act.ts

@@ -0,0 +1,77 @@
+import { act as reactAct } from "react";
+
+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;
+    }
+
+    throw new Error("unable to locate global object");
+};
+
+const getIsReactActEnvironment = (): boolean | undefined => getGlobalThis().IS_REACT_ACT_ENVIRONMENT;
+
+const setIsReactActEnvironment = (value: boolean | undefined): void => {
+    getGlobalThis().IS_REACT_ACT_ENVIRONMENT = value;
+};
+
+const isThenable = <T>(value: unknown): value is PromiseLike<T> =>
+    value !== null && typeof value === "object" && typeof (value as PromiseLike<T>).then === "function";
+
+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(isForced);
+
+    try {
+        const result: T | PromiseLike<T> = fn();
+
+        if (isThenable<T>(result)) {
+            return restoreAfter(result, previousActEnvironment);
+        }
+
+        setIsReactActEnvironment(previousActEnvironment);
+
+        return Promise.resolve(result);
+    } catch (error) {
+        setIsReactActEnvironment(previousActEnvironment);
+        throw error;
+    }
+};
+
+function withGlobalActEnvironment(actImplementation: ActImplementation): ActImplementation {
+    return <T>(callback: ActCallback<T>): PromiseLike<T> => {
+        const settled = runWithActEnvironment(true, () => actImplementation(() => callback()));
+
+        return Promise.resolve(settled);
+    };
+}
+
+const runInAct = async (callback: () => unknown): Promise<void> => {
+    await act(() => callback());
+};
+
+export { act, getIsReactActEnvironment, setIsReactActEnvironment, runWithActEnvironment, runInAct };

package/src/bound-queries.ts

@@ -0,0 +1,37 @@
+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";
+
+/**
+ * The set of built-in queries (getBy, findBy, queryBy, and their All variants)
+ * bound to a specific container.
+ */
+type BoundQueries = BoundCustomQueries<typeof builtinQueries>;
+/**
+ * The global screen object's shape: built-in queries scoped to the current
+ * toplevels, plus debug utilities.
+ */
+type Screen = BoundQueries & DebugUtilities;
+
+/**
+ * The result of a render call: queries scoped to the rendered tree, debug
+ * utilities, and controls for updating or tearing down the render.
+ *
+ * @typeParam Q Custom queries provided at render time, merged with the built-in ones.
+ */
+type RenderResult<Q extends QueryMap = Record<never, never>> = BoundQueries &
+    BoundCustomQueries<Q> &
+    DebugUtilities & {
+        /** The top-level widget the element was rendered into. */
+        container: Gtk.Widget;
+        /** The root the queries are scoped to (defaults to all toplevels). */
+        baseElement: Container;
+        /** Unmounts the rendered tree and disposes its resources. */
+        unmount: () => Promise<void>;
+        /** 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

@@ -0,0 +1,226 @@
+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 { waitFor } from "./wait-for.js";
+
+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;
+
+type BuiltQueries<Args extends unknown[]> = {
+    queryBy: (container: Container, ...args: Args) => Gtk.Widget | null;
+    getAllBy: QueryAllBy<Args>;
+    getBy: (container: Container, ...args: Args) => Gtk.Widget;
+    findAllBy: (container: Container, ...args: Args) => Promise<Gtk.Widget[]>;
+    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.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.at(-1);
+
+    if (last && typeof last === "object" && !(last instanceof RegExp)) {
+        return (last as MatcherOptions).suggest;
+    }
+
+    return undefined;
+};
+
+const maybeThrowSuggestion = (options: {
+    container: Container;
+    match: Gtk.Widget;
+    queryName: Method;
+    variant: Variant;
+    suggest: boolean | undefined;
+}): void => {
+    const { container, match, queryName, variant, suggest } = options;
+    const shouldSuggest = suggest ?? getConfig().throwSuggestions;
+
+    if (!shouldSuggest) {
+        return;
+    }
+
+    const suggestion = getSuggestedQuery(match, variant);
+
+    if (suggestion && suggestion.queryName !== queryName) {
+        throw suggestionError(suggestion.toString(), container);
+    }
+};
+
+const reRunForDiagnostics = <Args extends unknown[]>(
+    query: FindQuery<Args>,
+    container: Container,
+    args: Args,
+    fallback: Error,
+): Error => {
+    try {
+        query(container, ...args);
+    } catch (error) {
+        if (error instanceof Error) {
+            return error;
+        }
+    }
+
+    return fallback;
+};
+
+const findOptions = <Args extends unknown[]>(
+    query: FindQuery<Args>,
+    container: Container,
+    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,
+        timeout: userOptions.timeout,
+        interval: userOptions.interval,
+    };
+};
+
+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;
+        };
+
+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;
+        };
+
+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;
+        };
+
+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;
+        };
+
+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;
+        };
+
+const buildQueries = <Args extends unknown[]>(
+    queryName: Method,
+    queryAllBy: QueryAllBy<Args>,
+    getMultipleError: MultipleErrorBuilder<Args>,
+    getMissingError: MissingErrorBuilder<Args>,
+): BuiltQueries<Args> => {
+    const getAllBy = allOrThrow(queryAllBy, getMissingError);
+    const getBy = requireSingle(singleFrom(getAllBy, getMultipleError), getMissingError);
+
+    const queryByWithSuggestion = wrapSingleWithSuggestion(
+        singleFrom(queryAllBy, getMultipleError),
+        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;
+    };
+
+    const findAllBy = (container: Container, ...args: Args): Promise<Gtk.Widget[]> =>
+        waitFor(
+            () => runWithExpensiveErrorDiagnosticsDisabled(() => getAllByWithSuggestion(container, ...args)),
+            findOptions(getAllByWithSuggestion, container, args),
+        );
+
+    const findBy = (container: Container, ...args: Args): Promise<Gtk.Widget> =>
+        waitFor(
+            () => runWithExpensiveErrorDiagnosticsDisabled(() => getByWithSuggestion(container, ...args)),
+            findOptions(getByWithSuggestion, container, args),
+        );
+
+    return {
+        queryBy: queryByWithSuggestion,
+        getAllBy: getAllByWithSuggestion,
+        getBy: getByWithSuggestion,
+        findAllBy,
+        findBy,
+    };
+};
+
+export { buildQueries, type QueryAllBy, type BuiltQueries };

package/src/cleanup-registry.ts

@@ -0,0 +1,27 @@
+type CleanupFunction = () => void | Promise<void>;
+
+const cleanupQueue: Set<CleanupFunction> = new Set();
+
+const addToCleanupQueue = (fn: CleanupFunction): void => {
+    cleanupQueue.add(fn);
+};
+
+const runCleanup = async (): Promise<void> => {
+    const failures: unknown[] = [];
+
+    for (const fn of cleanupQueue) {
+        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

@@ -1,89 +1,62 @@
 import type { Container } from "./traversal.js";
 
 /**
- * Configuration options for the testing library.
+ * Global configuration for the testing harness, controlling query behavior,
+ * error formatting, and the timeouts used by async utilities and actionability
+ * checks.
  */
-export type Config = {
-    /**
-     * Whether to show role suggestions in error messages when elements are not found.
-     * @default true
-     */
-    showSuggestions: boolean;
+type Config = {
+    throwSuggestions: boolean;
 
-    /**
-     * Custom error factory for query failures.
-     * Allows customizing how errors are constructed.
-     */
-    getElementError: (message: string, container: Container) => Error;
+    /** Builds the error thrown when a query fails, given a message and optional container. */
+    getElementError: (message: string, container?: Container) => Error;
 
-    /**
-     * Default timeout in milliseconds for async utilities (waitFor, findBy* queries).
-     * @default 1000
-     */
+    /** Default timeout in milliseconds for async utilities such as waitFor. */
     asyncUtilTimeout: number;
-};
 
-const defaultGetElementError = (message: string, _container: Container): Error => {
-    return new Error(message);
+    /** Timeout in milliseconds for waiting on a widget to become actionable. */
+    actionabilityTimeout: number;
 };
 
+/**
+ * Function form of a configuration update: receives the current config and
+ * returns the fields to override.
+ */
+type ConfigFn = (existingConfig: Config) => Partial<Config>;
+
 const defaultConfig: Config = {
-    showSuggestions: true,
+    throwSuggestions: false,
     getElementError: defaultGetElementError,
     asyncUtilTimeout: 1000,
+    actionabilityTimeout: 500,
 };
 
-let currentConfig: Config = { ...defaultConfig };
+const currentConfig: Config = { ...defaultConfig };
+
+function defaultGetElementError(message: string): Error {
+    return new GtkxElementError(message);
+}
 
 /**
- * Returns the current testing library configuration.
- *
- * @returns The current configuration object
- *
- * @example
- * ```tsx
- * import { getConfig } from "@gtkx/testing";
- *
- * const config = getConfig();
- * console.log(config.showSuggestions);
- * ```
+ * Returns the current global testing configuration.
  */
-export const getConfig = (): Readonly<Config> => {
+const getConfig = (): Config => {
     return currentConfig;
 };
 
 /**
- * Configures the testing library behavior.
- *
- * Accepts either a partial configuration object or a function that receives
- * the current configuration and returns updates.
+ * Merges the given overrides into the global testing configuration.
  *
- * @param newConfig - Partial configuration or updater function
- *
- * @example
- * ```tsx
- * import { configure } from "@gtkx/testing";
- *
- * // Disable role suggestions
- * configure({ showSuggestions: false });
- *
- * // Use updater function
- * configure((current) => ({
- *   showSuggestions: !current.showSuggestions,
- * }));
- * ```
+ * @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> | ((current: Config) => Partial<Config>)): void => {
+const configure = (newConfig: Partial<Config> | ConfigFn): void => {
     const updates = typeof newConfig === "function" ? newConfig(currentConfig) : newConfig;
-    currentConfig = { ...currentConfig, ...updates };
+    Object.assign(currentConfig, updates);
 };
 
-/**
- * Resets configuration to defaults.
- * Primarily used for testing.
- *
- * @internal
- */
-export const resetConfig = (): void => {
-    currentConfig = { ...defaultConfig };
-};
+class GtkxElementError extends Error {
+    override name = "GtkxElementError";
+}
+
+export { getConfig, configure, type Config, type ConfigFn };