@gtkx/testing 0.21.0 → 1.0.0-rc.2

package/src/register-test-hooks.ts

@@ -0,0 +1,19 @@
+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,71 +1,64 @@
-import { useRef } from "react";
-import { render } from "./render.js";
+import * as Gtk from "@gtkx/gi/gtk";
 import type { RenderHookOptions, RenderHookResult } from "./types.js";
+import { render } from "./render.js";
 
 /**
- * Renders a React hook for testing.
- *
- * 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 } }
- *   );
+ * Renders a test component that calls the given hook, exposing its latest
+ * return value along with rerender and unmount controls.
  *
- *   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.
+ */
+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>(
+function renderHook<Result, Props>(
+    callback: (props: Props) => Result,
+    options: RenderHookOptions<Props>,
+): Promise<RenderHookResult<Result, Props>>;
+
+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;
             }
+
             await renderResult.rerender(<TestComponent props={currentProps} />);
         },
         unmount: renderResult.unmount,
     };
-};
+}
+
+export { renderHook };

package/src/render.tsx

@@ -1,192 +1,229 @@
-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;
+import type { RootElement } from "@gtkx/react";
+import * as Gtk from "@gtkx/gi/gtk";
+import {
+    createReconcilerRoot,
+    isRootElement,
+    type ReconcilerRoot,
+    setReconcilerErrorHandler,
+} from "@gtkx/react/internal";
+import { type ErrorInfo, type ReactNode, StrictMode } from "react";
+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";
+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 { resetClipboard } from "./user-event/index.js";
+import { within } from "./within.js";
+
+type ActiveRender = {
+    root: ReconcilerRoot;
+    window: Gtk.Window | null;
+};
+
+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;
+
+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 (reconcilerErrors.lastError) {
+        const captured = reconcilerErrors.lastError;
+        reconcilerErrors.lastError = null;
+        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 => {
+    reconcilerErrors.lastError = 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 (reconcilerErrors.isHandlerInstalled) {
+        return;
+    }
 
-const findFirstWidget = (root: Container): Gtk.Widget | null => {
-    for (const widget of traverse(root)) {
-        if (isApplication(root)) return widget;
-        return root;
+    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 };
     }
-    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;
+    if (resolved.window) {
+        return resolved.window;
     }
-    const firstWidget = findFirstWidget(baseElement);
-    if (!firstWidget) {
-        throw new Error("render() produced no widgets: ensure the element renders visible content");
+
+    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 = (areAnimationsEnabled: boolean): void => {
+    const settings = Gtk.Settings.getDefault();
+
+    if (settings) {
+        settings.gtkEnableAnimations = areAnimationsEnabled;
     }
-    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.
+ * 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.
  *
- * @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
+ * @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;
-
-    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);
+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;
+    };
 
-    setScreenRoot(application);
+    await update(wrap(element), root);
+    resolved.window?.present();
+    await flushLayout(resolved.window);
+    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);
+const cleanup = async (): Promise<void> => {
+    await runCleanup();
 };
 
-process.on("SIGTERM", handleSignal);
-process.on("SIGINT", handleSignal);
+export { render, cleanup };