@gtkx/testing 1.0.0-rc.3 → 1.0.0

package/src/build-queries.ts

@@ -3,63 +3,61 @@ 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 { getSuggestedQuery, type Variant } from "./suggestions.js";
 import { waitFor } from "./wait-for.js";
 
+/**
+ * The `queryAllBy` function a query family is built from, taking the scope to search followed by the
+ * family's own matcher arguments. Its name determines the family name, so `queryAllByTestId` builds
+ * a `TestId` family.
+ */
 type QueryAllBy<Args extends unknown[]> = (container: Container, ...args: Args) => Gtk.Widget[];
 
+/** Builds the error thrown when a single-match query finds more than one widget. */
 type MultipleErrorBuilder<Args extends unknown[]> = (
     container: Container,
     matches: Gtk.Widget[],
     ...args: Args
 ) => Error;
 
+/** Builds the error thrown when a query that requires a match finds none. */
 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>;
-};
+/** The variants derived from one `queryAllBy` function, in the order DOM Testing Library returns them. */
+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 getTrailingOptions = (args: unknown[]): MatcherOptions | undefined => {
     const last = args.at(-1);
 
     if (last && typeof last === "object" && !(last instanceof RegExp)) {
-        return (last as MatcherOptions).suggest;
+        return last;
     }
 
     return undefined;
 };
 
+const extractShouldSuggest = (args: unknown[]): boolean | undefined => getTrailingOptions(args)?.suggest;
+const getQueryFamily = (queryAllBy: { name: string }): string => queryAllBy.name.replace(/^queryAllBy/, "");
+
 const maybeThrowSuggestion = (options: {
     container: Container;
     match: Gtk.Widget;
-    queryName: Method;
+    queryName: string;
     variant: Variant;
-    suggest: boolean | undefined;
+    shouldSuggest: boolean | undefined;
 }): void => {
-    const { container, match, queryName, variant, suggest } = options;
-    const shouldSuggest = suggest ?? getConfig().throwSuggestions;
+    const { container, match, queryName, variant, shouldSuggest } = options;
 
-    if (!shouldSuggest) {
+    if (!(shouldSuggest ?? getConfig().throwSuggestions)) {
         return;
     }
 
@@ -92,16 +90,13 @@ const findOptions = <Args extends unknown[]>(
     container: Container,
     args: Args,
 ): WaitForOptions => {
-    const userOptions = extractWaitForOptions(args);
-
-    const onTimeout =
-        userOptions.onTimeout ?? ((fallback: Error) => reRunForDiagnostics(query, container, args, fallback));
+    const { timeout, interval, onTimeout } = getTrailingOptions(args) ?? {};
 
     return {
         stackTraceError: new Error("STACK_TRACE_MESSAGE"),
-        onTimeout,
-        timeout: userOptions.timeout,
-        interval: userOptions.interval,
+        onTimeout: onTimeout ?? ((fallback: Error) => reRunForDiagnostics(query, container, args, fallback)),
+        timeout,
+        interval,
     };
 };
 
@@ -136,19 +131,25 @@ const allOrThrow =
         };
 
 const wrapSingleWithSuggestion =
-    <Args extends unknown[]>(query: SingleQuery<Args>, queryName: Method, variant: Variant): SingleQuery<Args> =>
+    <Args extends unknown[]>(query: SingleQuery<Args>, queryName: string, variant: Variant): SingleQuery<Args> =>
         (container, ...args) => {
             const match = query(container, ...args);
 
             if (match) {
-                maybeThrowSuggestion({ container, match, queryName, variant, suggest: extractSuggestOption(args) });
+                maybeThrowSuggestion({
+                    container,
+                    match,
+                    queryName,
+                    variant,
+                    shouldSuggest: extractShouldSuggest(args),
+                });
             }
 
             return match;
         };
 
 const wrapAllWithSuggestion =
-    <Args extends unknown[]>(query: QueryAllBy<Args>, queryName: Method, variant: Variant): QueryAllBy<Args> =>
+    <Args extends unknown[]>(query: QueryAllBy<Args>, queryName: string, variant: Variant): QueryAllBy<Args> =>
         (container, ...args) => {
             const matches = query(container, ...args);
             const [first] = matches;
@@ -159,7 +160,7 @@ const wrapAllWithSuggestion =
                     match: first,
                     queryName,
                     variant,
-                    suggest: extractSuggestOption(args),
+                    shouldSuggest: extractShouldSuggest(args),
                 });
             }
 
@@ -178,12 +179,22 @@ const requireSingle =
             return match;
         };
 
+/**
+ * Derives the `queryBy`, `getAllBy`, `getBy`, `findAllBy`, and `findBy` variants of a query family
+ * from the family's `queryAllBy` function, mirroring DOM Testing Library's `buildQueries`. The family
+ * name used when suggesting a better query comes from `queryAllBy.name`.
+ *
+ * @param queryAllBy Finds every widget the family matches.
+ * @param getMultipleError Builds the error thrown when a single-match variant finds more than one widget.
+ * @param getMissingError Builds the error thrown when a required match is missing.
+ * @returns The five variants, in the order `[queryBy, getAllBy, getBy, findAllBy, findBy]`.
+ */
 const buildQueries = <Args extends unknown[]>(
-    queryName: Method,
     queryAllBy: QueryAllBy<Args>,
     getMultipleError: MultipleErrorBuilder<Args>,
     getMissingError: MissingErrorBuilder<Args>,
 ): BuiltQueries<Args> => {
+    const queryName = getQueryFamily(queryAllBy);
     const getAllBy = allOrThrow(queryAllBy, getMissingError);
     const getBy = requireSingle(singleFrom(getAllBy, getMultipleError), getMissingError);
 
@@ -197,7 +208,14 @@ const buildQueries = <Args extends unknown[]>(
 
     const getByWithSuggestion: (container: Container, ...args: Args) => Gtk.Widget = (container, ...args) => {
         const match = getBy(container, ...args);
-        maybeThrowSuggestion({ container, match, queryName, variant: "get", suggest: extractSuggestOption(args) });
+
+        maybeThrowSuggestion({
+            container,
+            match,
+            queryName,
+            variant: "get",
+            shouldSuggest: extractShouldSuggest(args),
+        });
 
         return match;
     };
@@ -214,13 +232,13 @@ const buildQueries = <Args extends unknown[]>(
             findOptions(getByWithSuggestion, container, args),
         );
 
-    return {
-        queryBy: queryByWithSuggestion,
-        getAllBy: getAllByWithSuggestion,
-        getBy: getByWithSuggestion,
-        findAllBy,
-        findBy,
-    };
+    return [queryByWithSuggestion, getAllByWithSuggestion, getByWithSuggestion, findAllBy, findBy];
 };
 
-export { buildQueries, type QueryAllBy, type BuiltQueries };
+export {
+    buildQueries,
+    type BuiltQueries,
+    type MissingErrorBuilder,
+    type MultipleErrorBuilder,
+    type QueryAllBy,
+};

package/src/cleanup-registry.ts

@@ -24,4 +24,4 @@ const runCleanup = async (): Promise<void> => {
     }
 };
 
-export { addToCleanupQueue, runCleanup, type CleanupFunction };
+export { addToCleanupQueue, runCleanup };

package/src/config.ts

@@ -6,6 +6,7 @@ import type { Container } from "./traversal.js";
  * checks.
  */
 type Config = {
+    /** Whether a successful query throws instead, naming a better query, when one is available. */
     throwSuggestions: boolean;
 
     /** Builds the error thrown when a query fails, given a message and optional container. */
@@ -34,7 +35,7 @@ const defaultConfig: Config = {
 const currentConfig: Config = { ...defaultConfig };
 
 function defaultGetElementError(message: string): Error {
-    return new GtkxElementError(message);
+    return new ElementError(message);
 }
 
 /**
@@ -55,8 +56,8 @@ const configure = (newConfig: Partial<Config> | ConfigFn): void => {
     Object.assign(currentConfig, updates);
 };
 
-class GtkxElementError extends Error {
-    override name = "GtkxElementError";
+class ElementError extends Error {
+    override name = "ElementError";
 }
 
 export { getConfig, configure, type Config, type ConfigFn };

package/src/errors.ts

@@ -125,11 +125,22 @@ const buildElementError = (container: Container, headLines: string[]): Error =>
 
     const lines = expensiveErrorDiagnostics.isDisabled
         ? headLines
-        : [...headLines, "", prettyWidget(container, { highlight: false })];
+        : [...headLines, "", prettyWidget(container, { shouldHighlight: false })];
 
     return config.getElementError(lines.join("\n"), container);
 };
 
+/**
+ * Builds the error a failing query throws, appending the container's widget tree to the message the
+ * way the built-in queries do.
+ *
+ * @param message The failure message.
+ * @param container The scope whose widget tree is appended; omitted, only the message is used.
+ * @returns The error produced by the configured `getElementError`.
+ */
+const getElementError = (message: string, container?: Container): Error =>
+    container === undefined ? getConfig().getElementError(message) : buildElementError(container, [message]);
+
 const notFoundError = (container: Container, descriptor: QueryDescriptor): Error => {
     const description = formatQueryDescription(descriptor);
     const headLines = [`Unable to find an element with ${description}`];
@@ -160,7 +171,7 @@ const multipleFoundError = (container: Container, descriptor: QueryDescriptor, m
     ];
 
     if (!expensiveErrorDiagnostics.isDisabled) {
-        const renderedMatches = matches.map((widget) => prettyWidget(widget, { highlight: false }));
+        const renderedMatches = matches.map((widget) => prettyWidget(widget, { shouldHighlight: false }));
         headLines.push("", "Here are the matching elements:", "", ...renderedMatches);
     }
 
@@ -183,9 +194,9 @@ const timeoutError = (timeout: number, lastError: Error | null): Error => {
 
 export {
     runWithExpensiveErrorDiagnosticsDisabled,
+    getElementError,
     notFoundError,
     multipleFoundError,
     suggestionError,
     timeoutError,
-    type QueryDescriptor,
 };

package/src/fire-event.ts

@@ -1,18 +1,71 @@
-import type * as GObject from "@gtkx/gi/gobject";
+import * as GObject from "@gtkx/gi/gobject";
 import { runInAct } from "./act.js";
 
 /**
- * Emits a GObject signal on a widget or object inside React's act environment,
- * so any resulting state updates are flushed before the promise resolves.
+ * A signal emission built but not yet delivered. GObject has no event object to construct, so this
+ * records the target, signal, and arguments {@link fireEvent} will emit.
+ */
+type WidgetEvent = {
+    /** The GObject instance the signal is emitted on. */
+    target: GObject.Object;
+    /** Name of the signal to emit. */
+    signalName: string;
+    /** Arguments passed to the signal handlers. */
+    args: unknown[];
+};
+
+/**
+ * Records a signal emission without delivering it, so it can be inspected or held and passed to
+ * {@link fireEvent} later.
  *
- * @param element The GObject instance to emit the signal on.
+ * @param target The GObject instance the signal would be emitted on.
  * @param signalName Name of the signal to emit.
- * @param args Arguments passed to the signal handlers.
+ * @param args Arguments to pass to the signal handlers.
+ * @returns The recorded emission.
  */
-const fireEvent = async (element: GObject.Object, signalName: string, ...args: unknown[]): Promise<void> => {
+const createEvent = (target: GObject.Object, signalName: string, ...args: unknown[]): WidgetEvent => ({
+    target,
+    signalName,
+    args,
+});
+
+const dispatchEvent = async (event: WidgetEvent): Promise<void> => {
     await runInAct(() => {
-        element.emit(signalName, ...args);
+        event.target.emit(event.signalName, ...event.args);
     });
 };
 
-export { fireEvent };
+/**
+ * Emits a recorded signal emission inside React's act environment, so any resulting state updates are
+ * flushed before the promise resolves.
+ *
+ * @param event An emission built by {@link createEvent}.
+ */
+function fireEvent(event: WidgetEvent): Promise<void>;
+/**
+ * Emits a GObject signal on a widget or object inside React's act environment, so any resulting state
+ * updates are flushed before the promise resolves.
+ *
+ * @param target The GObject instance to emit the signal on.
+ * @param signalName Name of the signal to emit.
+ * @param args Arguments passed to the signal handlers.
+ */
+function fireEvent(target: GObject.Object, signalName: string, ...args: unknown[]): Promise<void>;
+
+function fireEvent(
+    eventOrTarget: WidgetEvent | GObject.Object,
+    signalName?: string,
+    ...args: unknown[]
+): Promise<void> {
+    if (!(eventOrTarget instanceof GObject.Object)) {
+        return dispatchEvent(eventOrTarget);
+    }
+
+    if (signalName === undefined) {
+        throw new Error("Unable to fire an event: pass a signal name, or an event built by createEvent.");
+    }
+
+    return dispatchEvent(createEvent(eventOrTarget, signalName, ...args));
+}
+
+export { createEvent, fireEvent, type WidgetEvent };

package/src/frame-sync.ts

@@ -16,7 +16,10 @@ const once = (callback: () => void): (() => void) => {
     };
 };
 
-const runWhenSized = (widget: Gtk.Widget, finish: () => void): void => {
+const hasFrameClock = (widget: Gtk.Widget | null): widget is Gtk.Widget => widget?.getFrameClock() != null;
+const isSized = (widget: Gtk.Widget): boolean => widget.getWidth() > 0;
+
+const runUntilReady = (widget: Gtk.Widget, isReady: () => boolean, finish: () => void): void => {
     let tickId = 0;
 
     const fallback = setTimeout(() => {
@@ -25,7 +28,7 @@ const runWhenSized = (widget: Gtk.Widget, finish: () => void): void => {
     }, CLOCK_STALL_FALLBACK_MS);
 
     tickId = widget.addTickCallback(() => {
-        if (widget.getWidth() === 0) {
+        if (!isReady()) {
             return GLib.SOURCE_CONTINUE;
         }
 
@@ -36,16 +39,29 @@ const runWhenSized = (widget: Gtk.Widget, finish: () => void): void => {
     });
 };
 
+const scheduleNextFrame = (widget: Gtk.Widget): Promise<void> =>
+    new Promise((resolve) => {
+        const finish = once(resolve);
+
+        if (!hasFrameClock(widget)) {
+            queueMicrotask(finish);
+
+            return;
+        }
+
+        runUntilReady(widget, () => true, finish);
+    });
+
 const scheduleAfterLayout = (widget: Gtk.Widget | null, callback: () => void): void => {
     const finish = once(callback);
 
-    if (widget?.getFrameClock() == null || widget.getWidth() > 0) {
+    if (!hasFrameClock(widget) || isSized(widget)) {
         queueMicrotask(finish);
 
         return;
     }
 
-    runWhenSized(widget, finish);
+    runUntilReady(widget, () => isSized(widget), finish);
 };
 
-export { scheduleAfterLayout };
+export { scheduleAfterLayout, scheduleNextFrame };

package/src/harness-window.ts

@@ -0,0 +1,9 @@
+import * as Gtk from "@gtkx/gi/gtk";
+
+const HARNESS_WINDOW_WIDTH = 800;
+const HARNESS_WINDOW_HEIGHT = 600;
+
+const createHarnessWindow = (): Gtk.Window =>
+    new Gtk.Window({ defaultWidth: HARNESS_WINDOW_WIDTH, defaultHeight: HARNESS_WINDOW_HEIGHT });
+
+export { createHarnessWindow };

package/src/index.ts

@@ -2,12 +2,22 @@ import "./register-test-hooks.js";
 
 export { act } from "./act.js";
 export type { BoundQueries, RenderResult, Screen } from "./bound-queries.js";
+export type {
+    BuiltQueries,
+    MissingErrorBuilder,
+    MultipleErrorBuilder,
+    QueryAllBy,
+} from "./build-queries.js";
+export { buildQueries } from "./build-queries.js";
 export type { Config, ConfigFn } from "./config.js";
 export { configure, getConfig } from "./config.js";
-export { fireEvent } from "./fire-event.js";
+export { getElementError } from "./errors.js";
+export type { WidgetEvent } from "./fire-event.js";
+export { createEvent, fireEvent } from "./fire-event.js";
 export type { ClassExpectation, TextContentOptions, TextExpectation } from "./matchers.js";
 export { matchers, registerMatchers } from "./matchers.js";
 export { getDefaultNormalizer } from "./normalize.js";
+export { prettyFormat } from "./pretty-format.js";
 export type { PrettyWidgetOptions } from "./pretty-widget.js";
 export { logWidget, prettyWidget } from "./pretty-widget.js";
 export {
@@ -48,11 +58,13 @@ export {
     queryByRole,
     queryByText,
 } from "./queries.js";
+export type { QueryHelpers } from "./query-helpers.js";
+export { queryAllByObjectProperty, queryByObjectProperty, queryHelpers } from "./query-helpers.js";
 export { renderHook } from "./render-hook.js";
 export { cleanup, render } from "./render.js";
-export { formatRole, getRoles, logRoles, prettyRoles } from "./role-helpers.js";
+export { computeHeadingLevel, formatRole, getRoles, logRoles, prettyRoles } from "./role-helpers.js";
 export { screen } from "./screen.js";
-export { captureAndSaveScreenshot, logScreenshotPath, screenshot } from "./screenshot.js";
+export { screenshot } from "./screenshot.js";
 export type { Method, Suggestion, Variant } from "./suggestions.js";
 export { getSuggestedQuery } from "./suggestions.js";
 export type { Container } from "./traversal.js";
@@ -71,7 +83,6 @@ export type {
     ScreenshotOptions,
     ScreenshotResult,
     WaitForOptions,
-    WindowSelector,
     WrapperComponent,
 } from "./types.js";
 export type { ControllerConstructor } from "./user-event/controller.js";
@@ -91,13 +102,9 @@ export type {
     TabOptions,
     TypeOptions,
     UserEvent,
+    UserEventOptions,
 } from "./user-event/index.js";
 export { userEvent } from "./user-event/index.js";
 export { waitFor, waitForElementToBeRemoved } from "./wait-for.js";
-export {
-    getWidgetErrorMessage,
-    getWidgetInvalidState,
-    getWidgetNodeText,
-    getWidgetTextContent,
-} from "./widget-accessible-properties.js";
-export { within } from "./within.js";
+export { getWidgetText, isInaccessible } from "./widget-accessible-properties.js";
+export { getQueriesForElement, within } from "./within.js";

package/src/internal.ts

@@ -0,0 +1,11 @@
+export {
+    readAccessibleBooleanProperty,
+    readAccessibleFlag,
+    readAccessibleInt,
+    readAccessibleNumber,
+    readAccessibleRelation,
+    readAccessibleState,
+    readAccessibleString,
+} from "./accessible-native.js";
+export { cleanup, render } from "./production.js";
+export { renderChildren, type ChildrenBuilder } from "./render-children.js";