@gtkx/testing 0.11.0 → 0.12.0

package/dist/bind-queries.d.ts

@@ -0,0 +1,13 @@
+import type { Container } from "./traversal.js";
+import type { BoundQueries } from "./types.js";
+type ContainerOrGetter = Container | (() => Container);
+/**
+ * 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 declare const bindQueries: (containerOrGetter: ContainerOrGetter) => BoundQueries;
+export {};

package/dist/bind-queries.js

@@ -0,0 +1,28 @@
+import * as queries from "./queries.js";
+const resolveContainer = (containerOrGetter) => 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) => ({
+    queryByRole: (role, options) => queries.queryByRole(resolveContainer(containerOrGetter), role, options),
+    queryByLabelText: (text, options) => queries.queryByLabelText(resolveContainer(containerOrGetter), text, options),
+    queryByText: (text, options) => queries.queryByText(resolveContainer(containerOrGetter), text, options),
+    queryByTestId: (testId, options) => queries.queryByTestId(resolveContainer(containerOrGetter), testId, options),
+    queryAllByRole: (role, options) => queries.queryAllByRole(resolveContainer(containerOrGetter), role, options),
+    queryAllByLabelText: (text, options) => queries.queryAllByLabelText(resolveContainer(containerOrGetter), text, options),
+    queryAllByText: (text, options) => queries.queryAllByText(resolveContainer(containerOrGetter), text, options),
+    queryAllByTestId: (testId, options) => queries.queryAllByTestId(resolveContainer(containerOrGetter), testId, options),
+    findByRole: (role, options) => queries.findByRole(resolveContainer(containerOrGetter), role, options),
+    findByLabelText: (text, options) => queries.findByLabelText(resolveContainer(containerOrGetter), text, options),
+    findByText: (text, options) => queries.findByText(resolveContainer(containerOrGetter), text, options),
+    findByTestId: (testId, options) => queries.findByTestId(resolveContainer(containerOrGetter), testId, options),
+    findAllByRole: (role, options) => queries.findAllByRole(resolveContainer(containerOrGetter), role, options),
+    findAllByLabelText: (text, options) => queries.findAllByLabelText(resolveContainer(containerOrGetter), text, options),
+    findAllByText: (text, options) => queries.findAllByText(resolveContainer(containerOrGetter), text, options),
+    findAllByTestId: (testId, options) => queries.findAllByTestId(resolveContainer(containerOrGetter), testId, options),
+});

package/dist/config.d.ts

@@ -0,0 +1,59 @@
+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;
+};
+/**
+ * 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 declare const getConfig: () => Readonly<Config>;
+/**
+ * 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 declare const configure: (newConfig: Partial<Config> | ((current: Config) => Partial<Config>)) => void;
+/**
+ * Resets configuration to defaults.
+ * Primarily used for testing.
+ *
+ * @internal
+ */
+export declare const resetConfig: () => void;

package/dist/config.js

@@ -0,0 +1,58 @@
+const defaultGetElementError = (message, _container) => {
+    return new Error(message);
+};
+const defaultConfig = {
+    showSuggestions: true,
+    getElementError: defaultGetElementError,
+};
+let currentConfig = { ...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 = () => {
+    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) => {
+    const updates = typeof newConfig === "function" ? newConfig(currentConfig) : newConfig;
+    currentConfig = { ...currentConfig, ...updates };
+};
+/**
+ * Resets configuration to defaults.
+ * Primarily used for testing.
+ *
+ * @internal
+ */
+export const resetConfig = () => {
+    currentConfig = { ...defaultConfig };
+};

package/dist/error-builder.d.ts

@@ -0,0 +1,27 @@
+import type * as Gtk from "@gtkx/ffi/gtk";
+import type { Container } from "./traversal.js";
+import type { ByRoleOptions, TextMatch } from "./types.js";
+type QueryType = "role" | "text" | "labelText" | "testId";
+/**
+ * Builds an error for when no elements match a query.
+ */
+export declare const buildNotFoundError: (container: Container, queryType: QueryType, args: {
+    role?: Gtk.AccessibleRole;
+    text?: TextMatch;
+    testId?: TextMatch;
+    options?: ByRoleOptions;
+}) => Error;
+/**
+ * Builds an error for when multiple elements match a query but only one was expected.
+ */
+export declare const buildMultipleFoundError: (container: Container, queryType: QueryType, args: {
+    role?: Gtk.AccessibleRole;
+    text?: TextMatch;
+    testId?: TextMatch;
+    options?: ByRoleOptions;
+}, count: number) => Error;
+/**
+ * Builds a timeout error with the last query error message.
+ */
+export declare const buildTimeoutError: (timeout: number, lastError: Error | null) => Error;
+export {};

package/dist/error-builder.js

@@ -0,0 +1,80 @@
+import { getConfig } from "./config.js";
+import { prettyWidget } from "./pretty-widget.js";
+import { formatRole, prettyRoles } from "./role-helpers.js";
+const formatTextMatcher = (text) => {
+    if (typeof text === "function") {
+        return "custom function";
+    }
+    if (text instanceof RegExp) {
+        return text.toString();
+    }
+    return `'${text}'`;
+};
+const formatByRoleDescription = (role, options) => {
+    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, args) => {
+    switch (queryType) {
+        case "role":
+            return formatByRoleDescription(args.role, args.options);
+        case "text":
+            return `text ${formatTextMatcher(args.text)}`;
+        case "labelText":
+            return `label text ${formatTextMatcher(args.text)}`;
+        case "testId":
+            return `test id ${formatTextMatcher(args.testId)}`;
+    }
+};
+/**
+ * Builds an error for when no elements match a query.
+ */
+export const buildNotFoundError = (container, queryType, args) => {
+    const config = getConfig();
+    const description = formatQueryDescription(queryType, args);
+    const lines = [`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, queryType, args, count) => {
+    const config = getConfig();
+    const description = formatQueryDescription(queryType, args);
+    const lines = [`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, lastError) => {
+    const baseMessage = `Timed out after ${timeout}ms`;
+    if (lastError) {
+        return new Error(`${baseMessage}.\n\n${lastError.message}`);
+    }
+    return new Error(baseMessage);
+};

package/dist/fire-event.js

@@ -22,8 +22,8 @@ import { tick } from "./timing.js";
  */
 export const fireEvent = async (element, signalName, ...args) => {
     call("libgobject-2.0.so.0", "g_signal_emit_by_name", [
-        { type: { type: "gobject", ownership: "none" }, value: element.id },
-        { type: { type: "string", ownership: "none" }, value: signalName },
+        { type: { type: "gobject", ownership: "borrowed" }, value: element.handle },
+        { type: { type: "string", ownership: "borrowed" }, value: signalName },
         ...args,
     ], { type: "undefined" });
     await tick();

package/dist/index.d.ts

@@ -1,10 +1,18 @@
+export type { Config } from "./config.js";
+export { configure, getConfig } from "./config.js";
 export { fireEvent } from "./fire-event.js";
-export { findAllByLabelText, findAllByRole, findAllByTestId, findAllByText, findByLabelText, findByRole, findByTestId, findByText, } from "./queries.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 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 { BoundQueries, ByRoleOptions, NormalizerOptions, RenderOptions, RenderResult, TextMatch, TextMatchFunction, TextMatchOptions, WaitForOptions, } from "./types.js";
-export type { TabOptions } from "./user-event.js";
+export type { BoundQueries, ByRoleOptions, NormalizerOptions, RenderOptions, RenderResult, ScreenshotResult, TextMatch, TextMatchFunction, TextMatchOptions, WaitForOptions, } 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/dist/index.js

@@ -1,7 +1,11 @@
+export { configure, getConfig } from "./config.js";
 export { fireEvent } from "./fire-event.js";
-export { findAllByLabelText, findAllByRole, findAllByTestId, findAllByText, findByLabelText, findByRole, findByTestId, findByText, } from "./queries.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 { getRoles, logRoles, prettyRoles } from "./role-helpers.js";
 export { screen } from "./screen.js";
+export { screenshot } from "./screenshot.js";
 export { tick } from "./timing.js";
 export { userEvent } from "./user-event.js";
 export { waitFor, waitForElementToBeRemoved } from "./wait-for.js";

package/dist/pretty-widget.d.ts

@@ -0,0 +1,36 @@
+import { type Container } from "./traversal.js";
+/**
+ * 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;
+};
+/**
+ * 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 declare const prettyWidget: (container: Container, options?: PrettyWidgetOptions) => string;

package/dist/pretty-widget.js

@@ -0,0 +1,150 @@
+import { getNativeId } from "@gtkx/ffi";
+import { formatRole } from "./role-helpers.js";
+import { isApplication } from "./traversal.js";
+import { getWidgetText } from "./widget-text.js";
+const DEFAULT_MAX_LENGTH = 7000;
+const INDENT = "  ";
+const shouldHighlight = () => {
+    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) => {
+    if (!enabled) {
+        const identity = (s) => 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) => {
+    return widget.constructor.name;
+};
+const escapeAttrValue = (value) => {
+    return value.replace(/"/g, """);
+};
+const formatAttributes = (widget, colors, includeIds) => {
+    const attrs = [];
+    if (includeIds) {
+        attrs.push(["id", String(getNativeId(widget.handle))]);
+    }
+    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) => {
+    return widget.getFirstChild() !== null;
+};
+const printWidget = (widget, colors, depth, includeIds) => {
+    const indent = INDENT.repeat(depth);
+    const tagName = formatTagName(widget);
+    const attributes = formatAttributes(widget, colors, includeIds);
+    const text = getWidgetText(widget);
+    const children = [];
+    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, colors, includeIds) => {
+    if (isApplication(container)) {
+        const windows = container.getWindows();
+        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, options = {}) => {
+    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();
+};

package/dist/queries.d.ts

@@ -1,6 +1,82 @@
-import * as Gtk from "@gtkx/ffi/gtk";
+import type * as Gtk from "@gtkx/ffi/gtk";
+import { type Container } from "./traversal.js";
 import type { ByRoleOptions, TextMatch, TextMatchOptions } from "./types.js";
-type Container = Gtk.Application | Gtk.Widget;
+/**
+ * Finds all elements matching a role without throwing.
+ *
+ * @param container - The container to search within
+ * @param role - The GTK accessible role to match
+ * @param options - Query options including name and state filters
+ * @returns Array of matching widgets (empty if none found)
+ */
+export declare const queryAllByRole: (container: Container, role: Gtk.AccessibleRole, options?: ByRoleOptions) => Gtk.Widget[];
+/**
+ * Finds a single element matching a role without throwing.
+ *
+ * @param container - The container to search within
+ * @param role - The GTK accessible role to match
+ * @param options - Query options including name and state filters
+ * @returns The matching widget or null if not found
+ * @throws Error if multiple elements match
+ */
+export declare const queryByRole: (container: Container, role: Gtk.AccessibleRole, options?: ByRoleOptions) => Gtk.Widget | null;
+/**
+ * Finds all elements matching label text without throwing.
+ *
+ * @param container - The container to search within
+ * @param text - Text to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization
+ * @returns Array of matching widgets (empty if none found)
+ */
+export declare const queryAllByLabelText: (container: Container, text: TextMatch, options?: TextMatchOptions) => Gtk.Widget[];
+/**
+ * Finds a single element matching label text without throwing.
+ *
+ * @param container - The container to search within
+ * @param text - Text to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization
+ * @returns The matching widget or null if not found
+ * @throws Error if multiple elements match
+ */
+export declare const queryByLabelText: (container: Container, text: TextMatch, options?: TextMatchOptions) => Gtk.Widget | null;
+/**
+ * Finds all elements matching text content without throwing.
+ *
+ * @param container - The container to search within
+ * @param text - Text to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization
+ * @returns Array of matching widgets (empty if none found)
+ */
+export declare const queryAllByText: (container: Container, text: TextMatch, options?: TextMatchOptions) => Gtk.Widget[];
+/**
+ * Finds a single element matching text content without throwing.
+ *
+ * @param container - The container to search within
+ * @param text - Text to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization
+ * @returns The matching widget or null if not found
+ * @throws Error if multiple elements match
+ */
+export declare const queryByText: (container: Container, text: TextMatch, options?: TextMatchOptions) => Gtk.Widget | null;
+/**
+ * Finds all elements matching a test ID without throwing.
+ *
+ * @param container - The container to search within
+ * @param testId - Test ID to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization
+ * @returns Array of matching widgets (empty if none found)
+ */
+export declare const queryAllByTestId: (container: Container, testId: TextMatch, options?: TextMatchOptions) => Gtk.Widget[];
+/**
+ * Finds a single element matching a test ID without throwing.
+ *
+ * @param container - The container to search within
+ * @param testId - Test ID to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization
+ * @returns The matching widget or null if not found
+ * @throws Error if multiple elements match
+ */
+export declare const queryByTestId: (container: Container, testId: TextMatch, options?: TextMatchOptions) => Gtk.Widget | null;
 /**
  * Finds a single element by accessible role.
  *
@@ -100,4 +176,3 @@ export declare const findByTestId: (container: Container, testId: TextMatch, opt
  * @returns Promise resolving to array of matching widgets
  */
 export declare const findAllByTestId: (container: Container, testId: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
-export {};