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

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

package/src/frame-sync.ts

@@ -1,34 +1,51 @@
 import type * as Gtk from "@gtkx/gi/gtk";
+import * as GLib from "@gtkx/gi/glib";
 
 const CLOCK_STALL_FALLBACK_MS = 500;
 
-export const scheduleAfterLayout = (widget: Gtk.Widget | null, callback: () => void): void => {
-    let done = false;
-    let removeTick: (() => void) | null = null;
-    let fallback: ReturnType<typeof setTimeout> | null = null;
-
-    const finish = (): void => {
-        if (done) return;
-        done = true;
-        if (fallback !== null) clearTimeout(fallback);
-        removeTick?.();
-        removeTick = null;
-        fallback = null;
+const once = (callback: () => void): (() => void) => {
+    let isCalled = false;
+
+    return () => {
+        if (isCalled) {
+            return;
+        }
+
+        isCalled = true;
         callback();
     };
+};
 
-    if (widget === null || widget.getFrameClock() === null || widget.getWidth() > 0) {
-        queueMicrotask(finish);
-        return;
-    }
+const runWhenSized = (widget: Gtk.Widget, finish: () => void): void => {
+    let tickId = 0;
+
+    const fallback = setTimeout(() => {
+        widget.removeTickCallback(tickId);
+        finish();
+    }, CLOCK_STALL_FALLBACK_MS);
 
-    fallback = setTimeout(finish, CLOCK_STALL_FALLBACK_MS);
+    tickId = widget.addTickCallback(() => {
+        if (widget.getWidth() === 0) {
+            return GLib.SOURCE_CONTINUE;
+        }
 
-    const tickId = widget.addTickCallback(() => {
-        if (widget.getWidth() === 0) return true;
+        clearTimeout(fallback);
         finish();
-        return false;
+
+        return GLib.SOURCE_REMOVE;
     });
+};
+
+const scheduleAfterLayout = (widget: Gtk.Widget | null, callback: () => void): void => {
+    const finish = once(callback);
+
+    if (widget?.getFrameClock() == null || widget.getWidth() > 0) {
+        queueMicrotask(finish);
 
-    removeTick = () => widget.removeTickCallback(tickId);
+        return;
+    }
+
+    runWhenSized(widget, finish);
 };
+
+export { scheduleAfterLayout };

package/src/index.ts

@@ -5,8 +5,9 @@ export type { BoundQueries, RenderResult, Screen } from "./bound-queries.js";
 export type { Config, ConfigFn } from "./config.js";
 export { configure, getConfig } from "./config.js";
 export { fireEvent } from "./fire-event.js";
-export type { TextExpectation } from "./matchers.js";
+export type { ClassExpectation, TextContentOptions, TextExpectation } from "./matchers.js";
 export { matchers, registerMatchers } from "./matchers.js";
+export { getDefaultNormalizer } from "./normalize.js";
 export type { PrettyWidgetOptions } from "./pretty-widget.js";
 export { logWidget, prettyWidget } from "./pretty-widget.js";
 export {
@@ -34,7 +35,6 @@ export {
     getByPlaceholderText,
     getByRole,
     getByText,
-    getDefaultNormalizer,
     queryAllByDisplayValue,
     queryAllByLabelText,
     queryAllByName,
@@ -48,8 +48,8 @@ export {
     queryByRole,
     queryByText,
 } from "./queries.js";
-export { cleanup, render } from "./render.js";
 export { renderHook } from "./render-hook.js";
+export { cleanup, render } from "./render.js";
 export { formatRole, getRoles, logRoles, prettyRoles } from "./role-helpers.js";
 export { screen } from "./screen.js";
 export { captureAndSaveScreenshot, logScreenshotPath, screenshot } from "./screenshot.js";
@@ -59,6 +59,7 @@ export type { Container } from "./traversal.js";
 export type {
     ByRoleOptions,
     ByRoleValue,
+    WidgetType,
     Matcher,
     MatcherFunction,
     MatcherOptions,
@@ -73,12 +74,20 @@ export type {
     WindowSelector,
     WrapperComponent,
 } from "./types.js";
+export type { ControllerConstructor } from "./user-event/controller.js";
+export {
+    getAllControllers,
+    getController,
+    queryAllControllers,
+    queryController,
+} from "./user-event/controller.js";
 export type {
     DragOffset,
     DragOptions,
     DropContent,
     DropOptions,
     PointerInput,
+    ScrollDelta,
     TabOptions,
     TypeOptions,
     UserEvent,
@@ -89,5 +98,6 @@ export {
     getWidgetErrorMessage,
     getWidgetInvalidState,
     getWidgetNodeText,
+    getWidgetTextContent,
 } from "./widget-accessible-properties.js";
 export { within } from "./within.js";