@gtkx/testing 0.21.0 → 1.0.0-rc.2

package/src/role-helpers.ts

@@ -1,64 +1,68 @@
-import * as Gtk from "@gtkx/ffi/gtk";
+import * as Gtk from "@gtkx/gi/gtk";
+import { sortStringsBy } from "@gtkx/utils";
 import { type Container, traverse } from "./traversal.js";
-import { getWidgetAccessibleName } from "./widget-text.js";
+import { getWidgetAccessibleName } from "./widget-accessible-properties.js";
 
-/**
- * Information about a widget and its accessible name.
- */
-export type RoleInfo = {
-    widget: Gtk.Widget;
-    name: string | null;
-};
+const ROLE_NAMES_BY_VALUE = enumNamesByValue(Gtk.AccessibleRole);
+
+function enumNamesByValue(enumObject: Record<string, string | number>): Map<number, string> {
+    return new Map<number, string>(
+        Object.entries(enumObject)
+            .filter((entry): entry is [string, number] => typeof entry[1] === "number")
+            .map(([name, value]) => [value, name]),
+    );
+}
 
 /**
- * Formats a GTK accessible role to a lowercase string.
+ * Converts an accessible role enum value into its lowercase name, falling back
+ * to the numeric value when the role is unknown.
  *
- * @param role - The GTK accessible role
- * @returns Lowercase role name (e.g., "button", "checkbox")
+ * @param role The accessible role to format.
  */
-export const formatRole = (role: Gtk.AccessibleRole | undefined): string => {
-    if (role === undefined) return "unknown";
-    const name = Gtk.AccessibleRole[role];
-    if (!name) return String(role);
+const formatRole = (role: Gtk.AccessibleRole): string => {
+    const name = ROLE_NAMES_BY_VALUE.get(role);
+
+    if (!name) {
+        return String(role);
+    }
+
     return name.toLowerCase();
 };
 
+const formatRoleList = (roles: Iterable<Gtk.AccessibleRole>): string => {
+    const names = [...roles].map((role) => formatRole(role).toUpperCase());
+
+    if (names.length <= 1) {
+        return names.join("");
+    }
+
+    if (names.length === 2) {
+        return names.join(" or ");
+    }
+
+    const head = names.slice(0, -1);
+    const last = names.at(-1) ?? "";
+
+    return `${head.join(", ")}, or ${last}`;
+};
+
 /**
- * Collects all accessible roles and their widgets from a container.
+ * Groups every widget in a container's tree by its accessible role name.
  *
- * 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" }]
- * // }
- * ```
+ * @param container The scope to traverse.
+ * @returns A map from role name to the widgets that have that role.
  */
-export const getRoles = (container: Container): Map<string, RoleInfo[]> => {
-    const roles = new Map<string, RoleInfo[]>();
+const getRoles = (container: Container): Map<string, Gtk.Widget[]> => {
+    const roles: Map<string, Gtk.Widget[]> = new Map();
 
     for (const widget of traverse(container)) {
-        const role = widget.getAccessibleRole?.();
-        if (role === undefined) continue;
-
-        const roleName = formatRole(role);
-        const name = getWidgetAccessibleName(widget);
-        const info: RoleInfo = { widget, name };
-
+        const roleName = formatRole(widget.getAccessibleRole());
         const existing = roles.get(roleName);
+
         if (existing) {
-            existing.push(info);
+            existing.push(widget);
         } else {
-            roles.set(roleName, [info]);
+            roles.set(roleName, [widget]);
         }
     }
 
@@ -67,18 +71,19 @@ export const getRoles = (container: Container): Map<string, RoleInfo[]> => {
 
 const formatWidgetPreview = (widget: Gtk.Widget, name: string | null): string => {
     const tagName = widget.constructor.name;
-    const roleAttr = formatRole(widget.getAccessibleRole?.());
+    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.
+ * Formats the accessible roles in a container's tree as a readable string,
+ * listing each role together with its widgets and their accessible names.
  *
- * @param container - The container to format roles for
- * @returns Formatted string showing all roles and their accessible names
+ * @param container The scope to inspect.
  */
-export const prettyRoles = (container: Container): string => {
+const prettyRoles = (container: Container): string => {
     const roles = getRoles(container);
 
     if (roles.size === 0) {
@@ -86,14 +91,15 @@ export const prettyRoles = (container: Container): string => {
     }
 
     const lines: string[] = [];
-
-    const sortedRoles = [...roles.entries()].sort(([a], [b]) => a.localeCompare(b));
+    const sortedRoles = sortStringsBy([...roles], ([roleName]) => roleName);
 
     for (const [roleName, widgets] of sortedRoles) {
         lines.push(`${roleName}:`);
-        for (const { widget, name } of widgets) {
-            lines.push(`  ${formatWidgetPreview(widget, name)}`);
+
+        for (const widget of widgets) {
+            lines.push(`  ${formatWidgetPreview(widget, getWidgetAccessibleName(widget))}`);
         }
+
         lines.push("");
     }
 
@@ -101,26 +107,13 @@ export const prettyRoles = (container: Container): string => {
 };
 
 /**
- * Logs all accessible roles in a container to the console.
- *
- * Useful for debugging test failures and discovering available roles.
+ * Prints the accessible roles in a container's tree to the console using
+ * {@link prettyRoles}.
  *
- * @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>
- * ```
+ * @param container The scope to inspect.
  */
-export const logRoles = (container: Container): void => {
+const logRoles = (container: Container): void => {
     console.log(prettyRoles(container));
 };
+
+export { formatRole, formatRoleList, getRoles, prettyRoles, logRoles };

package/src/screen.ts

@@ -1,125 +1,37 @@
-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";
+import type { RenderResult, Screen } from "./bound-queries.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 NO_RENDER_MESSAGE = "No render has been performed: call render() before using screen queries";
 
-const getRoot = (): Gtk.Application => {
-    if (!currentRoot) {
-        throw new Error("No render has been performed: call render() before using screen queries");
-    }
+const defaultScreen: RenderResult = new Proxy({} as RenderResult, {
+    get: (_target, property) => {
+        if (property === "baseElement" || property === "container") {
+            return throwNoRender();
+        }
 
-    return currentRoot;
-};
+        return throwNoRender;
+    },
+});
 
-const boundQueries = bindQueries(getRoot);
+const activeScreen: { current: RenderResult } = { current: defaultScreen };
 
 /**
- * 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
+ * Queries and debug utilities bound to the most recent render, scoped to the
+ * current toplevel windows. Accessing it before any render throws.
  */
-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");
-        }
+const screen: Screen = new Proxy({} as Screen, {
+    get: (_target, property): unknown => Reflect.get(activeScreen.current, property),
+});
 
-        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;
+const throwNoRender = (): never => {
+    throw new Error(NO_RENDER_MESSAGE);
+};
 
-            if (!targetWindow) {
-                const pattern = isRegex ? selector.toString() : `"${selector}"`;
-                throw new Error(`No window found with title matching ${pattern}`);
-            }
-        }
+const setScreen = (result: RenderResult): void => {
+    activeScreen.current = result;
+};
 
-        const result = await screenshotWidget(targetWindow, options);
-        saveAndLogScreenshot(result);
-        return result;
-    },
+const clearScreen = (): void => {
+    activeScreen.current = defaultScreen;
 };
+
+export { screen, setScreen, clearScreen };

package/src/screenshot.ts

@@ -1,47 +1,47 @@
-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 * as Gsk from "@gtkx/gi/gsk";
+import * as Gtk from "@gtkx/gi/gtk";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ScreenshotOptions, ScreenshotResult, WindowSelector } from "./types.js";
 import { waitFor } from "./wait-for.js";
 
+const DEFAULT_SCREENSHOT_INTERVAL = 10;
+
 const bytesToBase64 = (bytes: number[]): string => {
     return Buffer.from(bytes).toString("base64");
 };
 
-const DEFAULT_SCREENSHOT_TIMEOUT = 100;
-const DEFAULT_SCREENSHOT_INTERVAL = 10;
+const describeWidgetState = (widget: Gtk.Widget): string =>
+    `realized=${String(widget.getRealized())} mapped=${String(widget.getMapped())} ` +
+    `visible=${String(widget.getVisible())}`;
 
-const captureSnapshot = (widget: Gtk.Widget): ScreenshotResult => {
-    const paintable = new Gtk.WidgetPaintable(widget);
+const captureSnapshot = (widget: Gtk.Widget, scale: number): 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");
+        throw new Error(`Widget has no size: ensure it is realized and visible (${describeWidgetState(widget)})`);
     }
 
     const snapshot = new Gtk.Snapshot();
+    snapshot.scale(scale, scale);
     paintable.snapshot(snapshot, width, height);
     const renderNode = snapshot.toNode();
 
     if (!renderNode) {
-        throw new Error("Widget produced no render content");
+        throw new Error(`Widget produced no render content (${describeWidgetState(widget)})`);
     }
 
     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 texture = renderer.renderTexture(renderNode, null);
         const pngBytes = texture.saveToPngBytes();
-        const sizeRef = createRef(0);
-        const data = pngBytes.getData(sizeRef);
+        const data = pngBytes.getData();
 
         if (!data) {
             throw new Error("Failed to serialize screenshot to PNG");
@@ -50,8 +50,8 @@ const captureSnapshot = (widget: Gtk.Widget): ScreenshotResult => {
         return {
             data: bytesToBase64(data),
             mimeType: "image/png",
-            width,
-            height,
+            width: Math.round(width * scale),
+            height: Math.round(height * scale),
         };
     } finally {
         renderer.unrealize();
@@ -59,47 +59,119 @@ const captureSnapshot = (widget: Gtk.Widget): ScreenshotResult => {
 };
 
 /**
- * Options for capturing widget screenshots.
+ * Captures a PNG snapshot of a widget, retrying until it has a paintable size.
+ *
+ * @param widget The widget to render to an image.
+ * @param options Optional scale, timeout, and retry interval.
+ * @returns The base64-encoded PNG data along with its mime type and dimensions.
  */
-export type ScreenshotOptions = Pick<WaitForOptions, "timeout" | "interval">;
+const screenshot = async (widget: Gtk.Widget, options?: ScreenshotOptions): Promise<ScreenshotResult> => {
+    const scale = options?.scale ?? 1;
+
+    if (!Number.isFinite(scale) || scale <= 0) {
+        throw new Error(`Screenshot scale must be a positive number, got ${String(scale)}`);
+    }
+
+    return waitFor(() => captureSnapshot(widget, scale), {
+        timeout: options?.timeout,
+        interval: options?.interval ?? DEFAULT_SCREENSHOT_INTERVAL,
+    });
+};
+
+const firstToplevelWindow = (windows: Gtk.Widget[]): Gtk.Window => {
+    const [first] = windows;
+
+    if (!(first instanceof Gtk.Window)) {
+        throw new TypeError("First toplevel is not a Window");
+    }
+
+    return first;
+};
+
+const windowAtIndex = (windows: Gtk.Widget[], index: number): Gtk.Window => {
+    const indexed = windows[index];
+
+    if (!(indexed instanceof Gtk.Window)) {
+        throw new TypeError(`Window at index ${String(index)} not found`);
+    }
+
+    return indexed;
+};
+
+const isWindow = (widget: Gtk.Widget): widget is Gtk.Window => widget instanceof Gtk.Window;
+
+const hasMatchingTitle = (window: Gtk.Window, selector: string | RegExp): boolean => {
+    const title = window.getTitle() ?? "";
+
+    return selector instanceof RegExp ? selector.test(title) : title.includes(selector);
+};
+
+const describeTitleSelector = (selector: string | RegExp): string =>
+    selector instanceof RegExp ? selector.toString() : `"${selector}"`;
+
+const windowByTitle = (windows: Gtk.Widget[], selector: string | RegExp): Gtk.Window => {
+    const found = windows.filter(isWindow).find((window) => hasMatchingTitle(window, selector));
+
+    if (!found) {
+        throw new Error(`No window found with title matching ${describeTitleSelector(selector)}`);
+    }
+
+    return found;
+};
+
+const resolveWindow = (selector?: WindowSelector): Gtk.Window => {
+    const windows = Gtk.Window.listToplevels();
+
+    if (windows.length === 0) {
+        throw new Error("No windows available for screenshot");
+    }
+
+    if (selector === undefined) {
+        return firstToplevelWindow(windows);
+    }
+
+    if (typeof selector === "number") {
+        return windowAtIndex(windows, selector);
+    }
+
+    return windowByTitle(windows, selector);
+};
+
+const saveScreenshotToTempFile = (result: ScreenshotResult): string => {
+    const dir = mkdtempSync(join(tmpdir(), "gtkx-screenshots-"));
+    const filepath = join(dir, "screenshot.png");
+    writeFileSync(filepath, Buffer.from(result.data, "base64"));
+
+    return filepath;
+};
 
 /**
- * Captures a screenshot of a GTK widget as a PNG image.
+ * Prints a clickable file URL for a saved screenshot to the console.
  *
- * 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";
+ * @param filepath Absolute path of the saved screenshot file.
+ */
+const logScreenshotPath = (filepath: string): void => {
+    console.log(`Screenshot saved: file://${filepath}`);
+};
+
+/**
+ * Captures a screenshot of a toplevel window, writes it to a temporary file,
+ * logs its path, and returns the image data.
  *
- * const { container } = await render(<MyApp />);
- * const window = container.getWindows()[0];
- * const result = await screenshot(window);
- * console.log(result.mimeType); // "image/png"
- * ```
+ * @param selector Chooses the window by index, title substring, or regular
+ * expression; defaults to the first toplevel.
+ * @param options Optional scale, timeout, and retry interval.
+ * @returns The base64-encoded PNG data along with its mime type and dimensions.
  */
-export const screenshot = async (widget: Gtk.Widget, options?: ScreenshotOptions): Promise<ScreenshotResult> => {
-    await tick();
+const captureAndSaveScreenshot = async (
+    selector?: WindowSelector,
+    options?: ScreenshotOptions,
+): Promise<ScreenshotResult> => {
+    const target = resolveWindow(selector);
+    const result = await screenshot(target, options);
+    logScreenshotPath(saveScreenshotToTempFile(result));
 
-    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}`);
-        },
-    });
+    return result;
 };
+
+export { screenshot, logScreenshotPath, captureAndSaveScreenshot };