@gtkx/testing 0.18.0 → 0.18.2

package/src/render.tsx

@@ -0,0 +1,192 @@
+import { start, stop } from "@gtkx/ffi";
+import * as Gio from "@gtkx/ffi/gio";
+import type * as Gtk from "@gtkx/ffi/gtk";
+import { ApplicationContext, GtkApplicationWindow, reconciler } from "@gtkx/react";
+import { createRef, type ReactNode, type Ref } from "react";
+import type Reconciler from "react-reconciler";
+import { bindQueries } from "./bind-queries.js";
+import { prettyWidget } from "./pretty-widget.js";
+import { setScreenRoot } from "./screen.js";
+import { tick } from "./timing.js";
+import { type Container, isApplication, traverse } from "./traversal.js";
+import type { RenderOptions, RenderResult, WrapperComponent } from "./types.js";
+
+let application: Gtk.Application | null = null;
+let container: Reconciler.FiberRoot | null = null;
+let lastRenderError: Error | null = null;
+
+type ReconcilerInstance = ReturnType<typeof reconciler.getInstance>;
+
+const update = async (
+    instance: ReconcilerInstance,
+    element: ReactNode,
+    fiberRoot: Reconciler.FiberRoot,
+): Promise<void> => {
+    lastRenderError = null;
+    instance.updateContainer(element, fiberRoot, null, () => {});
+    await tick();
+
+    if (lastRenderError) {
+        const error = lastRenderError;
+        lastRenderError = null;
+        throw error;
+    }
+};
+
+const handleError = (error: Error): void => {
+    lastRenderError = error;
+};
+
+const ensureInitialized = (): { app: Gtk.Application; container: Reconciler.FiberRoot } => {
+    application = start("org.gtkx.testing", Gio.ApplicationFlags.NON_UNIQUE);
+
+    if (!container) {
+        const instance = reconciler.getInstance();
+        container = instance.createContainer(
+            application,
+            1,
+            null,
+            false,
+            null,
+            "",
+            handleError,
+            handleError,
+            () => {},
+            () => {},
+        );
+    }
+
+    return { app: application, container };
+};
+
+const DefaultWrapper: WrapperComponent = ({ children, ref }) => (
+    <GtkApplicationWindow ref={ref as Ref<Gtk.ApplicationWindow>} defaultWidth={800} defaultHeight={600}>
+        {children}
+    </GtkApplicationWindow>
+);
+
+const findFirstWidget = (root: Container): Gtk.Widget | null => {
+    for (const widget of traverse(root)) {
+        if (isApplication(root)) return widget;
+        return root;
+    }
+    return null;
+};
+
+const wrapElement = (
+    element: ReactNode,
+    wrapperRef: React.RefObject<Gtk.Widget | null>,
+    wrapper: RenderOptions["wrapper"],
+): ReactNode => {
+    if (wrapper === false || wrapper === undefined) return element;
+    const Wrapper = wrapper === true ? DefaultWrapper : wrapper;
+    return <Wrapper ref={wrapperRef}>{element}</Wrapper>;
+};
+
+const resolveContainer = (
+    wrapper: RenderOptions["wrapper"],
+    wrapperRef: React.RefObject<Gtk.Widget | null>,
+    baseElement: Container,
+): Gtk.Widget => {
+    if (wrapper !== false && wrapper !== undefined && wrapperRef.current) {
+        return wrapperRef.current;
+    }
+    const firstWidget = findFirstWidget(baseElement);
+    if (!firstWidget) {
+        throw new Error("render() produced no widgets. Ensure the element renders visible content.");
+    }
+    return firstWidget;
+};
+
+/**
+ * Renders a React element for testing.
+ *
+ * Creates a GTK application context and renders the element, returning
+ * query methods and utilities for interacting with the rendered widgets.
+ *
+ * @param element - The React element to render
+ * @param options - Render options including wrapper configuration
+ * @returns A promise resolving to query methods and utilities
+ *
+ * @example
+ * ```tsx
+ * import { render, screen } from "@gtkx/testing";
+ *
+ * test("button click", async () => {
+ * await render(<MyButton />);
+ * const button = await screen.findByRole(Gtk.AccessibleRole.BUTTON);
+ * await userEvent.click(button);
+ * });
+ * ```
+ *
+ * @see {@link cleanup} for cleaning up after tests
+ * @see {@link screen} for global query access
+ */
+export const render = async (element: ReactNode, options?: RenderOptions): Promise<RenderResult> => {
+    const { app: application, container: fiberRoot } = ensureInitialized();
+    const instance = reconciler.getInstance();
+    const baseElement: Container = options?.baseElement ?? application;
+    const wrapper = options?.wrapper ?? true;
+
+    const wrapperRef = createRef<Gtk.Widget>();
+    const wrappedElement = wrapElement(element, wrapperRef, wrapper);
+    const withContext = <ApplicationContext.Provider value={application}>{wrappedElement}</ApplicationContext.Provider>;
+    await update(instance, withContext, fiberRoot);
+
+    setScreenRoot(application);
+
+    return {
+        container: resolveContainer(wrapper, wrapperRef, baseElement),
+        baseElement,
+        ...bindQueries(baseElement),
+        unmount: () => update(instance, null, fiberRoot),
+        rerender: async (newElement: ReactNode) => {
+            const newWrapperRef = createRef<Gtk.Widget>();
+            const wrapped = wrapElement(newElement, newWrapperRef, wrapper);
+            const withCtx = <ApplicationContext.Provider value={application}>{wrapped}</ApplicationContext.Provider>;
+            await update(instance, withCtx, fiberRoot);
+        },
+        debug: () => {
+            console.log(prettyWidget(application));
+        },
+    };
+};
+
+/**
+ * Cleans up the rendered component tree.
+ *
+ * Unmounts all rendered components and resets the testing environment.
+ * Call this in `afterEach` to ensure tests don't affect each other.
+ *
+ * @example
+ * ```tsx
+ * import { render, cleanup } from "@gtkx/testing";
+ *
+ * afterEach(async () => {
+ * await cleanup();
+ * });
+ *
+ * test("my test", async () => {
+ * await render(<MyComponent />);
+ * // ...
+ * });
+ * ```
+ */
+export const cleanup = async (): Promise<void> => {
+    if (container && application) {
+        const instance = reconciler.getInstance();
+        await update(instance, null, container);
+    }
+    container = null;
+    setScreenRoot(null);
+};
+
+const handleSignal = (): void => {
+    try {
+        stop();
+    } catch {}
+    process.exit(0);
+};
+
+process.on("SIGTERM", handleSignal);
+process.on("SIGINT", handleSignal);

package/src/role-helpers.ts

@@ -0,0 +1,126 @@
+import * as Gtk from "@gtkx/ffi/gtk";
+import { type Container, traverse } from "./traversal.js";
+import { getWidgetText } from "./widget-text.js";
+
+/**
+ * Information about a widget and its accessible name.
+ */
+export type RoleInfo = {
+    widget: Gtk.Widget;
+    name: string | null;
+};
+
+/**
+ * Formats a GTK accessible role to a lowercase string.
+ *
+ * @param role - The GTK accessible role
+ * @returns Lowercase role name (e.g., "button", "checkbox")
+ */
+export const formatRole = (role: Gtk.AccessibleRole | undefined): string => {
+    if (role === undefined) return "unknown";
+    const name = Gtk.AccessibleRole[role];
+    if (!name) return String(role);
+    return name.toLowerCase();
+};
+
+/**
+ * Collects all accessible roles and their widgets from a container.
+ *
+ * Returns a Map where keys are role names (lowercase) and values are
+ * arrays of widgets with that role, including their accessible names.
+ *
+ * @param container - The container to scan for roles
+ * @returns Map of role names to arrays of RoleInfo
+ *
+ * @example
+ * ```tsx
+ * import { getRoles } from "@gtkx/testing";
+ *
+ * const roles = getRoles(container);
+ * // Map {
+ * //   "button" => [{ widget: ..., name: "Submit" }, { widget: ..., name: "Cancel" }],
+ * //   "checkbox" => [{ widget: ..., name: "Remember me" }]
+ * // }
+ * ```
+ */
+export const getRoles = (container: Container): Map<string, RoleInfo[]> => {
+    const roles = new Map<string, RoleInfo[]>();
+
+    for (const widget of traverse(container)) {
+        const role = widget.getAccessibleRole?.();
+        if (role === undefined) continue;
+
+        const roleName = formatRole(role);
+        const name = getWidgetText(widget);
+        const info: RoleInfo = { widget, name };
+
+        const existing = roles.get(roleName);
+        if (existing) {
+            existing.push(info);
+        } else {
+            roles.set(roleName, [info]);
+        }
+    }
+
+    return roles;
+};
+
+const formatWidgetPreview = (widget: Gtk.Widget, name: string | null): string => {
+    const tagName = widget.constructor.name;
+    const roleAttr = formatRole(widget.getAccessibleRole?.());
+    const nameDisplay = name ? `Name "${name}"` : 'Name ""';
+    return `${nameDisplay}: <${tagName} role="${roleAttr}">${name ?? ""}</${tagName}>`;
+};
+
+/**
+ * Formats roles into a readable string for error messages.
+ *
+ * @param container - The container to format roles for
+ * @returns Formatted string showing all roles and their accessible names
+ */
+export const prettyRoles = (container: Container): string => {
+    const roles = getRoles(container);
+
+    if (roles.size === 0) {
+        return "No accessible roles found in the widget tree.";
+    }
+
+    const lines: string[] = [];
+
+    const sortedRoles = [...roles.entries()].sort(([a], [b]) => a.localeCompare(b));
+
+    for (const [roleName, widgets] of sortedRoles) {
+        lines.push(`${roleName}:`);
+        for (const { widget, name } of widgets) {
+            lines.push(`  ${formatWidgetPreview(widget, name)}`);
+        }
+        lines.push("");
+    }
+
+    return lines.join("\n").trimEnd();
+};
+
+/**
+ * Logs all accessible roles in a container to the console.
+ *
+ * Useful for debugging test failures and discovering available roles.
+ *
+ * @param container - The container to log roles for
+ *
+ * @example
+ * ```tsx
+ * import { render, logRoles } from "@gtkx/testing";
+ *
+ * const { container } = await render(<MyComponent />);
+ * logRoles(container);
+ * // Console output:
+ * // button:
+ * //   Name "Submit": <GtkButton role="button">Submit</GtkButton>
+ * //   Name "Cancel": <GtkButton role="button">Cancel</GtkButton>
+ * // checkbox:
+ * //   Name "Remember me": <GtkCheckButton role="checkbox">Remember me</GtkCheckButton>
+ * ```
+ */
+export const logRoles = (container: Container): void => {
+    console.log(prettyRoles(container));
+};

package/src/screen.ts

@@ -0,0 +1,125 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import * as Gtk from "@gtkx/ffi/gtk";
+import { bindQueries } from "./bind-queries.js";
+import { prettyWidget } from "./pretty-widget.js";
+import { logRoles } from "./role-helpers.js";
+import { type ScreenshotOptions, screenshot as screenshotWidget } from "./screenshot.js";
+import type { ScreenshotResult } from "./types.js";
+
+const getScreenshotDir = (): string => {
+    const dir = join(tmpdir(), "gtkx-screenshots");
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+};
+
+const saveAndLogScreenshot = (result: ScreenshotResult): void => {
+    const dir = getScreenshotDir();
+    const filename = `${Date.now()}-screenshot.png`;
+    const filepath = join(dir, filename);
+    const buffer = Buffer.from(result.data, "base64");
+    writeFileSync(filepath, buffer);
+    console.log(`Screenshot saved: file://${filepath}`);
+};
+
+let currentRoot: Gtk.Application | null = null;
+
+/** @internal */
+export const setScreenRoot = (root: Gtk.Application | null): void => {
+    currentRoot = root;
+};
+
+const getRoot = (): Gtk.Application => {
+    if (!currentRoot) {
+        throw new Error("No render has been performed: call render() before using screen queries");
+    }
+
+    return currentRoot;
+};
+
+const boundQueries = bindQueries(getRoot);
+
+/**
+ * Global query object for accessing rendered components.
+ *
+ * Provides the same query methods as render result, but automatically
+ * uses the most recently rendered application as the container.
+ *
+ * @example
+ * ```tsx
+ * import { render, screen } from "@gtkx/testing";
+ *
+ * test("finds button", async () => {
+ *   await render(<MyComponent />);
+ *   const button = await screen.findByRole(Gtk.AccessibleRole.BUTTON);
+ *   expect(button).toBeDefined();
+ * });
+ * ```
+ *
+ * @see {@link render} for rendering components
+ * @see {@link within} for scoped queries
+ */
+export const screen = {
+    ...boundQueries,
+    /** Print the widget tree to console for debugging */
+    debug: () => {
+        console.log(prettyWidget(getRoot()));
+    },
+    /** Log all accessible roles to console for debugging */
+    logRoles: () => {
+        logRoles(getRoot());
+    },
+    /**
+     * Capture a screenshot of the application window, saving it to a temporary file and logging the file path.
+     *
+     * @param selector - Window selector: index (number), title substring (string), or title pattern (RegExp).
+     *                   If omitted, captures the first window.
+     * @param options - Optional timeout and interval configuration for waiting on widget rendering.
+     * @returns Screenshot result containing base64-encoded PNG data
+     * @throws Error if no windows are available or no matching window is found
+     *
+     * @example
+     * ```tsx
+     * await screen.screenshot();              // First window
+     * await screen.screenshot(0);             // Window at index 0
+     * await screen.screenshot("Settings");    // Window with title containing "Settings"
+     * await screen.screenshot(/^My App/);     // Window with title matching regex
+     * ```
+     */
+    screenshot: async (selector?: number | string | RegExp, options?: ScreenshotOptions): Promise<ScreenshotResult> => {
+        const windows = Gtk.Window.listToplevels();
+
+        if (windows.length === 0) {
+            throw new Error("No windows available for screenshot");
+        }
+
+        let targetWindow: Gtk.Window | undefined;
+
+        if (selector === undefined) {
+            targetWindow = windows[0] as Gtk.Window;
+        } else if (typeof selector === "number") {
+            targetWindow = windows[selector] as Gtk.Window | undefined;
+            if (!targetWindow) {
+                throw new Error(`Window at index ${selector} not found`);
+            }
+        } else {
+            const isRegex = selector instanceof RegExp;
+            targetWindow = windows.find((w) => {
+                const title = (w as Gtk.Window).getTitle() ?? "";
+                return isRegex ? selector.test(title) : title.includes(selector);
+            }) as Gtk.Window | undefined;
+
+            if (!targetWindow) {
+                const pattern = isRegex ? selector.toString() : `"${selector}"`;
+                throw new Error(`No window found with title matching ${pattern}`);
+            }
+        }
+
+        const result = await screenshotWidget(targetWindow, options);
+        saveAndLogScreenshot(result);
+        return result;
+    },
+};

package/src/screenshot.ts

@@ -0,0 +1,105 @@
+import { createRef } from "@gtkx/ffi";
+import * as Gsk from "@gtkx/ffi/gsk";
+import * as Gtk from "@gtkx/ffi/gtk";
+import { tick } from "./timing.js";
+import type { ScreenshotResult, WaitForOptions } from "./types.js";
+import { waitFor } from "./wait-for.js";
+
+const bytesToBase64 = (bytes: number[]): string => {
+    return Buffer.from(bytes).toString("base64");
+};
+
+const DEFAULT_SCREENSHOT_TIMEOUT = 100;
+const DEFAULT_SCREENSHOT_INTERVAL = 10;
+
+const captureSnapshot = (widget: Gtk.Widget): ScreenshotResult => {
+    const paintable = new Gtk.WidgetPaintable(widget);
+    const width = paintable.getIntrinsicWidth();
+    const height = paintable.getIntrinsicHeight();
+
+    if (width <= 0 || height <= 0) {
+        throw new Error("Widget has no size - ensure it is realized and visible");
+    }
+
+    const snapshot = new Gtk.Snapshot();
+    paintable.snapshot(snapshot, width, height);
+    const renderNode = snapshot.toNode();
+
+    if (!renderNode) {
+        throw new Error("Widget produced no render content");
+    }
+
+    const display = widget.getDisplay();
+    if (!display) {
+        throw new Error("Widget has no display - ensure it is realized");
+    }
+
+    const renderer = new Gsk.CairoRenderer();
+    renderer.realizeForDisplay(display);
+
+    try {
+        const texture = renderer.renderTexture(renderNode);
+        const pngBytes = texture.saveToPngBytes();
+        const sizeRef = createRef(0);
+        const data = pngBytes.getData(sizeRef);
+
+        if (!data) {
+            throw new Error("Failed to serialize screenshot to PNG");
+        }
+
+        return {
+            data: bytesToBase64(data),
+            mimeType: "image/png",
+            width,
+            height,
+        };
+    } finally {
+        renderer.unrealize();
+    }
+};
+
+/**
+ * Options for capturing widget screenshots.
+ */
+export type ScreenshotOptions = Pick<WaitForOptions, "timeout" | "interval">;
+
+/**
+ * Captures a screenshot of a GTK widget as a PNG image.
+ *
+ * This function will retry multiple times if the widget hasn't finished
+ * rendering, waiting for GTK to complete its paint cycle.
+ *
+ * @param widget - The widget to capture (typically a Window)
+ * @param options - Optional timeout and interval configuration
+ * @returns Screenshot result containing base64-encoded PNG data and dimensions
+ * @throws Error if widget has no size, is not realized, or rendering fails after timeout
+ *
+ * @example
+ * ```tsx
+ * import { render, screenshot } from "@gtkx/testing";
+ * import * as Gtk from "@gtkx/ffi/gtk";
+ *
+ * const { container } = await render(<MyApp />);
+ * const window = container.getWindows()[0];
+ * const result = await screenshot(window);
+ * console.log(result.mimeType); // "image/png"
+ * ```
+ */
+export const screenshot = async (widget: Gtk.Widget, options?: ScreenshotOptions): Promise<ScreenshotResult> => {
+    await tick();
+
+    return waitFor(() => captureSnapshot(widget), {
+        timeout: options?.timeout ?? DEFAULT_SCREENSHOT_TIMEOUT,
+        interval: options?.interval ?? DEFAULT_SCREENSHOT_INTERVAL,
+        onTimeout: (error) => {
+            const paintable = new Gtk.WidgetPaintable(widget);
+            const width = paintable.getIntrinsicWidth();
+            const height = paintable.getIntrinsicHeight();
+
+            if (width <= 0 || height <= 0) {
+                return new Error("Widget has no size - ensure it is realized and visible");
+            }
+            return new Error(`Widget produced no render content after waiting for paint cycle. ${error.message}`);
+        },
+    });
+};

package/src/timing.ts

@@ -0,0 +1,17 @@
+/**
+ * Yields to the event loop, allowing pending GTK events to process.
+ *
+ * Use this after actions that trigger async widget updates.
+ *
+ * @returns Promise that resolves on the next event loop tick
+ *
+ * @example
+ * ```tsx
+ * import { tick } from "@gtkx/testing";
+ *
+ * widget.setSensitive(false);
+ * await tick(); // Wait for GTK to process the change
+ * expect(widget.getSensitive()).toBe(false);
+ * ```
+ */
+export const tick = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 0));

package/src/traversal.ts

@@ -0,0 +1,48 @@
+import * as Gtk from "@gtkx/ffi/gtk";
+
+/**
+ * Root element for scoping queries.
+ *
+ * When a `Gtk.Application` is provided, queries search across all toplevel
+ * windows. When a `Gtk.Widget` is provided, queries are scoped to that
+ * widget's subtree.
+ */
+export type Container = Gtk.Application | Gtk.Widget;
+
+export const isApplication = (container: Container): container is Gtk.Application =>
+    "getWindows" in container && typeof container.getWindows === "function";
+
+const traverseWidgetTree = function* (root: Gtk.Widget): Generator<Gtk.Widget> {
+    yield root;
+
+    let child = root.getFirstChild();
+    while (child) {
+        yield* traverseWidgetTree(child);
+        child = child.getNextSibling();
+    }
+};
+
+const traverseWindows = function* (): Generator<Gtk.Widget> {
+    const windows = Gtk.Window.listToplevels();
+    for (const window of windows) {
+        yield* traverseWidgetTree(window);
+    }
+};
+
+export const traverse = function* (container: Container): Generator<Gtk.Widget> {
+    if (isApplication(container)) {
+        yield* traverseWindows();
+    } else {
+        yield* traverseWidgetTree(container);
+    }
+};
+
+export const findAll = (container: Container, predicate: (node: Gtk.Widget) => boolean): Gtk.Widget[] => {
+    const results: Gtk.Widget[] = [];
+    for (const node of traverse(container)) {
+        if (predicate(node)) {
+            results.push(node);
+        }
+    }
+    return results;
+};