@gtkx/testing 0.9.3 → 0.10.0

package/dist/render.d.ts

@@ -1,19 +1,48 @@
 import type { ReactNode } from "react";
 import type { RenderOptions, RenderResult } from "./types.js";
 /**
- * Renders a React element into a GTK application for testing.
+ * 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 component
- * @returns Object containing query methods, container, and utility functions
+ * @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 declare const render: (element: ReactNode, options?: RenderOptions) => Promise<RenderResult>;
 /**
- * Cleans up the rendered component by unmounting it and destroying windows.
- * Should be called after each test to reset state.
+ * 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 declare const cleanup: () => Promise<void>;
-/**
- * Tears down the testing environment by cleaning up and stopping GTK.
- * Can be used as global teardown in your test runner configuration.
- */
-export declare const teardown: () => Promise<void>;

package/dist/render.js

@@ -1,13 +1,15 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { getApplication, getNativeObject, start, stop } from "@gtkx/ffi";
+import { discardAllBatches, getNativeObject, start } from "@gtkx/ffi";
 import * as Gtk from "@gtkx/ffi/gtk";
-import { ApplicationWindow, ROOT_NODE_CONTAINER, reconciler } from "@gtkx/react";
+import { ApplicationContext, GtkApplicationWindow, reconciler } from "@gtkx/react";
 import * as queries from "./queries.js";
 import { setScreenRoot } from "./screen.js";
 import { tick } from "./timing.js";
 import { hasLabel } from "./widget.js";
-const APP_ID = "com.gtkx.testing";
+let application = null;
 let container = null;
+let lastRenderError = null;
+const APP_ID = `com.gtkx.test${process.pid}`;
 const getWidgetLabel = (widget) => {
     if (!hasLabel(widget))
         return null;
@@ -35,18 +37,28 @@ const printWidgetTree = (root, indent = 0) => {
     return result;
 };
 const update = async (instance, element, fiberRoot) => {
+    lastRenderError = null;
     instance.updateContainer(element, fiberRoot, null, () => { });
     await tick();
+    if (lastRenderError) {
+        const error = lastRenderError;
+        lastRenderError = null;
+        throw error;
+    }
+};
+const handleError = (error) => {
+    discardAllBatches();
+    lastRenderError = error;
 };
 const ensureInitialized = () => {
-    const app = start(APP_ID);
+    application = start(APP_ID);
     if (!container) {
         const instance = reconciler.getInstance();
-        container = instance.createContainer(ROOT_NODE_CONTAINER, 0, null, false, null, "", (error) => console.error("Test reconciler error:", error), () => { }, () => { }, () => { }, null);
+        container = instance.createContainer(application, 0, null, false, null, "", handleError, handleError, () => { }, () => { }, null);
     }
-    return { app, container };
+    return { app: application, container };
 };
-const DefaultWrapper = ({ children }) => (_jsx(ApplicationWindow, { children: children }));
+const DefaultWrapper = ({ children }) => (_jsx(GtkApplicationWindow, { children: children }));
 const wrapElement = (element, wrapper = true) => {
     if (wrapper === false)
         return element;
@@ -56,16 +68,35 @@ const wrapElement = (element, wrapper = true) => {
     return _jsx(Wrapper, { children: element });
 };
 /**
- * Renders a React element into a GTK application for testing.
+ * 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 component
- * @returns Object containing query methods, container, and utility functions
+ * @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, options) => {
     const { app: application, container: fiberRoot } = ensureInitialized();
     const instance = reconciler.getInstance();
     const wrappedElement = wrapElement(element, options?.wrapper);
-    await update(instance, wrappedElement, fiberRoot);
+    const withContext = _jsx(ApplicationContext.Provider, { value: application, children: wrappedElement });
+    await update(instance, withContext, fiberRoot);
     setScreenRoot(application);
     return {
         container: application,
@@ -80,7 +111,8 @@ export const render = async (element, options) => {
         unmount: () => update(instance, null, fiberRoot),
         rerender: (newElement) => {
             const wrapped = wrapElement(newElement, options?.wrapper);
-            return update(instance, wrapped, fiberRoot);
+            const withCtx = _jsx(ApplicationContext.Provider, { value: application, children: wrapped });
+            return update(instance, withCtx, fiberRoot);
         },
         debug: () => {
             const activeWindow = application.getActiveWindow();
@@ -91,26 +123,30 @@ export const render = async (element, options) => {
     };
 };
 /**
- * Cleans up the rendered component by unmounting it and destroying windows.
- * Should be called after each test to reset state.
+ * 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 () => {
-    if (container) {
-        const app = getApplication();
+    if (container && application) {
         const instance = reconciler.getInstance();
         await update(instance, null, container);
-        for (const window of app.getWindows()) {
-            window.destroy();
-        }
     }
     container = null;
     setScreenRoot(null);
 };
-/**
- * Tears down the testing environment by cleaning up and stopping GTK.
- * Can be used as global teardown in your test runner configuration.
- */
-export const teardown = async () => {
-    await cleanup();
-    stop();
-};

package/dist/screen.d.ts

@@ -1,19 +1,44 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
 import type { ByRoleOptions, TextMatch, TextMatchOptions } from "./types.js";
+/** @internal */
 export declare const setScreenRoot: (root: Gtk.Application | null) => void;
 /**
- * Global screen object providing query methods bound to the current render root.
- * Similar to Testing Library's screen, it provides all query variants without
- * needing to destructure from render().
+ * 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 declare const screen: {
+    /** Find single element by accessible role */
     findByRole: (role: Gtk.AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget>;
+    /** Find single element by label/text content */
     findByLabelText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
+    /** Find single element by visible text */
     findByText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
+    /** Find single element by test ID (widget name) */
     findByTestId: (testId: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
+    /** Find all elements by accessible role */
     findAllByRole: (role: Gtk.AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget[]>;
+    /** Find all elements by label/text content */
     findAllByLabelText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
+    /** Find all elements by visible text */
     findAllByText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
+    /** Find all elements by test ID (widget name) */
     findAllByTestId: (testId: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
+    /** Print debug info to console */
     debug: () => void;
 };

package/dist/screen.js

@@ -1,28 +1,53 @@
 import * as queries from "./queries.js";
 let currentRoot = null;
+/** @internal */
 export const setScreenRoot = (root) => {
     currentRoot = root;
 };
 const getRoot = () => {
     if (!currentRoot) {
-        throw new Error("No render has been performed. Call render() before using screen queries.");
+        throw new Error("No render has been performed: call render() before using screen queries");
     }
     return currentRoot;
 };
 /**
- * Global screen object providing query methods bound to the current render root.
- * Similar to Testing Library's screen, it provides all query variants without
- * needing to destructure from render().
+ * 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 = {
+    /** Find single element by accessible role */
     findByRole: (role, options) => queries.findByRole(getRoot(), role, options),
+    /** Find single element by label/text content */
     findByLabelText: (text, options) => queries.findByLabelText(getRoot(), text, options),
+    /** Find single element by visible text */
     findByText: (text, options) => queries.findByText(getRoot(), text, options),
+    /** Find single element by test ID (widget name) */
     findByTestId: (testId, options) => queries.findByTestId(getRoot(), testId, options),
+    /** Find all elements by accessible role */
     findAllByRole: (role, options) => queries.findAllByRole(getRoot(), role, options),
+    /** Find all elements by label/text content */
     findAllByLabelText: (text, options) => queries.findAllByLabelText(getRoot(), text, options),
+    /** Find all elements by visible text */
     findAllByText: (text, options) => queries.findAllByText(getRoot(), text, options),
+    /** Find all elements by test ID (widget name) */
     findAllByTestId: (testId, options) => queries.findAllByTestId(getRoot(), testId, options),
+    /** Print debug info to console */
     debug: () => {
         console.log("Screen debug - root:", getRoot());
     },

package/dist/timing.d.ts

@@ -1 +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 declare const tick: () => Promise<void>;

package/dist/timing.js

@@ -1 +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 = () => new Promise((resolve) => setTimeout(resolve, 0));

package/dist/types.d.ts

@@ -1,117 +1,124 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
 import type { ComponentType, ReactNode } from "react";
 /**
- * A function that receives the text content and widget, returning true for a match.
- * Matches React Testing Library's function matcher signature.
+ * Custom function for matching text content.
+ *
+ * @param content - The normalized text content to match against
+ * @param widget - The widget being tested
+ * @returns `true` if the content matches
  */
 export type TextMatchFunction = (content: string, widget: Gtk.Widget) => boolean;
 /**
- * Flexible text matching: string for exact/partial, RegExp for patterns, or function for custom logic.
- * Matches React Testing Library's TextMatch type.
+ * Text matching pattern.
+ *
+ * Can be a string for exact/substring matching, a RegExp for pattern matching,
+ * or a custom function for advanced matching logic.
  */
 export type TextMatch = string | RegExp | TextMatchFunction;
 /**
- * Options for normalizing text before comparison.
+ * Options for text normalization before matching.
  */
 export type NormalizerOptions = {
-    /** Whether to trim whitespace from text. Defaults to true. */
+    /** Remove leading/trailing whitespace (default: true) */
     trim?: boolean;
-    /** Whether to collapse multiple whitespace into single spaces. Defaults to true. */
+    /** Replace multiple whitespace characters with single space (default: true) */
     collapseWhitespace?: boolean;
 };
 /**
- * Options for text matching in queries.
+ * Options for text-based queries.
  */
 export type TextMatchOptions = {
-    /** Whether to match the entire string exactly. Defaults to true. */
+    /** Require exact match vs substring match (default: true) */
     exact?: boolean;
-    /**
-     * Custom function to normalize text before comparison.
-     * Cannot be used with trim/collapseWhitespace options.
-     */
+    /** Custom text normalizer function */
     normalizer?: (text: string) => string;
-    /** Whether to trim whitespace from text. Defaults to true. */
+    /** Remove leading/trailing whitespace (default: true) */
     trim?: boolean;
-    /** Whether to collapse multiple whitespace into single spaces. Defaults to true. */
+    /** Replace multiple whitespace with single space (default: true) */
     collapseWhitespace?: boolean;
-    /** Maximum time in milliseconds to wait for a match. */
+    /** Timeout in milliseconds for async queries (default: 1000) */
     timeout?: number;
 };
 /**
- * Options for querying elements by their accessible role.
+ * Options for role-based queries.
+ *
+ * Extends text matching options with accessible state filters.
  */
 export type ByRoleOptions = TextMatchOptions & {
-    /** Filter by the element's accessible name. Supports string, RegExp, or function matcher. */
+    /** Filter by accessible name/label */
     name?: TextMatch;
-    /** Filter checkboxes/switches by checked state. */
+    /** Filter by checked state (checkboxes, radios, toggles) */
     checked?: boolean;
-    /** Filter toggle buttons by pressed state. */
+    /** Filter by pressed state */
     pressed?: boolean;
-    /** Filter selectable items by selected state. */
+    /** Filter by selected state */
     selected?: boolean;
-    /** Filter expandable elements by expanded state. */
+    /** Filter by expanded state (expanders) */
     expanded?: boolean;
-    /** Filter headings by their level (1-6). */
+    /** Filter by heading level */
     level?: number;
 };
 /**
- * Options for waitFor and related async utilities.
+ * Options for {@link waitFor} and {@link waitForElementToBeRemoved}.
  */
 export type WaitForOptions = {
-    /** Maximum time in milliseconds to wait. Defaults to 1000ms. */
+    /** Maximum time to wait in milliseconds (default: 1000) */
     timeout?: number;
-    /** Interval in milliseconds between condition checks. Defaults to 50ms. */
+    /** Polling interval in milliseconds (default: 50) */
     interval?: number;
-    /** Custom error handler called when timeout is reached. */
+    /** Custom error handler called on timeout */
     onTimeout?: (error: Error) => Error;
 };
 /**
- * Options for the render function.
+ * Options for {@link render}.
  */
 export type RenderOptions = {
     /**
-     * Controls how the rendered element is wrapped.
-     * - `true` (default): Wrap in ApplicationWindow
-     * - `false`: No wrapping, render element as-is
-     * - Component: Use a custom wrapper component
+     * Wrapper component or boolean.
+     * - `true` (default): Wrap in GtkApplicationWindow
+     * - `false`: No wrapper
+     * - Component: Custom wrapper component
      */
     wrapper?: boolean | ComponentType<{
         children: ReactNode;
     }>;
 };
 /**
- * Query methods bound to a specific container. All queries return promises
- * that resolve when a matching element is found or reject on timeout.
+ * Query methods bound to a container.
+ *
+ * @see {@link screen} for global queries
+ * @see {@link within} for scoped queries
  */
 export type BoundQueries = {
-    /** Find a single element by its accessible role. */
+    /** Find single element by accessible role */
     findByRole: (role: Gtk.AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget>;
-    /** Find a single element by its associated label text. */
+    /** Find single element by label/text content */
     findByLabelText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
-    /** Find a single element by its text content. */
+    /** Find single element by visible text */
     findByText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
-    /** Find a single element by its test ID. */
+    /** Find single element by test ID (widget name) */
     findByTestId: (testId: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
-    /** Find all elements matching an accessible role. */
+    /** Find all elements by accessible role */
     findAllByRole: (role: Gtk.AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget[]>;
-    /** Find all elements with matching label text. */
+    /** Find all elements by label/text content */
     findAllByLabelText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
-    /** Find all elements with matching text content. */
+    /** Find all elements by visible text */
     findAllByText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
-    /** Find all elements with matching test ID. */
+    /** Find all elements by test ID (widget name) */
     findAllByTestId: (testId: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
 };
 /**
- * The result returned by the render function. Includes query methods
- * and utilities for interacting with the rendered component.
+ * Result returned by {@link render}.
+ *
+ * Provides query methods and utilities for testing rendered components.
  */
 export type RenderResult = BoundQueries & {
-    /** The GTK Application instance containing the rendered component. */
+    /** The GTK Application container */
     container: Gtk.Application;
-    /** Unmount the rendered component and clean up resources. */
+    /** Unmount the rendered component */
     unmount: () => Promise<void>;
-    /** Re-render with a new element, preserving state where possible. */
+    /** Re-render with a new element */
     rerender: (element: ReactNode) => Promise<void>;
-    /** Print the current widget tree to the console for debugging. */
+    /** Print the widget tree to console for debugging */
     debug: () => void;
 };

package/dist/user-event.d.ts

@@ -1,23 +1,97 @@
 import * as Gtk from "@gtkx/ffi/gtk";
 /**
- * Options for the tab user event.
+ * Options for tab navigation.
  */
 export type TabOptions = {
-    /** If true, navigates backwards (Shift+Tab behavior). */
+    /** Navigate backwards (Shift+Tab) instead of forwards */
     shift?: boolean;
 };
 /**
- * Simulates user interactions with GTK widgets. Provides methods that mimic
- * real user behavior like clicking, typing, and clearing input fields.
+ * User interaction utilities for testing.
+ *
+ * Simulates user actions like clicking, typing, and selecting.
+ * All methods are async and wait for GTK event processing.
+ *
+ * @example
+ * ```tsx
+ * import { render, screen, userEvent } from "@gtkx/testing";
+ *
+ * test("form submission", async () => {
+ *   await render(<LoginForm />);
+ *
+ *   const input = await screen.findByRole(Gtk.AccessibleRole.TEXT_BOX);
+ *   await userEvent.type(input, "username");
+ *
+ *   const button = await screen.findByRole(Gtk.AccessibleRole.BUTTON);
+ *   await userEvent.click(button);
+ * });
+ * ```
  */
 export declare const userEvent: {
+    /**
+     * Clicks or toggles a widget.
+     *
+     * For toggleable widgets (checkboxes, switches, toggle buttons),
+     * toggles the active state. For buttons, emits clicked signal.
+     */
     click: (element: Gtk.Widget) => Promise<void>;
+    /**
+     * Double-clicks a widget.
+     *
+     * Emits two consecutive clicked signals.
+     */
     dblClick: (element: Gtk.Widget) => Promise<void>;
+    /**
+     * Triple-clicks a widget.
+     *
+     * Emits three consecutive clicked signals. Useful for text selection.
+     */
     tripleClick: (element: Gtk.Widget) => Promise<void>;
+    /**
+     * Activates a widget.
+     *
+     * Calls the widget's activate method.
+     */
     activate: (element: Gtk.Widget) => Promise<void>;
+    /**
+     * Simulates Tab key navigation.
+     *
+     * @param element - Starting element
+     * @param options - Use `shift: true` for backwards navigation
+     */
     tab: (element: Gtk.Widget, options?: TabOptions) => Promise<void>;
+    /**
+     * Types text into an editable widget.
+     *
+     * Appends text to the current content. Works with Entry, SearchEntry,
+     * and SpinButton widgets.
+     *
+     * @param element - The editable widget
+     * @param text - Text to type
+     */
     type: (element: Gtk.Widget, text: string) => Promise<void>;
+    /**
+     * Clears an editable widget's content.
+     *
+     * Sets the text to empty string.
+     */
     clear: (element: Gtk.Widget) => Promise<void>;
-    selectOptions: (element: Gtk.Widget, values: string | string[] | number | number[]) => Promise<void>;
+    /**
+     * Selects options in a dropdown or list.
+     *
+     * Works with DropDown, ComboBox, ListBox, ListView, GridView, and ColumnView.
+     *
+     * @param element - The selectable widget
+     * @param values - Index or array of indices to select
+     */
+    selectOptions: (element: Gtk.Widget, values: number | number[]) => Promise<void>;
+    /**
+     * Deselects options in a list.
+     *
+     * Works with ListBox and multi-selection list views.
+     *
+     * @param element - The selectable widget
+     * @param values - Index or array of indices to deselect
+     */
     deselectOptions: (element: Gtk.Widget, values: number | number[]) => Promise<void>;
 };