@gtkx/testing 0.15.0 → 0.17.1

package/README.md

@@ -71,6 +71,7 @@ render(<App />, "com.example.counter");
 - **React 19** — Hooks, concurrent features, and the component model you know
 - **Native GTK4 widgets** — Real native controls, not web components in a webview
 - **Adwaita support** — Modern GNOME styling with Libadwaita components
+- **Declarative animations** — Framer Motion-like API using native Adwaita animations
 - **Hot Module Replacement** — Fast refresh during development
 - **TypeScript first** — Full type safety with auto-generated bindings
 - **CSS-in-JS styling** — Familiar styling patterns adapted for GTK

package/dist/config.d.ts

@@ -13,6 +13,11 @@ export type Config = {
      * Allows customizing how errors are constructed.
      */
     getElementError: (message: string, container: Container) => Error;
+    /**
+     * Default timeout in milliseconds for async utilities (waitFor, findBy* queries).
+     * @default 1000
+     */
+    asyncUtilTimeout: number;
 };
 /**
  * Returns the current testing library configuration.

package/dist/config.js

@@ -4,6 +4,7 @@ const defaultGetElementError = (message, _container) => {
 const defaultConfig = {
     showSuggestions: true,
     getElementError: defaultGetElementError,
+    asyncUtilTimeout: 1000,
 };
 let currentConfig = { ...defaultConfig };
 /**

package/dist/index.d.ts

@@ -5,13 +5,14 @@ export type { PrettyWidgetOptions } from "./pretty-widget.js";
 export { prettyWidget } from "./pretty-widget.js";
 export { findAllByLabelText, findAllByRole, findAllByTestId, findAllByText, findByLabelText, findByRole, findByTestId, findByText, queryAllByLabelText, queryAllByRole, queryAllByTestId, queryAllByText, queryByLabelText, queryByRole, queryByTestId, queryByText, } from "./queries.js";
 export { cleanup, render } from "./render.js";
+export { renderHook } from "./render-hook.js";
 export type { RoleInfo } from "./role-helpers.js";
 export { getRoles, logRoles, prettyRoles } from "./role-helpers.js";
 export { screen } from "./screen.js";
 export type { ScreenshotOptions } from "./screenshot.js";
 export { screenshot } from "./screenshot.js";
 export { tick } from "./timing.js";
-export type { BoundQueries, ByRoleOptions, NormalizerOptions, RenderOptions, RenderResult, ScreenshotResult, TextMatch, TextMatchFunction, TextMatchOptions, WaitForOptions, } from "./types.js";
+export type { BoundQueries, ByRoleOptions, NormalizerOptions, RenderHookOptions, RenderHookResult, RenderOptions, RenderResult, ScreenshotResult, TextMatch, TextMatchFunction, TextMatchOptions, WaitForOptions, } from "./types.js";
 export type { PointerInput, TabOptions } from "./user-event.js";
 export { userEvent } from "./user-event.js";
 export { waitFor, waitForElementToBeRemoved } from "./wait-for.js";

package/dist/index.js

@@ -3,6 +3,7 @@ export { fireEvent } from "./fire-event.js";
 export { prettyWidget } from "./pretty-widget.js";
 export { findAllByLabelText, findAllByRole, findAllByTestId, findAllByText, findByLabelText, findByRole, findByTestId, findByText, queryAllByLabelText, queryAllByRole, queryAllByTestId, queryAllByText, queryByLabelText, queryByRole, queryByTestId, queryByText, } from "./queries.js";
 export { cleanup, render } from "./render.js";
+export { renderHook } from "./render-hook.js";
 export { getRoles, logRoles, prettyRoles } from "./role-helpers.js";
 export { screen } from "./screen.js";
 export { screenshot } from "./screenshot.js";

package/dist/pretty-widget.js

@@ -1,4 +1,5 @@
 import { getNativeId } from "@gtkx/ffi";
+import * as Gtk from "@gtkx/ffi/gtk";
 import { formatRole } from "./role-helpers.js";
 import { isApplication } from "./traversal.js";
 import { getWidgetText } from "./widget-text.js";
@@ -105,7 +106,7 @@ const printWidget = (widget, colors, depth, includeIds) => {
 };
 const printContainer = (container, colors, includeIds) => {
     if (isApplication(container)) {
-        const windows = container.getWindows();
+        const windows = Gtk.Window.listToplevels();
         return windows.map((window) => printWidget(window, colors, 0, includeIds)).join("");
     }
     return printWidget(container, colors, 0, includeIds);

package/dist/queries.js

@@ -1,7 +1,7 @@
+import { getConfig } from "./config.js";
 import { buildMultipleFoundError, buildNotFoundError, buildTimeoutError } from "./error-builder.js";
 import { findAll } from "./traversal.js";
 import { getWidgetCheckedState, getWidgetExpandedState, getWidgetTestId, getWidgetText } from "./widget-text.js";
-const DEFAULT_TIMEOUT = 1000;
 const DEFAULT_INTERVAL = 50;
 const buildNormalizer = (options) => {
     if (options?.normalizer) {
@@ -60,7 +60,8 @@ const matchByRoleOptions = (widget, options) => {
     return true;
 };
 const waitFor = async (callback, options) => {
-    const { timeout = DEFAULT_TIMEOUT, interval = DEFAULT_INTERVAL, onTimeout } = options ?? {};
+    const config = getConfig();
+    const { timeout = config.asyncUtilTimeout, interval = DEFAULT_INTERVAL, onTimeout } = options ?? {};
     const startTime = Date.now();
     let lastError = null;
     while (Date.now() - startTime < timeout) {

package/dist/render-hook.d.ts

@@ -0,0 +1,40 @@
+import type { RenderHookOptions, RenderHookResult } from "./types.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 } }
+ *   );
+ *
+ *   expect(result.current).toBe(2);
+ *
+ *   await rerender({ multiplier: 3 });
+ *   expect(result.current).toBe(3);
+ * });
+ * ```
+ */
+export declare const renderHook: <Result, Props>(callback: (props: Props) => Result, options?: RenderHookOptions<Props>) => Promise<RenderHookResult<Result, Props>>;

package/dist/render-hook.js

@@ -0,0 +1,64 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRef } from "react";
+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 } }
+ *   );
+ *
+ *   expect(result.current).toBe(2);
+ *
+ *   await rerender({ multiplier: 3 });
+ *   expect(result.current).toBe(3);
+ * });
+ * ```
+ */
+export const renderHook = async (callback, options) => {
+    const resultRef = { current: undefined };
+    let currentProps = options?.initialProps;
+    const TestComponent = ({ props }) => {
+        const result = callback(props);
+        const ref = useRef(resultRef);
+        ref.current.current = result;
+        return null;
+    };
+    const renderResult = await render(_jsx(TestComponent, { props: currentProps }), {
+        wrapper: options?.wrapper ?? false,
+    });
+    return {
+        result: resultRef,
+        rerender: async (newProps) => {
+            if (newProps !== undefined) {
+                currentProps = newProps;
+            }
+            await renderResult.rerender(_jsx(TestComponent, { props: currentProps }));
+        },
+        unmount: renderResult.unmount,
+    };
+};

package/dist/render.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { discardAllBatches, start, stop } from "@gtkx/ffi";
+import { start, stop } from "@gtkx/ffi";
 import * as Gio from "@gtkx/ffi/gio";
 import { ApplicationContext, GtkApplicationWindow, reconciler } from "@gtkx/react";
 import { bindQueries } from "./bind-queries.js";
@@ -20,14 +20,13 @@ const update = async (instance, element, fiberRoot) => {
     }
 };
 const handleError = (error) => {
-    discardAllBatches();
     lastRenderError = error;
 };
 const ensureInitialized = () => {
     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, () => { }, () => { }, null);
+        container = instance.createContainer(application, 1, null, false, null, "", handleError, handleError, () => { }, () => { });
     }
     return { app: application, container };
 };

package/dist/screen.d.ts

@@ -1,4 +1,4 @@
-import type * as Gtk from "@gtkx/ffi/gtk";
+import * as Gtk from "@gtkx/ffi/gtk";
 import { type ScreenshotOptions } from "./screenshot.js";
 import type { ScreenshotResult } from "./types.js";
 /** @internal */

package/dist/screen.js

@@ -1,6 +1,7 @@
 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";
@@ -80,8 +81,7 @@ export const screen = {
      * ```
      */
     screenshot: async (selector, options) => {
-        const root = getRoot();
-        const windows = root.getWindows();
+        const windows = Gtk.Window.listToplevels();
         if (windows.length === 0) {
             throw new Error("No windows available for screenshot");
         }

package/dist/traversal.d.ts

@@ -1,4 +1,4 @@
-import type * as Gtk from "@gtkx/ffi/gtk";
+import * as Gtk from "@gtkx/ffi/gtk";
 export type Container = Gtk.Application | Gtk.Widget;
 export declare const isApplication: (container: Container) => container is Gtk.Application;
 export declare const traverse: (container: Container) => Generator<Gtk.Widget>;

package/dist/traversal.js

@@ -1,3 +1,4 @@
+import * as Gtk from "@gtkx/ffi/gtk";
 export const isApplication = (container) => "getWindows" in container && typeof container.getWindows === "function";
 const traverseWidgetTree = function* (root) {
     yield root;
@@ -7,15 +8,15 @@ const traverseWidgetTree = function* (root) {
         child = child.getNextSibling();
     }
 };
-const traverseApplication = function* (app) {
-    const windows = app.getWindows();
+const traverseWindows = function* () {
+    const windows = Gtk.Window.listToplevels();
     for (const window of windows) {
         yield* traverseWidgetTree(window);
     }
 };
 export const traverse = function* (container) {
     if (isApplication(container)) {
-        yield* traverseApplication(container);
+        yield* traverseWindows();
     }
     else {
         yield* traverseWidgetTree(container);

package/dist/types.d.ts

@@ -151,3 +151,36 @@ export type ScreenshotResult = {
     /** Height of the captured image in pixels */
     height: number;
 };
+/**
+ * Options for {@link renderHook}.
+ */
+export type RenderHookOptions<Props> = {
+    /**
+     * Initial props passed to the hook callback.
+     */
+    initialProps?: Props;
+    /**
+     * Wrapper component or boolean.
+     * - `false` (default): No wrapper
+     * - `true`: Wrap in GtkApplicationWindow
+     * - Component: Custom wrapper component
+     */
+    wrapper?: boolean | ComponentType<{
+        children: ReactNode;
+    }>;
+};
+/**
+ * Result returned by {@link renderHook}.
+ *
+ * Provides access to the hook result and utilities for re-rendering and cleanup.
+ */
+export type RenderHookResult<Result, Props> = {
+    /** Object containing the current hook return value */
+    result: {
+        current: Result;
+    };
+    /** Re-render the hook with optional new props */
+    rerender: (newProps?: Props) => Promise<void>;
+    /** Unmount the component containing the hook */
+    unmount: () => Promise<void>;
+};

package/dist/user-event.d.ts

@@ -46,13 +46,13 @@ export declare const userEvent: {
     /**
      * Double-clicks a widget.
      *
-     * Emits two consecutive clicked signals.
+     * Emits pressed/released signals with n_press=1, then n_press=2.
      */
     dblClick: (element: Gtk.Widget) => Promise<void>;
     /**
      * Triple-clicks a widget.
      *
-     * Emits three consecutive clicked signals. Useful for text selection.
+     * Emits pressed/released signals with n_press=1, 2, then 3. Useful for text selection.
      */
     tripleClick: (element: Gtk.Widget) => Promise<void>;
     /**

package/dist/user-event.js

@@ -1,4 +1,3 @@
-import { getNativeObject } from "@gtkx/ffi";
 import * as Gdk from "@gtkx/ffi/gdk";
 import { signalEmitv, signalLookup, typeFromName, Value } from "@gtkx/ffi/gobject";
 import * as Gtk from "@gtkx/ffi/gtk";
@@ -35,20 +34,31 @@ const click = async (element) => {
         await fireEvent(element, "clicked");
     }
 };
+const emitClickSequence = async (element, nPress) => {
+    const controller = getOrCreateController(element, Gtk.GestureClick);
+    for (let i = 1; i <= nPress; i++) {
+        const args = [
+            Value.newFromObject(controller),
+            Value.newFromInt(i),
+            Value.newFromDouble(0),
+            Value.newFromDouble(0),
+        ];
+        signalEmitv(args, getSignalId(controller, "pressed"), 0, null);
+        signalEmitv(args, getSignalId(controller, "released"), 0, null);
+    }
+    await tick();
+};
 const dblClick = async (element) => {
-    await fireEvent(element, "clicked");
-    await fireEvent(element, "clicked");
+    await emitClickSequence(element, 2);
 };
 const tripleClick = async (element) => {
-    await fireEvent(element, "clicked");
-    await fireEvent(element, "clicked");
-    await fireEvent(element, "clicked");
+    await emitClickSequence(element, 3);
 };
 const tab = async (element, options) => {
     const direction = options?.shift ? Gtk.DirectionType.TAB_BACKWARD : Gtk.DirectionType.TAB_FORWARD;
     const root = element.getRoot();
-    if (root) {
-        getNativeObject(root.handle).childFocus(direction);
+    if (root && root instanceof Gtk.Widget) {
+        root.childFocus(direction);
     }
     await tick();
 };
@@ -56,16 +66,15 @@ const type = async (element, text) => {
     if (!isEditable(element)) {
         throw new Error("Cannot type into element: expected editable widget (TEXT_BOX, SEARCH_BOX, or SPIN_BUTTON)");
     }
-    const editable = getNativeObject(element.handle, Gtk.Editable);
-    const currentText = editable.getText();
-    editable.setText(currentText + text);
+    const currentText = element.getText();
+    element.setText(currentText + text);
     await tick();
 };
 const clear = async (element) => {
     if (!isEditable(element)) {
         throw new Error("Cannot clear element: expected editable widget (TEXT_BOX, SEARCH_BOX, or SPIN_BUTTON)");
     }
-    getNativeObject(element.handle, Gtk.Editable)?.setText("");
+    element.setText("");
     await tick();
 };
 const SELECTABLE_ROLES = new Set([Gtk.AccessibleRole.COMBO_BOX, Gtk.AccessibleRole.LIST]);
@@ -238,17 +247,19 @@ const parseKeyboardInput = (input) => {
     }
     return actions;
 };
+let gdkModifierType = null;
 const keyboard = async (element, input) => {
+    gdkModifierType ??= typeFromName("GdkModifierType");
     const controller = getOrCreateController(element, Gtk.EventControllerKey);
     const actions = parseKeyboardInput(input);
     for (const action of actions) {
         const signalName = action.press ? "key-pressed" : "key-released";
-        const returnValue = Value.newFromBoolean(false);
+        const returnValue = action.press ? Value.newFromBoolean(false) : null;
         signalEmitv([
             Value.newFromObject(controller),
             Value.newFromUint(action.keyval),
             Value.newFromUint(0),
-            Value.newFromUint(0),
+            Value.newFromFlags(gdkModifierType, 0),
         ], getSignalId(controller, signalName), 0, returnValue);
         if (action.press && action.keyval === Gdk.KEY_Return && isEditable(element)) {
             await fireEvent(element, "activate");
@@ -314,13 +325,13 @@ export const userEvent = {
     /**
      * Double-clicks a widget.
      *
-     * Emits two consecutive clicked signals.
+     * Emits pressed/released signals with n_press=1, then n_press=2.
      */
     dblClick,
     /**
      * Triple-clicks a widget.
      *
-     * Emits three consecutive clicked signals. Useful for text selection.
+     * Emits pressed/released signals with n_press=1, 2, then 3. Useful for text selection.
      */
     tripleClick,
     /**

package/dist/wait-for.js

@@ -1,4 +1,4 @@
-const DEFAULT_TIMEOUT = 1000;
+import { getConfig } from "./config.js";
 const DEFAULT_INTERVAL = 50;
 /**
  * Waits for a callback to succeed.
@@ -20,7 +20,8 @@ const DEFAULT_INTERVAL = 50;
  * ```
  */
 export const waitFor = async (callback, options) => {
-    const { timeout = DEFAULT_TIMEOUT, interval = DEFAULT_INTERVAL, onTimeout } = options ?? {};
+    const config = getConfig();
+    const { timeout = config.asyncUtilTimeout, interval = DEFAULT_INTERVAL, onTimeout } = options ?? {};
     const startTime = Date.now();
     let lastError = null;
     while (Date.now() - startTime < timeout) {
@@ -73,7 +74,8 @@ const isElementRemoved = (element) => {
  * ```
  */
 export const waitForElementToBeRemoved = async (elementOrCallback, options) => {
-    const { timeout = DEFAULT_TIMEOUT, interval = DEFAULT_INTERVAL, onTimeout } = options ?? {};
+    const config = getConfig();
+    const { timeout = config.asyncUtilTimeout, interval = DEFAULT_INTERVAL, onTimeout } = options ?? {};
     const initialElement = getElement(elementOrCallback);
     if (initialElement === null || isElementRemoved(initialElement)) {
         throw new Error("Element already removed: waitForElementToBeRemoved requires the element to be present initially");

package/dist/widget-text.js

@@ -1,4 +1,4 @@
-import { getNativeObject } from "@gtkx/ffi";
+import { getNativeInterface } from "@gtkx/ffi";
 import * as Gtk from "@gtkx/ffi/gtk";
 const ROLES_WITH_INTERNAL_LABELS = new Set([
     Gtk.AccessibleRole.BUTTON,
@@ -77,7 +77,7 @@ export const getWidgetText = (widget) => {
         case Gtk.AccessibleRole.TEXT_BOX:
         case Gtk.AccessibleRole.SEARCH_BOX:
         case Gtk.AccessibleRole.SPIN_BUTTON:
-            return getNativeObject(widget.handle, Gtk.Editable).getText() ?? null;
+            return getNativeInterface(widget, Gtk.Editable)?.getText() ?? null;
         case Gtk.AccessibleRole.GROUP:
             return widget.getLabel?.() ?? null;
         case Gtk.AccessibleRole.WINDOW:

package/dist/widget.d.ts

@@ -1,2 +1,2 @@
 import * as Gtk from "@gtkx/ffi/gtk";
-export declare const isEditable: (widget: Gtk.Widget) => boolean;
+export declare const isEditable: (widget: unknown) => widget is Gtk.Editable;

package/dist/widget.js

@@ -5,5 +5,8 @@ const EDITABLE_ROLES = new Set([
     Gtk.AccessibleRole.SPIN_BUTTON,
 ]);
 export const isEditable = (widget) => {
+    if (!(widget instanceof Gtk.Widget)) {
+        return false;
+    }
     return EDITABLE_ROLES.has(widget.getAccessibleRole());
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/testing",
-  "version": "0.15.0",
+  "version": "0.17.1",
   "description": "Testing utilities for GTKX applications",
   "keywords": [
     "gtkx",
@@ -36,13 +36,13 @@
     "dist"
   ],
   "dependencies": {
-    "@gtkx/ffi": "0.15.0",
-    "@gtkx/react": "0.15.0"
+    "@gtkx/react": "0.17.1",
+    "@gtkx/ffi": "0.17.1"
   },
   "devDependencies": {
-    "@types/react-reconciler": "^0.32.3",
+    "@types/react-reconciler": "^0.33.0",
     "react-reconciler": "^0.33.0",
-    "@gtkx/vitest": "0.15.0"
+    "@gtkx/vitest": "0.17.1"
   },
   "scripts": {
     "build": "tsc -b && cp ../../README.md .",