@gtkx/testing 0.20.0 → 1.0.0-rc.1

package/src/matchers.ts

@@ -0,0 +1,200 @@
+/// <reference types="@vitest/expect" />
+import * as Gtk from "@gtkx/gi/gtk";
+import {
+    getWidgetAccessibleName,
+    getWidgetCheckedState,
+    getWidgetDisplayValue,
+    getWidgetExpandedState,
+    getWidgetNodeText,
+    getWidgetPlaceholderText,
+    getWidgetPressedState,
+    getWidgetSelectedState,
+    getWidgetValue,
+} from "./widget-accessible-properties.js";
+
+/** The expected value for a text matcher: an exact string or a regular expression. */
+export type TextExpectation = string | RegExp;
+
+type MatcherResult = { pass: boolean; message: () => string };
+
+interface MatcherContext {
+    isNot: boolean;
+}
+
+type TextMatcher = (this: MatcherContext, received: unknown, expected?: TextExpectation) => MatcherResult;
+type StateMatcher = (this: MatcherContext, received: unknown) => MatcherResult;
+type ValueMatcher = (this: MatcherContext, received: unknown, expected: number) => MatcherResult;
+
+const asWidget = (received: unknown, matcherName: string): Gtk.Widget => {
+    if (!(received instanceof Gtk.Widget)) {
+        throw new TypeError(`${matcherName}: received value must be a Gtk.Widget, got ${typeof received}`);
+    }
+    return received;
+};
+
+const describeWidget = (widget: Gtk.Widget): string => {
+    const role = Gtk.AccessibleRole[widget.getAccessibleRole()];
+    const name = getWidgetAccessibleName(widget);
+    return name !== null ? `<${role} name=${JSON.stringify(name)}>` : `<${role}>`;
+};
+
+const matchesText = (actual: string, expected: TextExpectation, mode: "exact" | "substring"): boolean => {
+    if (expected instanceof RegExp) {
+        expected.lastIndex = 0;
+        return expected.test(actual);
+    }
+    return mode === "exact" ? actual === expected : actual.includes(expected);
+};
+
+const describeExpected = (expected: TextExpectation): string =>
+    expected instanceof RegExp ? String(expected) : JSON.stringify(expected);
+
+const textMatcher = (
+    matcherName: string,
+    read: (widget: Gtk.Widget) => string | null,
+    mode: "exact" | "substring",
+): TextMatcher =>
+    function (this: MatcherContext, received: unknown, expected?: TextExpectation): MatcherResult {
+        const widget = asWidget(received, matcherName);
+        const actual = read(widget);
+
+        if (expected === undefined) {
+            const pass = actual !== null && actual !== "";
+            return {
+                pass,
+                message: () =>
+                    `expected widget ${this.isNot ? "not " : ""}to have a non-empty value for ${matcherName}, ` +
+                    `but got ${JSON.stringify(actual)}\n${describeWidget(widget)}`,
+            };
+        }
+
+        const pass = actual !== null && matchesText(actual, expected, mode);
+        return {
+            pass,
+            message: () =>
+                `expected widget ${this.isNot ? "not " : ""}${matcherName} ${describeExpected(expected)}, ` +
+                `but received ${JSON.stringify(actual)}\n${describeWidget(widget)}`,
+        };
+    };
+
+const booleanStateMatcher = (
+    matcherName: string,
+    stateName: string,
+    read: (widget: Gtk.Widget) => boolean | null,
+): StateMatcher =>
+    function (this: MatcherContext, received: unknown): MatcherResult {
+        const widget = asWidget(received, matcherName);
+        const state = read(widget);
+        if (state === null) {
+            throw new Error(
+                `${matcherName}: widget does not expose a ${stateName} state ` +
+                    `(role ${Gtk.AccessibleRole[widget.getAccessibleRole()]})\n${describeWidget(widget)}`,
+            );
+        }
+        return {
+            pass: state,
+            message: () => `expected widget ${this.isNot ? "not " : ""}to be ${stateName}\n${describeWidget(widget)}`,
+        };
+    };
+
+export const toHaveDisplayValue: TextMatcher = textMatcher("toHaveDisplayValue", getWidgetDisplayValue, "exact");
+export const toHaveTextContent: TextMatcher = textMatcher(
+    "toHaveTextContent",
+    (widget) => getWidgetNodeText(widget) ?? getWidgetAccessibleName(widget),
+    "substring",
+);
+export const toHaveAccessibleName: TextMatcher = textMatcher("toHaveAccessibleName", getWidgetAccessibleName, "exact");
+export const toHavePlaceholderText: TextMatcher = textMatcher(
+    "toHavePlaceholderText",
+    getWidgetPlaceholderText,
+    "exact",
+);
+
+export const toBeChecked: StateMatcher = booleanStateMatcher("toBeChecked", "checked", getWidgetCheckedState);
+export const toBePressed: StateMatcher = booleanStateMatcher("toBePressed", "pressed", getWidgetPressedState);
+export const toBeExpanded: StateMatcher = booleanStateMatcher("toBeExpanded", "expanded", getWidgetExpandedState);
+export const toBeSelected: StateMatcher = booleanStateMatcher("toBeSelected", "selected", getWidgetSelectedState);
+
+export const toHaveValue: ValueMatcher = function (
+    this: MatcherContext,
+    received: unknown,
+    expected: number,
+): MatcherResult {
+    const widget = asWidget(received, "toHaveValue");
+    const actual = getWidgetValue(widget).now;
+    if (actual === null) {
+        throw new Error(
+            `toHaveValue: widget does not expose a numeric value ` +
+                `(role ${Gtk.AccessibleRole[widget.getAccessibleRole()]})\n${describeWidget(widget)}`,
+        );
+    }
+    return {
+        pass: actual === expected,
+        message: () =>
+            `expected widget ${this.isNot ? "not " : ""}to have value ${expected}, but received ${actual}\n${describeWidget(widget)}`,
+    };
+};
+
+interface MatcherImplementations {
+    toHaveDisplayValue: TextMatcher;
+    toHaveTextContent: TextMatcher;
+    toHaveAccessibleName: TextMatcher;
+    toHavePlaceholderText: TextMatcher;
+    toBeChecked: StateMatcher;
+    toBePressed: StateMatcher;
+    toBeExpanded: StateMatcher;
+    toBeSelected: StateMatcher;
+    toHaveValue: ValueMatcher;
+}
+
+/** The widget assertion matchers keyed by name, suitable for passing to `expect.extend`. */
+export const matchers: MatcherImplementations = {
+    toHaveDisplayValue,
+    toHaveTextContent,
+    toHaveAccessibleName,
+    toHavePlaceholderText,
+    toBeChecked,
+    toBePressed,
+    toBeExpanded,
+    toBeSelected,
+    toHaveValue,
+};
+
+type ExpectExtend = { extend: (m: MatcherImplementations) => void };
+
+const globalExpect = (): ExpectExtend | null => {
+    const candidate: unknown = Reflect.get(globalThis, "expect");
+    if (candidate && typeof (candidate as ExpectExtend).extend === "function") {
+        return candidate as ExpectExtend;
+    }
+    return null;
+};
+
+let registered = false;
+
+/** Registers the widget matchers on the global `expect`, when one is available. Safe to call more than once. */
+export const registerMatchers = (): void => {
+    if (registered) return;
+    const expect = globalExpect();
+    if (!expect) return;
+    expect.extend(matchers);
+    registered = true;
+};
+
+interface WidgetMatchers<R = void> {
+    toHaveDisplayValue(expected?: TextExpectation): R;
+    toHaveTextContent(expected?: TextExpectation): R;
+    toHaveAccessibleName(expected?: TextExpectation): R;
+    toHavePlaceholderText(expected?: TextExpectation): R;
+    toBeChecked(): R;
+    toBePressed(): R;
+    toBeExpanded(): R;
+    toBeSelected(): R;
+    toHaveValue(expected: number): R;
+}
+
+declare module "@vitest/expect" {
+    // biome-ignore lint/suspicious/noExplicitAny: must match the `Assertion<T>` signature it augments for declaration merging
+    interface Assertion<T = any> extends WidgetMatchers {}
+    interface AsymmetricMatchersContaining extends WidgetMatchers {}
+}

package/src/pretty-widget.ts

@@ -1,48 +1,61 @@
-import * as Gtk from "@gtkx/ffi/gtk";
+import type * as Gtk from "@gtkx/gi/gtk";
+import { sortStringsBy } from "@gtkx/utils";
 import { formatRole } from "./role-helpers.js";
-import { type Container, isApplication } from "./traversal.js";
-import { getWidgetPropertyText } from "./widget-text.js";
+import { type Container, roots } from "./traversal.js";
+import { getWidgetNodeText } from "./widget-accessible-properties.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;
-};
+type WidgetIdResolver = (widget: Gtk.Widget) => string;
 
 /**
- * Options for {@link prettyWidget}.
+ * Options controlling how a widget tree is rendered to a string by
+ * {@link prettyWidget} and {@link logWidget}.
  */
 export type PrettyWidgetOptions = {
-    /** Maximum output length before truncation (default: 7000) */
+    /** Truncates the output once it exceeds this many characters. */
     maxLength?: number;
-    /** Enable ANSI color highlighting (default: auto-detect) */
+    /** Whether to apply ANSI color highlighting; defaults to the terminal capabilities. */
     highlight?: boolean;
-    /** Include widget IDs for MCP/agentic interactions (default: false) */
-    includeIds?: boolean;
+    /** Resolves an `id` attribute to show for each widget. */
+    getId?: WidgetIdResolver;
 };
 
-type HighlightColors = {
+const buildAttrs = (widget: Gtk.Widget, getId: WidgetIdResolver | undefined): [string, string][] => {
+    const attrs: [string, string][] = [];
+
+    if (getId) {
+        attrs.push(["id", getId(widget)]);
+    }
+
+    const name = widget.getName();
+    if (name) {
+        attrs.push(["name", name]);
+    }
+
+    attrs.push(["role", formatRole(widget.getAccessibleRole())]);
+
+    if (!widget.getSensitive()) {
+        attrs.push(["accessible-disabled", "true"]);
+    }
+
+    if (!widget.getVisible()) {
+        attrs.push(["accessible-hidden", "true"]);
+    }
+
+    const idAttrs = attrs.filter(([key]) => key === "id");
+    const otherAttrs = sortStringsBy(
+        attrs.filter(([key]) => key !== "id"),
+        ([key]) => key,
+    );
+    return [...idAttrs, ...otherAttrs];
+};
+
+type Colors = {
     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 = {
@@ -52,150 +65,85 @@ const ansi = {
     reset: "\x1b[0m",
 };
 
-const createColors = (enabled: boolean): HighlightColors => {
+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;
+};
+
+const createColors = (enabled: boolean): Colors => {
     if (!enabled) {
         const identity = (s: string): string => s;
-        return { tag: identity, attr: identity, value: identity, text: identity, reset: "" };
+        return { tag: identity, attr: identity, value: identity };
     }
     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][] = [];
+const escapeAttrValue = (value: string): string => value.replaceAll('"', "&quot;");
 
-    if (includeIds) {
-        attrs.push(["id", getWidgetDebugId(widget)]);
-    }
+const formatAttrs = (attrs: [string, string][], colors: Colors): string =>
+    attrs.map(([key, value]) => ` ${colors.attr(key)}=${colors.value(`"${escapeAttrValue(value)}"`)}`).join("");
 
-    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 formatWidget = (
+    widget: Gtk.Widget,
+    depth: number,
+    getId: WidgetIdResolver | undefined,
+    colors: Colors,
+): string => {
     const indent = INDENT.repeat(depth);
-    const tagName = formatTagName(widget);
-    const attributes = formatAttributes(widget, colors, includeIds);
-    const text = getWidgetPropertyText(widget);
-    const children: string[] = [];
-
-    let child = widget.getFirstChild();
-    while (child) {
-        children.push(printWidget(child, colors, depth + 1, includeIds));
-        child = child.getNextSibling();
-    }
+    const tag = widget.constructor.name;
+    const attrs = formatAttrs(buildAttrs(widget, getId), colors);
+    const openTag = `${colors.tag("<")}${colors.tag(tag)}${attrs}${colors.tag(">")}`;
+    const closeTag = `${colors.tag("</")}${colors.tag(tag)}${colors.tag(">")}`;
 
-    const openTag = `${colors.tag("<")}${colors.tag(tagName)}${attributes}${colors.tag(">")}`;
+    const text = getWidgetNodeText(widget);
+    const firstChild = widget.getFirstChild();
 
-    if (!hasChildren(widget) && !text) {
+    if (!text && !firstChild) {
         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`;
+    let output = `${indent}${openTag}\n`;
     if (text) {
-        result += `${indent}${INDENT}${colors.text(text)}\n`;
-    }
-    for (const childOutput of children) {
-        result += childOutput;
+        output += `${indent}${INDENT}${text}\n`;
     }
-    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("");
+    let child = firstChild;
+    while (child) {
+        output += formatWidget(child, depth + 1, getId, colors);
+        child = child.getNextSibling();
     }
-    return printWidget(container, colors, 0, includeIds);
+    output += `${indent}${closeTag}\n`;
+    return output;
 };
 
 /**
- * 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";
+ * Renders a widget tree as an indented, HTML-like string showing each widget's
+ * tag, accessible attributes, and text content.
  *
- * console.log(prettyWidget(application));
- * // Output:
- * // <GtkApplicationWindow role="window">
- * //   <GtkButton role="button">
- * //     Click me
- * //   </GtkButton>
- * // </GtkApplicationWindow>
- * ```
+ * @param container The scope whose widget tree is formatted.
+ * @param options Formatting options such as truncation length and highlighting.
+ * @returns The formatted representation of the tree.
  */
 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 highlight = options.highlight ?? shouldHighlight();
     const colors = createColors(highlight);
-    const output = printContainer(container, colors, includeIds);
+
+    let output = "";
+    for (const root of roots(container)) {
+        output += formatWidget(root, 0, options.getId, colors);
+    }
 
     if (output.length > maxLength) {
         return `${output.slice(0, maxLength)}...`;
@@ -203,3 +151,16 @@ export const prettyWidget = (container: Container, options: PrettyWidgetOptions
 
     return output.trimEnd();
 };
+
+/**
+ * Prints one or more widget trees to the console using {@link prettyWidget}.
+ *
+ * @param container A single scope or an array of scopes to format and print.
+ * @param options Formatting options passed through to {@link prettyWidget}.
+ */
+export const logWidget = (container: Container | Container[], options?: PrettyWidgetOptions): void => {
+    const containers: Container[] = Array.isArray(container) ? container : [container];
+    for (const target of containers) {
+        console.log(prettyWidget(target, options));
+    }
+};