@gtkx/testing 1.0.0-rc.1 → 1.0.0-rc.2

package/src/register-test-hooks.ts

@@ -4,7 +4,10 @@ import { cleanup } from "./render.js";
 
 const callRunnerHook = (name: "afterEach" | "afterAll", callback: () => unknown): void => {
     const hook: unknown = Reflect.get(globalThis, name);
-    if (typeof hook === "function") (hook as (callback: () => unknown) => void)(callback);
+
+    if (typeof hook === "function") {
+        (hook as (callback: () => unknown) => void)(callback);
+    }
 };
 
 const registerTestRuntimeHooks = (): void => {

package/src/render-hook.tsx

@@ -1,6 +1,6 @@
 import * as Gtk from "@gtkx/gi/gtk";
-import { render } from "./render.js";
 import type { RenderHookOptions, RenderHookResult } from "./types.js";
+import { render } from "./render.js";
 
 /**
  * Renders a test component that calls the given hook, exposing its latest
@@ -10,10 +10,11 @@ import type { RenderHookOptions, RenderHookResult } from "./types.js";
  * @param options Optional initial props and wrapper component.
  * @returns A result whose `result.current` holds the hook's latest value.
  */
-export function renderHook<Result>(
+function renderHook<Result>(
     callback: () => Result,
     options?: RenderHookOptions<undefined>,
 ): Promise<RenderHookResult<Result, undefined>>;
+
 /**
  * Renders a test component that calls the given hook with props, exposing its
  * latest return value along with rerender and unmount controls.
@@ -22,11 +23,12 @@ export function renderHook<Result>(
  * @param options Initial props and optional wrapper component.
  * @returns A result whose `result.current` holds the hook's latest value.
  */
-export function renderHook<Result, Props>(
+function renderHook<Result, Props>(
     callback: (props: Props) => Result,
     options: RenderHookOptions<Props>,
 ): Promise<RenderHookResult<Result, Props>>;
-export async function renderHook<Result, Props>(
+
+async function renderHook<Result, Props>(
     callback: (props: Props) => Result,
     options?: RenderHookOptions<Props>,
 ): Promise<RenderHookResult<Result, Props>> {
@@ -37,6 +39,7 @@ export async function renderHook<Result, Props>(
     const TestComponent = ({ props }: { props: Props }): null => {
         const result = callback(props);
         resultRef.current = result;
+
         return null;
     };
 
@@ -51,8 +54,11 @@ export async function renderHook<Result, Props>(
             if (newProps !== undefined) {
                 currentProps = newProps;
             }
+
             await renderResult.rerender(<TestComponent props={currentProps} />);
         },
         unmount: renderResult.unmount,
     };
 }
+
+export { renderHook };

package/src/render.tsx

@@ -1,5 +1,5 @@
-import * as Gtk from "@gtkx/gi/gtk";
 import type { RootElement } from "@gtkx/react";
+import * as Gtk from "@gtkx/gi/gtk";
 import {
     createReconcilerRoot,
     isRootElement,
@@ -7,8 +7,9 @@ import {
     setReconcilerErrorHandler,
 } from "@gtkx/react/internal";
 import { type ErrorInfo, type ReactNode, StrictMode } from "react";
-import { runInAct } from "./act.js";
 import type { RenderResult } from "./bound-queries.js";
+import type { QueryMap, RenderOptions, ScreenshotOptions, WindowSelector } from "./types.js";
+import { runInAct } from "./act.js";
 import { addToCleanupQueue, runCleanup } from "./cleanup-registry.js";
 import { scheduleAfterLayout } from "./frame-sync.js";
 import { logWidget, type PrettyWidgetOptions } from "./pretty-widget.js";
@@ -16,20 +17,26 @@ import { logRoles } from "./role-helpers.js";
 import { clearScreen, setScreen } from "./screen.js";
 import { captureAndSaveScreenshot } from "./screenshot.js";
 import { type Container, TOPLEVELS, traverse } from "./traversal.js";
-import type { QueryMap, RenderOptions, ScreenshotOptions, WindowSelector } from "./types.js";
 import { resetClipboard } from "./user-event/index.js";
 import { within } from "./within.js";
 
-let lastRenderError: Error | null = null;
-let errorHandlerInstalled = false;
-
 type ActiveRender = {
     root: ReconcilerRoot;
     window: Gtk.Window | null;
 };
 
-const activeRenders = new Set<ActiveRender>();
+type ResolvedContainer = {
+    containerInfo: Gtk.Widget | RootElement;
+    window: Gtk.Window | null;
+};
 
+type ReconcilerErrorState = {
+    lastError: Error | null;
+    isHandlerInstalled: boolean;
+};
+
+const reconcilerErrors: ReconcilerErrorState = { lastError: null, isHandlerInstalled: false };
+const activeRenders: Set<ActiveRender> = new Set();
 const HARNESS_WINDOW_WIDTH = 800;
 const HARNESS_WINDOW_HEIGHT = 600;
 
@@ -43,15 +50,18 @@ const update = async (element: ReactNode, root: ReconcilerRoot): Promise<void> =
         root.update(element);
     });
 
-    if (lastRenderError) {
-        const captured = lastRenderError;
-        lastRenderError = null;
+    if (reconcilerErrors.lastError) {
+        const captured = reconcilerErrors.lastError;
+        reconcilerErrors.lastError = null;
         throw captured;
     }
 };
 
 const disposeActiveRender = async (active: ActiveRender): Promise<void> => {
-    if (!activeRenders.delete(active)) return;
+    if (!activeRenders.delete(active)) {
+        return;
+    }
+
     await active.root.unmount(async (root) => {
         await update(null, root);
         active.window?.destroy();
@@ -59,42 +69,50 @@ const disposeActiveRender = async (active: ActiveRender): Promise<void> => {
 };
 
 const disposeAllActiveRenders = async (): Promise<void> => {
-    for (const active of [...activeRenders]) {
+    for (const active of activeRenders) {
         await disposeActiveRender(active);
     }
 };
 
 const handleError = (error: unknown): void => {
-    lastRenderError = error instanceof Error ? error : new Error(String(error));
+    reconcilerErrors.lastError = error instanceof Error ? error : new Error(String(error));
 };
 
 const installErrorHandler = (): void => {
-    if (errorHandlerInstalled) return;
-    setReconcilerErrorHandler(handleError);
-    errorHandlerInstalled = true;
-};
+    if (reconcilerErrors.isHandlerInstalled) {
+        return;
+    }
 
-type ResolvedContainer = {
-    containerInfo: Gtk.Widget | RootElement;
-    window: Gtk.Window | null;
+    setReconcilerErrorHandler(handleError);
+    reconcilerErrors.isHandlerInstalled = true;
 };
 
 const resolveContainer = (container: RenderOptions["container"]): ResolvedContainer => {
     if (isRootElement(container)) {
         return { containerInfo: container, window: null };
     }
+
     if (container instanceof Gtk.Widget) {
         return { containerInfo: container, window: null };
     }
+
     const window = new Gtk.Window({ defaultWidth: HARNESS_WINDOW_WIDTH, defaultHeight: HARNESS_WINDOW_HEIGHT });
     window.setTitlebar(new Gtk.HeaderBar({ showTitleButtons: false }));
+
     return { containerInfo: window, window };
 };
 
 const firstToplevelWidget = (baseElement: Container): Gtk.Widget => {
-    if (baseElement instanceof Gtk.Widget) return baseElement;
+    if (baseElement instanceof Gtk.Widget) {
+        return baseElement;
+    }
+
     const [first] = traverse(baseElement);
-    if (first) return first;
+
+    if (first) {
+        return first;
+    }
+
     throw new Error("render() produced no widgets: ensure the element renders visible content");
 };
 
@@ -103,8 +121,14 @@ const resolveResultContainer = (
     container: RenderOptions["container"],
     baseElement: Container,
 ): Gtk.Widget => {
-    if (resolved.window) return resolved.window;
-    if (container instanceof Gtk.Widget) return container;
+    if (resolved.window) {
+        return resolved.window;
+    }
+
+    if (container instanceof Gtk.Widget) {
+        return container;
+    }
+
     return firstToplevelWidget(baseElement);
 };
 
@@ -119,10 +143,11 @@ const renderErrorHandlers = <Q extends QueryMap>(options: RenderOptions<Q> | und
     },
 });
 
-const applyEnableAnimations = (enabled: boolean): void => {
+const applyEnableAnimations = (areAnimationsEnabled: boolean): void => {
     const settings = Gtk.Settings.getDefault();
+
     if (settings) {
-        settings.gtkEnableAnimations = enabled;
+        settings.gtkEnableAnimations = areAnimationsEnabled;
     }
 };
 
@@ -135,38 +160,36 @@ const applyEnableAnimations = (enabled: boolean): void => {
  * @param options Optional container, wrapper, custom queries, and other render settings.
  * @returns A render result with bound queries, debug helpers, and lifecycle controls.
  */
-export const render = async <Q extends QueryMap = Record<never, never>>(
+const render = async <Q extends QueryMap = Record<never, never>>(
     element: ReactNode,
     options?: RenderOptions<Q>,
 ): Promise<RenderResult<Q>> => {
     installErrorHandler();
-
     applyEnableAnimations(options?.animations === true);
-
     const baseElement: Container = options?.baseElement ?? TOPLEVELS;
     const Wrapper = options?.wrapper;
-
     const resolved = resolveContainer(options?.container);
+
     const root = createReconcilerRoot({
         containerInfo: resolved.containerInfo,
         ...renderErrorHandlers(options),
     });
+
     const active: ActiveRender = { root, window: resolved.window };
     activeRenders.add(active);
-
     addToCleanupQueue(disposeAllActiveRenders);
     addToCleanupQueue(clearScreen);
     addToCleanupQueue(resetClipboard);
 
     const wrap = (node: ReactNode): ReactNode => {
         const wrapped = Wrapper ? <Wrapper>{node}</Wrapper> : node;
+
         return options?.reactStrictMode ? <StrictMode>{wrapped}</StrictMode> : wrapped;
     };
 
     await update(wrap(element), root);
     resolved.window?.present();
     await flushLayout(resolved.window);
-
     const container = resolveResultContainer(resolved, options?.container, baseElement);
 
     const result: RenderResult<Q> = {
@@ -199,6 +222,8 @@ export const render = async <Q extends QueryMap = Record<never, never>>(
  * Unmounts every active render and runs all registered cleanup callbacks,
  * resetting the screen and clipboard. Called automatically after each test.
  */
-export const cleanup = async (): Promise<void> => {
+const cleanup = async (): Promise<void> => {
     await runCleanup();
 };
+
+export { render, cleanup };

package/src/role-helpers.ts

@@ -3,14 +3,15 @@ import { sortStringsBy } from "@gtkx/utils";
 import { type Container, traverse } from "./traversal.js";
 import { getWidgetAccessibleName } from "./widget-accessible-properties.js";
 
-const enumNamesByValue = (enumObject: Record<string, string | number>): Map<number, string> =>
-    new Map<number, string>(
+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]),
     );
-
-const ROLE_NAMES_BY_VALUE = enumNamesByValue(Gtk.AccessibleRole);
+}
 
 /**
  * Converts an accessible role enum value into its lowercase name, falling back
@@ -18,22 +19,30 @@ const ROLE_NAMES_BY_VALUE = enumNamesByValue(Gtk.AccessibleRole);
  *
  * @param role The accessible role to format.
  */
-export const formatRole = (role: Gtk.AccessibleRole): string => {
+const formatRole = (role: Gtk.AccessibleRole): string => {
     const name = ROLE_NAMES_BY_VALUE.get(role);
-    if (!name) return String(role);
+
+    if (!name) {
+        return String(role);
+    }
+
     return name.toLowerCase();
 };
 
-export const formatRoleList = (roles: Iterable<Gtk.AccessibleRole>): string => {
+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[0]} or ${names[1]}`;
+        return names.join(" or ");
     }
+
     const head = names.slice(0, -1);
-    const last = names[names.length - 1];
+    const last = names.at(-1) ?? "";
+
     return `${head.join(", ")}, or ${last}`;
 };
 
@@ -43,13 +52,13 @@ export const formatRoleList = (roles: Iterable<Gtk.AccessibleRole>): string => {
  * @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, Gtk.Widget[]> => {
-    const roles = new Map<string, Gtk.Widget[]>();
+const getRoles = (container: Container): Map<string, Gtk.Widget[]> => {
+    const roles: Map<string, Gtk.Widget[]> = new Map();
 
     for (const widget of traverse(container)) {
         const roleName = formatRole(widget.getAccessibleRole());
-
         const existing = roles.get(roleName);
+
         if (existing) {
             existing.push(widget);
         } else {
@@ -64,6 +73,7 @@ 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}>`;
 };
 
@@ -73,7 +83,7 @@ const formatWidgetPreview = (widget: Gtk.Widget, name: string | null): string =>
  *
  * @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) {
@@ -81,14 +91,15 @@ export const prettyRoles = (container: Container): string => {
     }
 
     const lines: string[] = [];
-
-    const sortedRoles = sortStringsBy([...roles.entries()], ([roleName]) => roleName);
+    const sortedRoles = sortStringsBy([...roles], ([roleName]) => roleName);
 
     for (const [roleName, widgets] of sortedRoles) {
         lines.push(`${roleName}:`);
+
         for (const widget of widgets) {
             lines.push(`  ${formatWidgetPreview(widget, getWidgetAccessibleName(widget))}`);
         }
+
         lines.push("");
     }
 
@@ -101,6 +112,8 @@ export const prettyRoles = (container: Container): string => {
  *
  * @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

@@ -2,31 +2,36 @@ import type { RenderResult, Screen } from "./bound-queries.js";
 
 const NO_RENDER_MESSAGE = "No render has been performed: call render() before using screen queries";
 
-const throwNoRender = (): never => {
-    throw new Error(NO_RENDER_MESSAGE);
-};
-
 const defaultScreen: RenderResult = new Proxy({} as RenderResult, {
     get: (_target, property) => {
-        if (property === "baseElement" || property === "container") return throwNoRender();
+        if (property === "baseElement" || property === "container") {
+            return throwNoRender();
+        }
+
         return throwNoRender;
     },
 });
 
-let activeScreen: RenderResult = defaultScreen;
+const activeScreen: { current: RenderResult } = { current: defaultScreen };
 
 /**
  * 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: Screen = new Proxy({} as Screen, {
-    get: (_target, property) => Reflect.get(activeScreen, property),
+const screen: Screen = new Proxy({} as Screen, {
+    get: (_target, property): unknown => Reflect.get(activeScreen.current, property),
 });
 
-export const setScreen = (result: RenderResult): void => {
-    activeScreen = result;
+const throwNoRender = (): never => {
+    throw new Error(NO_RENDER_MESSAGE);
 };
 
-export const clearScreen = (): void => {
-    activeScreen = defaultScreen;
+const setScreen = (result: RenderResult): void => {
+    activeScreen.current = result;
 };
+
+const clearScreen = (): void => {
+    activeScreen.current = defaultScreen;
+};
+
+export { screen, setScreen, clearScreen };

package/src/screenshot.ts

@@ -1,19 +1,20 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 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_INTERVAL = 10;
-
 const describeWidgetState = (widget: Gtk.Widget): string =>
-    `realized=${widget.getRealized()} mapped=${widget.getMapped()} visible=${widget.getVisible()}`;
+    `realized=${String(widget.getRealized())} mapped=${String(widget.getMapped())} ` +
+    `visible=${String(widget.getVisible())}`;
 
 const captureSnapshot = (widget: Gtk.Widget, scale: number): ScreenshotResult => {
     const paintable = new Gtk.WidgetPaintable({ widget });
@@ -34,7 +35,6 @@ const captureSnapshot = (widget: Gtk.Widget, scale: number): ScreenshotResult =>
     }
 
     const display = widget.getDisplay();
-
     const renderer = new Gsk.CairoRenderer();
     renderer.realizeForDisplay(display);
 
@@ -65,11 +65,11 @@ const captureSnapshot = (widget: Gtk.Widget, scale: number): ScreenshotResult =>
  * @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> => {
+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 ${scale}`);
+        throw new Error(`Screenshot scale must be a positive number, got ${String(scale)}`);
     }
 
     return waitFor(() => captureSnapshot(widget, scale), {
@@ -78,6 +78,47 @@ export const screenshot = async (widget: Gtk.Widget, options?: ScreenshotOptions
     });
 };
 
+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();
 
@@ -86,42 +127,21 @@ const resolveWindow = (selector?: WindowSelector): Gtk.Window => {
     }
 
     if (selector === undefined) {
-        const [first] = windows;
-        if (!(first instanceof Gtk.Window)) {
-            throw new TypeError("First toplevel is not a Window");
-        }
-        return first;
+        return firstToplevelWindow(windows);
     }
 
     if (typeof selector === "number") {
-        const indexed = windows[selector];
-        if (!(indexed instanceof Gtk.Window)) {
-            throw new TypeError(`Window at index ${selector} not found`);
-        }
-        return indexed;
+        return windowAtIndex(windows, selector);
     }
 
-    const isRegex = selector instanceof RegExp;
-    const found = windows.find((w): w is Gtk.Window => {
-        if (!(w instanceof Gtk.Window)) return false;
-        const title = w.getTitle() ?? "";
-        return isRegex ? selector.test(title) : title.includes(selector);
-    });
-
-    if (!found) {
-        const pattern = isRegex ? selector.toString() : `"${selector}"`;
-        throw new Error(`No window found with title matching ${pattern}`);
-    }
-    return found;
+    return windowByTitle(windows, selector);
 };
 
 const saveScreenshotToTempFile = (result: ScreenshotResult): string => {
-    const dir = join(tmpdir(), "gtkx-screenshots");
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-    }
-    const filepath = join(dir, `${Date.now()}-screenshot.png`);
+    const dir = mkdtempSync(join(tmpdir(), "gtkx-screenshots-"));
+    const filepath = join(dir, "screenshot.png");
     writeFileSync(filepath, Buffer.from(result.data, "base64"));
+
     return filepath;
 };
 
@@ -130,7 +150,7 @@ const saveScreenshotToTempFile = (result: ScreenshotResult): string => {
  *
  * @param filepath Absolute path of the saved screenshot file.
  */
-export const logScreenshotPath = (filepath: string): void => {
+const logScreenshotPath = (filepath: string): void => {
     console.log(`Screenshot saved: file://${filepath}`);
 };
 
@@ -143,12 +163,15 @@ export const logScreenshotPath = (filepath: string): void => {
  * @param options Optional scale, timeout, and retry interval.
  * @returns The base64-encoded PNG data along with its mime type and dimensions.
  */
-export const captureAndSaveScreenshot = async (
+const captureAndSaveScreenshot = async (
     selector?: WindowSelector,
     options?: ScreenshotOptions,
 ): Promise<ScreenshotResult> => {
     const target = resolveWindow(selector);
     const result = await screenshot(target, options);
     logScreenshotPath(saveScreenshotToTempFile(result));
+
     return result;
 };
+
+export { screenshot, logScreenshotPath, captureAndSaveScreenshot };