@gtkx/testing 0.20.0 → 1.0.0-rc.1

package/src/register-test-hooks.ts

@@ -0,0 +1,16 @@
+import { quit } from "@gtkx/runtime";
+import { registerMatchers } from "./matchers.js";
+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);
+};
+
+const registerTestRuntimeHooks = (): void => {
+    callRunnerHook("afterEach", cleanup);
+    callRunnerHook("afterAll", quit);
+    registerMatchers();
+};
+
+registerTestRuntimeHooks();

package/src/render-hook.tsx

@@ -1,65 +1,52 @@
-import { useRef } from "react";
+import * as Gtk from "@gtkx/gi/gtk";
 import { render } from "./render.js";
 import type { RenderHookOptions, RenderHookResult } from "./types.js";
 
 /**
- * Renders a React hook for testing.
+ * Renders a test component that calls the given hook, exposing its latest
+ * return value along with rerender and unmount controls.
  *
- * Creates a test component that executes the hook and provides utilities
- * for accessing the result, re-rendering with new props, and cleanup.
- *
- * @param callback - Function that calls the hook and returns its result
- * @param options - Render options including initialProps and wrapper
- * @returns A promise resolving to the hook result and utilities
- *
- * @example
- * ```tsx
- * import { renderHook } from "@gtkx/testing";
- * import { useState } from "react";
- *
- * test("useState hook", async () => {
- *   const { result } = await renderHook(() => useState(0));
- *   expect(result.current[0]).toBe(0);
- * });
- * ```
- *
- * @example
- * ```tsx
- * import { renderHook } from "@gtkx/testing";
- *
- * test("hook with props", async () => {
- *   const { result, rerender } = await renderHook(
- *     ({ multiplier }) => useMultiplier(multiplier),
- *     { initialProps: { multiplier: 2 } }
- *   );
- *
- *   expect(result.current).toBe(2);
+ * @param callback The hook to run, invoked with the current props.
+ * @param options Optional initial props and wrapper component.
+ * @returns A result whose `result.current` holds the hook's latest value.
+ */
+export 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.
  *
- *   await rerender({ multiplier: 3 });
- *   expect(result.current).toBe(3);
- * });
- * ```
+ * @param callback The hook to run, invoked with the current props.
+ * @param options Initial props and optional wrapper component.
+ * @returns A result whose `result.current` holds the hook's latest value.
  */
-export const renderHook = async <Result, Props>(
+export function renderHook<Result, Props>(
+    callback: (props: Props) => Result,
+    options: RenderHookOptions<Props>,
+): Promise<RenderHookResult<Result, Props>>;
+export async function renderHook<Result, Props>(
     callback: (props: Props) => Result,
     options?: RenderHookOptions<Props>,
-): Promise<RenderHookResult<Result, Props>> => {
-    const resultRef = { current: undefined as Result };
-    let currentProps = options?.initialProps as Props;
+): Promise<RenderHookResult<Result, Props>> {
+    const initialProps = (options as { initialProps?: Props } | undefined)?.initialProps as Props;
+    const resultRef: { current: Result | undefined } = { current: undefined };
+    let currentProps: Props = initialProps;
 
     const TestComponent = ({ props }: { props: Props }): null => {
         const result = callback(props);
-        const ref = useRef(resultRef);
-        ref.current.current = result;
+        resultRef.current = result;
         return null;
     };
 
     const renderResult = await render(<TestComponent props={currentProps} />, {
-        wrapper: options?.wrapper ?? true,
+        container: new Gtk.Box(),
+        wrapper: options?.wrapper,
     });
 
     return {
-        result: resultRef,
+        result: resultRef as { current: Result },
         rerender: async (newProps?: Props) => {
             if (newProps !== undefined) {
                 currentProps = newProps;
@@ -68,4 +55,4 @@ export const renderHook = async <Result, Props>(
         },
         unmount: renderResult.unmount,
     };
-};
+}

package/src/render.tsx

@@ -1,192 +1,204 @@
-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;
+import * as Gtk from "@gtkx/gi/gtk";
+import type { RootElement } from "@gtkx/react";
+import {
+    createReconcilerRoot,
+    isRootElement,
+    type ReconcilerRoot,
+    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 { addToCleanupQueue, runCleanup } from "./cleanup-registry.js";
+import { scheduleAfterLayout } from "./frame-sync.js";
+import { logWidget, type PrettyWidgetOptions } from "./pretty-widget.js";
+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 ReconcilerInstance = ReturnType<typeof reconciler.getInstance>;
+type ActiveRender = {
+    root: ReconcilerRoot;
+    window: Gtk.Window | null;
+};
 
-const update = async (
-    instance: ReconcilerInstance,
-    element: ReactNode,
-    fiberRoot: Reconciler.FiberRoot,
-): Promise<void> => {
-    lastRenderError = null;
-    instance.updateContainer(element, fiberRoot, null, () => {});
-    await tick();
+const activeRenders = new Set<ActiveRender>();
+
+const HARNESS_WINDOW_WIDTH = 800;
+const HARNESS_WINDOW_HEIGHT = 600;
+
+const flushLayout = (window: Gtk.Window | null): Promise<void> =>
+    new Promise((resolve) => {
+        scheduleAfterLayout(window, resolve);
+    });
+
+const update = async (element: ReactNode, root: ReconcilerRoot): Promise<void> => {
+    await runInAct(() => {
+        root.update(element);
+    });
 
     if (lastRenderError) {
-        const error = lastRenderError;
+        const captured = lastRenderError;
         lastRenderError = null;
-        throw error;
+        throw captured;
     }
 };
 
-const handleError = (error: Error): void => {
-    lastRenderError = error;
+const disposeActiveRender = async (active: ActiveRender): Promise<void> => {
+    if (!activeRenders.delete(active)) return;
+    await active.root.unmount(async (root) => {
+        await update(null, root);
+        active.window?.destroy();
+    });
 };
 
-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,
-            () => {},
-            () => {},
-        );
+const disposeAllActiveRenders = async (): Promise<void> => {
+    for (const active of [...activeRenders]) {
+        await disposeActiveRender(active);
     }
+};
 
-    return { app: application, container };
+const handleError = (error: unknown): void => {
+    lastRenderError = error instanceof Error ? error : new Error(String(error));
 };
 
-const DefaultWrapper: WrapperComponent = ({ children, ref }) => (
-    <GtkApplicationWindow ref={ref as Ref<Gtk.ApplicationWindow>} defaultWidth={800} defaultHeight={600}>
-        {children}
-    </GtkApplicationWindow>
-);
+const installErrorHandler = (): void => {
+    if (errorHandlerInstalled) return;
+    setReconcilerErrorHandler(handleError);
+    errorHandlerInstalled = true;
+};
 
-const findFirstWidget = (root: Container): Gtk.Widget | null => {
-    for (const widget of traverse(root)) {
-        if (isApplication(root)) return widget;
-        return root;
+type ResolvedContainer = {
+    containerInfo: Gtk.Widget | RootElement;
+    window: Gtk.Window | null;
+};
+
+const resolveContainer = (container: RenderOptions["container"]): ResolvedContainer => {
+    if (isRootElement(container)) {
+        return { containerInfo: container, window: null };
+    }
+    if (container instanceof Gtk.Widget) {
+        return { containerInfo: container, window: null };
     }
-    return 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 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 firstToplevelWidget = (baseElement: Container): Gtk.Widget => {
+    if (baseElement instanceof Gtk.Widget) return baseElement;
+    const [first] = traverse(baseElement);
+    if (first) return first;
+    throw new Error("render() produced no widgets: ensure the element renders visible content");
 };
 
-const resolveContainer = (
-    wrapper: RenderOptions["wrapper"],
-    wrapperRef: React.RefObject<Gtk.Widget | null>,
+const resolveResultContainer = (
+    resolved: ResolvedContainer,
+    container: RenderOptions["container"],
     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.");
+    if (resolved.window) return resolved.window;
+    if (container instanceof Gtk.Widget) return container;
+    return firstToplevelWidget(baseElement);
+};
+
+const renderErrorHandlers = <Q extends QueryMap>(options: RenderOptions<Q> | undefined) => ({
+    onUncaughtError: handleError,
+    onCaughtError: (error: unknown, errorInfo: ErrorInfo): void => {
+        handleError(error);
+        options?.onCaughtError?.(error, errorInfo);
+    },
+    onRecoverableError: (error: unknown, errorInfo: ErrorInfo): void => {
+        options?.onRecoverableError?.(error, errorInfo);
+    },
+});
+
+const applyEnableAnimations = (enabled: boolean): void => {
+    const settings = Gtk.Settings.getDefault();
+    if (settings) {
+        settings.gtkEnableAnimations = enabled;
     }
-    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
+ * Renders a React element into a GTK4 widget tree and returns queries
+ * scoped to it along with controls for rerendering and unmounting. When no
+ * container is supplied, a harness window is created and presented.
  *
- * @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
+ * @param element The React element to render.
+ * @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 (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;
+export 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;
+    };
 
-    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);
+    await update(wrap(element), root);
+    resolved.window?.present();
+    await flushLayout(resolved.window);
 
-    setScreenRoot(application);
+    const container = resolveResultContainer(resolved, options?.container, baseElement);
 
-    return {
-        container: resolveContainer(wrapper, wrapperRef, baseElement),
+    const result: RenderResult<Q> = {
+        ...within(baseElement, options?.queries),
+        container,
         baseElement,
-        ...bindQueries(baseElement),
-        unmount: () => update(instance, null, fiberRoot),
+        unmount: async () => {
+            await disposeActiveRender(active);
+        },
         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);
+            await update(wrap(newElement), root);
+            await flushLayout(resolved.window);
+        },
+        debug: (element: Container | Container[] = baseElement, debugOptions?: PrettyWidgetOptions) => {
+            logWidget(element, debugOptions);
         },
-        debug: () => {
-            console.log(prettyWidget(application));
+        logRoles: () => {
+            logRoles(baseElement);
         },
+        screenshot: (selector?: WindowSelector, screenshotOptions?: ScreenshotOptions) =>
+            captureAndSaveScreenshot(selector, screenshotOptions),
     };
+
+    setScreen(result);
+
+    return result;
 };
 
 /**
- * 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 />);
- * // ...
- * });
- * ```
+ * 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> => {
-    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);
+    await runCleanup();
 };
-
-process.on("SIGTERM", handleSignal);
-process.on("SIGINT", handleSignal);

package/src/role-helpers.ts

@@ -1,64 +1,59 @@
-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 enumNamesByValue = (enumObject: Record<string, string | number>): Map<number, string> =>
+    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);
 
 /**
- * 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];
+export const formatRole = (role: Gtk.AccessibleRole): string => {
+    const name = ROLE_NAMES_BY_VALUE.get(role);
     if (!name) return String(role);
     return name.toLowerCase();
 };
 
+export 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]}`;
+    }
+    const head = names.slice(0, -1);
+    const last = names[names.length - 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[]>();
+export const getRoles = (container: Container): Map<string, Gtk.Widget[]> => {
+    const roles = new Map<string, Gtk.Widget[]>();
 
     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,16 +62,16 @@ 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 roles = getRoles(container);
@@ -87,12 +82,12 @@ export const prettyRoles = (container: Container): string => {
 
     const lines: string[] = [];
 
-    const sortedRoles = [...roles.entries()].sort(([a], [b]) => a.localeCompare(b));
+    const sortedRoles = sortStringsBy([...roles.entries()], ([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,25 +96,10 @@ 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.
- *
- * @param container - The container to log roles for
- *
- * @example
- * ```tsx
- * import { render, logRoles } from "@gtkx/testing";
+ * Prints the accessible roles in a container's tree to the console using
+ * {@link prettyRoles}.
  *
- * 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 => {
     console.log(prettyRoles(container));