@gtkx/testing 0.18.0 → 0.18.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/testing",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "description": "Testing utilities for GTKX applications",
   "keywords": [
     "gtkx",
@@ -32,17 +32,19 @@
       "default": "./dist/index.js"
     }
   },
+  "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "dependencies": {
-    "@gtkx/ffi": "0.18.0",
-    "@gtkx/react": "0.18.0"
+    "@gtkx/ffi": "0.18.2",
+    "@gtkx/react": "0.18.2"
   },
   "devDependencies": {
     "@types/react-reconciler": "^0.33.0",
     "react-reconciler": "^0.33.0",
-    "@gtkx/vitest": "0.18.0"
+    "@gtkx/vitest": "0.18.2"
   },
   "scripts": {
     "build": "tsc -b && cp ../../README.md .",

package/src/bind-queries.ts

@@ -0,0 +1,52 @@
+import type * as Gtk from "@gtkx/ffi/gtk";
+import * as queries from "./queries.js";
+import type { Container } from "./traversal.js";
+import type { BoundQueries, ByRoleOptions, TextMatch, TextMatchOptions } from "./types.js";
+
+type ContainerOrGetter = Container | (() => Container);
+
+const resolveContainer = (containerOrGetter: ContainerOrGetter): Container =>
+    typeof containerOrGetter === "function" ? containerOrGetter() : containerOrGetter;
+
+/**
+ * Binds all query functions to a container.
+ *
+ * @param containerOrGetter - The container to bind queries to, or a function that returns it
+ * @returns Object with all query methods bound to the container
+ *
+ * @internal
+ */
+export const bindQueries = (containerOrGetter: ContainerOrGetter): BoundQueries => ({
+    queryByRole: (role: Gtk.AccessibleRole, options?: ByRoleOptions) =>
+        queries.queryByRole(resolveContainer(containerOrGetter), role, options),
+    queryByLabelText: (text: TextMatch, options?: TextMatchOptions) =>
+        queries.queryByLabelText(resolveContainer(containerOrGetter), text, options),
+    queryByText: (text: TextMatch, options?: TextMatchOptions) =>
+        queries.queryByText(resolveContainer(containerOrGetter), text, options),
+    queryByTestId: (testId: TextMatch, options?: TextMatchOptions) =>
+        queries.queryByTestId(resolveContainer(containerOrGetter), testId, options),
+    queryAllByRole: (role: Gtk.AccessibleRole, options?: ByRoleOptions) =>
+        queries.queryAllByRole(resolveContainer(containerOrGetter), role, options),
+    queryAllByLabelText: (text: TextMatch, options?: TextMatchOptions) =>
+        queries.queryAllByLabelText(resolveContainer(containerOrGetter), text, options),
+    queryAllByText: (text: TextMatch, options?: TextMatchOptions) =>
+        queries.queryAllByText(resolveContainer(containerOrGetter), text, options),
+    queryAllByTestId: (testId: TextMatch, options?: TextMatchOptions) =>
+        queries.queryAllByTestId(resolveContainer(containerOrGetter), testId, options),
+    findByRole: (role: Gtk.AccessibleRole, options?: ByRoleOptions) =>
+        queries.findByRole(resolveContainer(containerOrGetter), role, options),
+    findByLabelText: (text: TextMatch, options?: TextMatchOptions) =>
+        queries.findByLabelText(resolveContainer(containerOrGetter), text, options),
+    findByText: (text: TextMatch, options?: TextMatchOptions) =>
+        queries.findByText(resolveContainer(containerOrGetter), text, options),
+    findByTestId: (testId: TextMatch, options?: TextMatchOptions) =>
+        queries.findByTestId(resolveContainer(containerOrGetter), testId, options),
+    findAllByRole: (role: Gtk.AccessibleRole, options?: ByRoleOptions) =>
+        queries.findAllByRole(resolveContainer(containerOrGetter), role, options),
+    findAllByLabelText: (text: TextMatch, options?: TextMatchOptions) =>
+        queries.findAllByLabelText(resolveContainer(containerOrGetter), text, options),
+    findAllByText: (text: TextMatch, options?: TextMatchOptions) =>
+        queries.findAllByText(resolveContainer(containerOrGetter), text, options),
+    findAllByTestId: (testId: TextMatch, options?: TextMatchOptions) =>
+        queries.findAllByTestId(resolveContainer(containerOrGetter), testId, options),
+});

package/src/config.ts

@@ -0,0 +1,89 @@
+import type { Container } from "./traversal.js";
+
+/**
+ * Configuration options for the testing library.
+ */
+export type Config = {
+    /**
+     * Whether to show role suggestions in error messages when elements are not found.
+     * @default true
+     */
+    showSuggestions: boolean;
+
+    /**
+     * Custom error factory for query failures.
+     * Allows customizing how errors are constructed.
+     */
+    getElementError: (message: string, container: Container) => Error;
+
+    /**
+     * Default timeout in milliseconds for async utilities (waitFor, findBy* queries).
+     * @default 1000
+     */
+    asyncUtilTimeout: number;
+};
+
+const defaultGetElementError = (message: string, _container: Container): Error => {
+    return new Error(message);
+};
+
+const defaultConfig: Config = {
+    showSuggestions: true,
+    getElementError: defaultGetElementError,
+    asyncUtilTimeout: 1000,
+};
+
+let currentConfig: Config = { ...defaultConfig };
+
+/**
+ * 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);
+ * ```
+ */
+export const getConfig = (): Readonly<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.
+ *
+ * @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,
+ * }));
+ * ```
+ */
+export const configure = (newConfig: Partial<Config> | ((current: Config) => Partial<Config>)): void => {
+    const updates = typeof newConfig === "function" ? newConfig(currentConfig) : newConfig;
+    currentConfig = { ...currentConfig, ...updates };
+};
+
+/**
+ * Resets configuration to defaults.
+ * Primarily used for testing.
+ *
+ * @internal
+ */
+export const resetConfig = (): void => {
+    currentConfig = { ...defaultConfig };
+};

package/src/error-builder.ts

@@ -0,0 +1,102 @@
+import type * as Gtk from "@gtkx/ffi/gtk";
+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, TextMatch } from "./types.js";
+
+type QueryType = "role" | "text" | "labelText" | "testId";
+
+const formatTextMatcher = (text: TextMatch): string => {
+    if (typeof text === "function") {
+        return "custom function";
+    }
+    if (text instanceof RegExp) {
+        return text.toString();
+    }
+    return `'${text}'`;
+};
+
+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}`);
+    return parts.join(" and ");
+};
+
+const formatQueryDescription = (
+    queryType: QueryType,
+    args: { role?: Gtk.AccessibleRole; text?: TextMatch; testId?: TextMatch; options?: ByRoleOptions },
+): string => {
+    switch (queryType) {
+        case "role":
+            return formatByRoleDescription(args.role as Gtk.AccessibleRole, args.options);
+        case "text":
+            return `text ${formatTextMatcher(args.text as TextMatch)}`;
+        case "labelText":
+            return `label text ${formatTextMatcher(args.text as TextMatch)}`;
+        case "testId":
+            return `test id ${formatTextMatcher(args.testId as TextMatch)}`;
+    }
+};
+
+/**
+ * Builds an error for when no elements match a query.
+ */
+export const buildNotFoundError = (
+    container: Container,
+    queryType: QueryType,
+    args: { role?: Gtk.AccessibleRole; text?: TextMatch; testId?: TextMatch; options?: ByRoleOptions },
+): Error => {
+    const config = getConfig();
+    const description = formatQueryDescription(queryType, args);
+    const lines: string[] = [`Unable to find an element with ${description}`];
+
+    if (config.showSuggestions && queryType === "role") {
+        lines.push("");
+        lines.push("Here are the accessible roles:");
+        lines.push("");
+        lines.push(prettyRoles(container));
+    }
+
+    lines.push("");
+    lines.push(prettyWidget(container, { highlight: false }));
+
+    const message = lines.join("\n");
+    return config.getElementError(message, container);
+};
+
+/**
+ * Builds an error for when multiple elements match a query but only one was expected.
+ */
+export const buildMultipleFoundError = (
+    container: Container,
+    queryType: QueryType,
+    args: { role?: Gtk.AccessibleRole; text?: TextMatch; testId?: TextMatch; options?: ByRoleOptions },
+    count: number,
+): Error => {
+    const config = getConfig();
+    const description = formatQueryDescription(queryType, args);
+    const lines: string[] = [`Found ${count} elements with ${description}, but expected only one`];
+
+    lines.push("");
+    lines.push(prettyWidget(container, { highlight: false }));
+
+    const message = lines.join("\n");
+    return config.getElementError(message, container);
+};
+
+/**
+ * Builds a timeout error with the last query error message.
+ */
+export const buildTimeoutError = (timeout: number, lastError: Error | null): Error => {
+    const baseMessage = `Timed out after ${timeout}ms`;
+    if (lastError) {
+        return new Error(`${baseMessage}.\n\n${lastError.message}`);
+    }
+    return new Error(baseMessage);
+};

package/src/fire-event.ts

@@ -0,0 +1,43 @@
+import { type Object as GObject, signalEmitv, signalLookup, typeFromName, Value } from "@gtkx/ffi/gobject";
+import type * as Gtk from "@gtkx/ffi/gtk";
+import { tick } from "./timing.js";
+
+/**
+ * Emits a GTK signal on a widget or event controller.
+ *
+ * Low-level utility for triggering signals directly. Prefer {@link userEvent}
+ * for common interactions like clicking and typing.
+ *
+ * @param element - The widget or event controller to emit the signal on
+ * @param signalName - GTK signal name (e.g., "clicked", "activate", "drag-begin")
+ * @param args - Additional signal arguments as GValues
+ *
+ * @example
+ * ```tsx
+ * import { fireEvent } from "@gtkx/testing";
+ * import { Value } from "@gtkx/ffi/gobject";
+ *
+ * // Emit signal on widget
+ * await fireEvent(widget, "clicked");
+ *
+ * // Emit signal on gesture controller
+ * const gesture = widget.observeControllers().getObject(0) as Gtk.GestureDrag;
+ * await fireEvent(gesture, "drag-begin", Value.newFromDouble(100), Value.newFromDouble(100));
+ * ```
+ *
+ * @see {@link userEvent} for high-level user interactions
+ */
+export const fireEvent = async (
+    element: Gtk.Widget | Gtk.EventController,
+    signalName: string,
+    ...args: Value[]
+): Promise<void> => {
+    const gtype = typeFromName((element.constructor as typeof GObject).glibTypeName);
+    const signalId = signalLookup(signalName, gtype);
+
+    const instanceValue = Value.newFromObject(element as GObject);
+
+    signalEmitv([instanceValue, ...args], signalId, 0);
+
+    await tick();
+};

package/src/index.ts

@@ -0,0 +1,51 @@
+export type { Config } from "./config.js";
+export { configure, getConfig } from "./config.js";
+export { fireEvent } from "./fire-event.js";
+export type { PrettyWidgetOptions } from "./pretty-widget.js";
+export { prettyWidget } from "./pretty-widget.js";
+export {
+    findAllByLabelText,
+    findAllByRole,
+    findAllByTestId,
+    findAllByText,
+    findByLabelText,
+    findByRole,
+    findByTestId,
+    findByText,
+    queryAllByLabelText,
+    queryAllByRole,
+    queryAllByTestId,
+    queryAllByText,
+    queryByLabelText,
+    queryByRole,
+    queryByTestId,
+    queryByText,
+} from "./queries.js";
+export { cleanup, render } from "./render.js";
+export { renderHook } from "./render-hook.js";
+export type { RoleInfo } from "./role-helpers.js";
+export { getRoles, logRoles, prettyRoles } from "./role-helpers.js";
+export { screen } from "./screen.js";
+export type { ScreenshotOptions } from "./screenshot.js";
+export { screenshot } from "./screenshot.js";
+export { tick } from "./timing.js";
+export type { Container } from "./traversal.js";
+export type {
+    BoundQueries,
+    ByRoleOptions,
+    NormalizerOptions,
+    RenderHookOptions,
+    RenderHookResult,
+    RenderOptions,
+    RenderResult,
+    ScreenshotResult,
+    TextMatch,
+    TextMatchFunction,
+    TextMatchOptions,
+    WaitForOptions,
+    WrapperComponent,
+} from "./types.js";
+export type { PointerInput, TabOptions } from "./user-event.js";
+export { userEvent } from "./user-event.js";
+export { waitFor, waitForElementToBeRemoved } from "./wait-for.js";
+export { within } from "./within.js";

package/src/pretty-widget.ts

@@ -0,0 +1,205 @@
+import * as Gtk from "@gtkx/ffi/gtk";
+import { formatRole } from "./role-helpers.js";
+import { type Container, isApplication } from "./traversal.js";
+import { getWidgetText } from "./widget-text.js";
+
+const DEFAULT_MAX_LENGTH = 7000;
+const INDENT = "  ";
+
+const debugIdMap = new WeakMap<Gtk.Widget, string>();
+let nextDebugId = 0;
+
+const getWidgetDebugId = (widget: Gtk.Widget): string => {
+    let id = debugIdMap.get(widget);
+    if (!id) {
+        id = String(nextDebugId++);
+        debugIdMap.set(widget, id);
+    }
+    return id;
+};
+
+/**
+ * Options for {@link prettyWidget}.
+ */
+export type PrettyWidgetOptions = {
+    /** Maximum output length before truncation (default: 7000) */
+    maxLength?: number;
+    /** Enable ANSI color highlighting (default: auto-detect) */
+    highlight?: boolean;
+    /** Include widget IDs for MCP/agentic interactions (default: false) */
+    includeIds?: boolean;
+};
+
+type HighlightColors = {
+    tag: (s: string) => string;
+    attr: (s: string) => string;
+    value: (s: string) => string;
+    text: (s: string) => string;
+    reset: string;
+};
+
+const shouldHighlight = (): boolean => {
+    if (typeof process === "undefined") return false;
+    if (process.env.COLORS === "false" || process.env.NO_COLOR) return false;
+    if (process.env.COLORS === "true" || process.env.FORCE_COLOR) return true;
+    return process.stdout?.isTTY ?? false;
+};
+
+const ansi = {
+    cyan: "\x1b[36m",
+    yellow: "\x1b[33m",
+    green: "\x1b[32m",
+    reset: "\x1b[0m",
+};
+
+const createColors = (enabled: boolean): HighlightColors => {
+    if (!enabled) {
+        const identity = (s: string): string => s;
+        return { tag: identity, attr: identity, value: identity, text: identity, reset: "" };
+    }
+    return {
+        tag: (s) => `${ansi.cyan}${s}${ansi.reset}`,
+        attr: (s) => `${ansi.yellow}${s}${ansi.reset}`,
+        value: (s) => `${ansi.green}${s}${ansi.reset}`,
+        text: (s) => s,
+        reset: ansi.reset,
+    };
+};
+
+const formatTagName = (widget: Gtk.Widget): string => {
+    return widget.constructor.name;
+};
+
+const escapeAttrValue = (value: string): string => {
+    return value.replace(/"/g, "&quot;");
+};
+
+const formatAttributes = (widget: Gtk.Widget, colors: HighlightColors, includeIds: boolean): string => {
+    const attrs: [string, string][] = [];
+
+    if (includeIds) {
+        attrs.push(["id", getWidgetDebugId(widget)]);
+    }
+
+    const name = widget.getName();
+    if (name) {
+        attrs.push(["data-testid", name]);
+    }
+
+    const role = widget.getAccessibleRole();
+    if (role !== undefined) {
+        attrs.push(["role", formatRole(role)]);
+    }
+
+    if (!widget.getSensitive()) {
+        attrs.push(["aria-disabled", "true"]);
+    }
+
+    if (!widget.getVisible()) {
+        attrs.push(["aria-hidden", "true"]);
+    }
+
+    if (attrs.length === 0) return "";
+
+    return attrs
+        .sort(([a], [b]) => {
+            if (a === "id") return -1;
+            if (b === "id") return 1;
+            return a.localeCompare(b);
+        })
+        .map(([key, value]) => ` ${colors.attr(key)}=${colors.value(`"${escapeAttrValue(value)}"`)}`)
+        .join("");
+};
+
+const hasChildren = (widget: Gtk.Widget): boolean => {
+    return widget.getFirstChild() !== null;
+};
+
+const printWidget = (widget: Gtk.Widget, colors: HighlightColors, depth: number, includeIds: boolean): string => {
+    const indent = INDENT.repeat(depth);
+    const tagName = formatTagName(widget);
+    const attributes = formatAttributes(widget, colors, includeIds);
+    const text = getWidgetText(widget);
+    const children: string[] = [];
+
+    let child = widget.getFirstChild();
+    while (child) {
+        children.push(printWidget(child, colors, depth + 1, includeIds));
+        child = child.getNextSibling();
+    }
+
+    const openTag = `${colors.tag("<")}${colors.tag(tagName)}${attributes}${colors.tag(">")}`;
+
+    if (!hasChildren(widget) && !text) {
+        return `${indent}${openTag}\n`;
+    }
+
+    const closeTag = `${colors.tag("</")}${colors.tag(tagName)}${colors.tag(">")}`;
+
+    if (text && !hasChildren(widget)) {
+        const textContent = colors.text(text);
+        return `${indent}${openTag}\n${indent}${INDENT}${textContent}\n${indent}${closeTag}\n`;
+    }
+
+    let result = `${indent}${openTag}\n`;
+    if (text) {
+        result += `${indent}${INDENT}${colors.text(text)}\n`;
+    }
+    for (const childOutput of children) {
+        result += childOutput;
+    }
+    result += `${indent}${closeTag}\n`;
+
+    return result;
+};
+
+const printContainer = (container: Container, colors: HighlightColors, includeIds: boolean): string => {
+    if (isApplication(container)) {
+        const windows = Gtk.Window.listToplevels();
+        return windows.map((window) => printWidget(window, colors, 0, includeIds)).join("");
+    }
+    return printWidget(container, colors, 0, includeIds);
+};
+
+/**
+ * Formats a widget tree as a readable string for debugging.
+ *
+ * Renders the widget hierarchy in an HTML-like format with accessibility
+ * attributes like role, data-testid, and text content.
+ *
+ * @param container - The container widget or application to format
+ * @param options - Formatting options for length and highlighting
+ * @returns Formatted string representation of the widget tree
+ *
+ * @example
+ * ```tsx
+ * import { prettyWidget } from "@gtkx/testing";
+ *
+ * console.log(prettyWidget(application));
+ * // Output:
+ * // <GtkApplicationWindow role="window">
+ * //   <GtkButton role="button">
+ * //     Click me
+ * //   </GtkButton>
+ * // </GtkApplicationWindow>
+ * ```
+ */
+export const prettyWidget = (container: Container, options: PrettyWidgetOptions = {}): string => {
+    const envLimit = process.env.DEBUG_PRINT_LIMIT ? Number(process.env.DEBUG_PRINT_LIMIT) : DEFAULT_MAX_LENGTH;
+    const maxLength = options.maxLength ?? envLimit;
+    const highlight = options.highlight ?? shouldHighlight();
+    const includeIds = options.includeIds ?? false;
+
+    if (maxLength === 0) {
+        return "";
+    }
+
+    const colors = createColors(highlight);
+    const output = printContainer(container, colors, includeIds);
+
+    if (output.length > maxLength) {
+        return `${output.slice(0, maxLength)}...`;
+    }
+
+    return output.trimEnd();
+};