@gtkx/testing 0.1.45 → 0.1.46

package/dist/fire-event.d.ts

@@ -1,3 +1,17 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
 import type { Arg } from "@gtkx/native";
+/**
+ * Low-level utility to emit GTK signals on widgets. For common interactions
+ * like clicking or typing, use `userEvent` instead.
+ *
+ * @param element - The GTK widget to emit the signal on
+ * @param signalName - The name of the signal to emit
+ * @param args - Additional arguments to pass to the signal handlers
+ *
+ * @example
+ * fireEvent(button, "clicked")
+ *
+ * @example
+ * fireEvent(widget, "custom-signal", { type: { type: "int", size: 32 }, value: 42 })
+ */
 export declare const fireEvent: (element: Gtk.Widget, signalName: string, ...args: Arg[]) => void;

package/dist/fire-event.js

@@ -1,4 +1,18 @@
 import { call } from "@gtkx/native";
+/**
+ * Low-level utility to emit GTK signals on widgets. For common interactions
+ * like clicking or typing, use `userEvent` instead.
+ *
+ * @param element - The GTK widget to emit the signal on
+ * @param signalName - The name of the signal to emit
+ * @param args - Additional arguments to pass to the signal handlers
+ *
+ * @example
+ * fireEvent(button, "clicked")
+ *
+ * @example
+ * fireEvent(widget, "custom-signal", { type: { type: "int", size: 32 }, value: 42 })
+ */
 export const fireEvent = (element, signalName, ...args) => {
     call("libgobject-2.0.so.0", "g_signal_emit_by_name", [{ type: { type: "gobject" }, value: element.ptr }, { type: { type: "string" }, value: signalName }, ...args], { type: "undefined" });
 };

package/dist/queries.d.ts

@@ -2,12 +2,68 @@ import type * as Gtk from "@gtkx/ffi/gtk";
 import { AccessibleRole } from "@gtkx/ffi/gtk";
 import type { ByRoleOptions, TextMatchOptions } from "./types.js";
 type Container = Gtk.Application | Gtk.Widget;
+/**
+ * Waits for and finds a single widget matching the specified accessible role.
+ * @param container - The container to search within
+ * @param role - The accessible role to match
+ * @param options - Additional filtering options (name, checked, expanded)
+ * @returns Promise resolving to the matching widget
+ */
 export declare const findByRole: (container: Container, role: AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget>;
+/**
+ * Waits for and finds all widgets matching the specified accessible role.
+ * @param container - The container to search within
+ * @param role - The accessible role to match
+ * @param options - Additional filtering options (name, checked, expanded)
+ * @returns Promise resolving to array of matching widgets
+ */
 export declare const findAllByRole: (container: Container, role: AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget[]>;
+/**
+ * Waits for and finds a single widget matching the specified label text.
+ * @param container - The container to search within
+ * @param text - The text or pattern to match
+ * @param options - Text matching options (exact, normalizer)
+ * @returns Promise resolving to the matching widget
+ */
 export declare const findByLabelText: (container: Container, text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget>;
+/**
+ * Waits for and finds all widgets matching the specified label text.
+ * @param container - The container to search within
+ * @param text - The text or pattern to match
+ * @param options - Text matching options (exact, normalizer)
+ * @returns Promise resolving to array of matching widgets
+ */
 export declare const findAllByLabelText: (container: Container, text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
+/**
+ * Waits for and finds a single widget matching the specified text content.
+ * @param container - The container to search within
+ * @param text - The text or pattern to match
+ * @param options - Text matching options (exact, normalizer)
+ * @returns Promise resolving to the matching widget
+ */
 export declare const findByText: (container: Container, text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget>;
+/**
+ * Waits for and finds all widgets matching the specified text content.
+ * @param container - The container to search within
+ * @param text - The text or pattern to match
+ * @param options - Text matching options (exact, normalizer)
+ * @returns Promise resolving to array of matching widgets
+ */
 export declare const findAllByText: (container: Container, text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
+/**
+ * Waits for and finds a single widget matching the specified test ID.
+ * @param container - The container to search within
+ * @param testId - The test ID or pattern to match
+ * @param options - Text matching options (exact, normalizer)
+ * @returns Promise resolving to the matching widget
+ */
 export declare const findByTestId: (container: Container, testId: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget>;
+/**
+ * Waits for and finds all widgets matching the specified test ID.
+ * @param container - The container to search within
+ * @param testId - The test ID or pattern to match
+ * @param options - Text matching options (exact, normalizer)
+ * @returns Promise resolving to array of matching widgets
+ */
 export declare const findAllByTestId: (container: Container, testId: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
 export {};

package/dist/queries.js

@@ -196,11 +196,67 @@ const getByTestId = (container, testId, options) => {
     }
     return matches[0];
 };
+/**
+ * Waits for and finds a single widget matching the specified accessible role.
+ * @param container - The container to search within
+ * @param role - The accessible role to match
+ * @param options - Additional filtering options (name, checked, expanded)
+ * @returns Promise resolving to the matching widget
+ */
 export const findByRole = async (container, role, options) => waitFor(() => getByRole(container, role, options));
+/**
+ * Waits for and finds all widgets matching the specified accessible role.
+ * @param container - The container to search within
+ * @param role - The accessible role to match
+ * @param options - Additional filtering options (name, checked, expanded)
+ * @returns Promise resolving to array of matching widgets
+ */
 export const findAllByRole = async (container, role, options) => waitFor(() => getAllByRole(container, role, options));
+/**
+ * Waits for and finds a single widget matching the specified label text.
+ * @param container - The container to search within
+ * @param text - The text or pattern to match
+ * @param options - Text matching options (exact, normalizer)
+ * @returns Promise resolving to the matching widget
+ */
 export const findByLabelText = async (container, text, options) => waitFor(() => getByLabelText(container, text, options));
+/**
+ * Waits for and finds all widgets matching the specified label text.
+ * @param container - The container to search within
+ * @param text - The text or pattern to match
+ * @param options - Text matching options (exact, normalizer)
+ * @returns Promise resolving to array of matching widgets
+ */
 export const findAllByLabelText = async (container, text, options) => waitFor(() => getAllByLabelText(container, text, options));
+/**
+ * Waits for and finds a single widget matching the specified text content.
+ * @param container - The container to search within
+ * @param text - The text or pattern to match
+ * @param options - Text matching options (exact, normalizer)
+ * @returns Promise resolving to the matching widget
+ */
 export const findByText = async (container, text, options) => waitFor(() => getByText(container, text, options));
+/**
+ * Waits for and finds all widgets matching the specified text content.
+ * @param container - The container to search within
+ * @param text - The text or pattern to match
+ * @param options - Text matching options (exact, normalizer)
+ * @returns Promise resolving to array of matching widgets
+ */
 export const findAllByText = async (container, text, options) => waitFor(() => getAllByText(container, text, options));
+/**
+ * Waits for and finds a single widget matching the specified test ID.
+ * @param container - The container to search within
+ * @param testId - The test ID or pattern to match
+ * @param options - Text matching options (exact, normalizer)
+ * @returns Promise resolving to the matching widget
+ */
 export const findByTestId = async (container, testId, options) => waitFor(() => getByTestId(container, testId, options));
+/**
+ * Waits for and finds all widgets matching the specified test ID.
+ * @param container - The container to search within
+ * @param testId - The test ID or pattern to match
+ * @param options - Text matching options (exact, normalizer)
+ * @returns Promise resolving to array of matching widgets
+ */
 export const findAllByTestId = async (container, testId, options) => waitFor(() => getAllByTestId(container, testId, options));

package/dist/render.d.ts

@@ -1,5 +1,19 @@
 import type { ReactNode } from "react";
 import type { RenderOptions, RenderResult } from "./types.js";
+/**
+ * Renders a React element into a GTK application for testing.
+ * @param element - The React element to render
+ * @param options - Render options including wrapper component
+ * @returns Object containing query methods, container, and utility functions
+ */
 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.
+ */
 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

@@ -30,12 +30,20 @@ const ensureInitialized = () => {
     const app = 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(
+        // biome-ignore lint/suspicious/noExplicitAny: testing only
+        ROOT_NODE_CONTAINER, 0, null, false, null, "", (error) => console.error("Test reconciler error:", error), () => { }, () => { }, () => { }, null);
     }
     return { app, container };
 };
 const DefaultWrapper = ({ children }) => (_jsx(ApplicationWindow, { children: children }));
 const wrapElement = (element, Wrapper = DefaultWrapper) => (_jsx(Wrapper, { children: element }));
+/**
+ * Renders a React element into a GTK application for testing.
+ * @param element - The React element to render
+ * @param options - Render options including wrapper component
+ * @returns Object containing query methods, container, and utility functions
+ */
 export const render = async (element, options) => {
     const { app: application, container: fiberRoot } = ensureInitialized();
     const instance = reconciler.getInstance();
@@ -65,6 +73,10 @@ 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.
+ */
 export const cleanup = async () => {
     if (container) {
         const app = getCurrentApp();
@@ -77,6 +89,10 @@ export const cleanup = async () => {
     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,7 +1,16 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
 import type { AccessibleRole } from "@gtkx/ffi/gtk";
 import type { ByRoleOptions, TextMatchOptions } from "./types.js";
+/**
+ * Sets the root application for screen queries. Called internally by render().
+ * @param root - The GTK application to use as query root, or null to clear
+ */
 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().
+ */
 export declare const screen: {
     findByRole: (role: AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget>;
     findByLabelText: (text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget>;

package/dist/screen.js

@@ -1,5 +1,9 @@
 import * as queries from "./queries.js";
 let currentRoot = null;
+/**
+ * Sets the root application for screen queries. Called internally by render().
+ * @param root - The GTK application to use as query root, or null to clear
+ */
 export const setScreenRoot = (root) => {
     currentRoot = root;
 };
@@ -9,6 +13,11 @@ const getRoot = () => {
     }
     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().
+ */
 export const screen = {
     findByRole: (role, options) => queries.findByRole(getRoot(), role, options),
     findByLabelText: (text, options) => queries.findByLabelText(getRoot(), text, options),

package/dist/traversal.d.ts

@@ -1,4 +1,10 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
 type Container = Gtk.Application | Gtk.Widget;
+/**
+ * Traverses the widget tree and returns all widgets matching the predicate.
+ * @param container - The application or widget to search within
+ * @param predicate - Function that returns true for matching widgets
+ * @returns Array of widgets that match the predicate
+ */
 export declare const findAll: (container: Container, predicate: (node: Gtk.Widget) => boolean) => Gtk.Widget[];
 export {};

package/dist/traversal.js

@@ -21,6 +21,12 @@ const traverse = function* (container) {
         yield* traverseWidgetTree(container);
     }
 };
+/**
+ * Traverses the widget tree and returns all widgets matching the predicate.
+ * @param container - The application or widget to search within
+ * @param predicate - Function that returns true for matching widgets
+ * @returns Array of widgets that match the predicate
+ */
 export const findAll = (container, predicate) => {
     const results = [];
     for (const node of traverse(container)) {

package/dist/user-event.d.ts

@@ -1,14 +1,31 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
+/**
+ * Options for configuring user event behavior.
+ */
 export interface UserEventOptions {
+    /** Delay between events in milliseconds */
     delay?: number;
 }
+/**
+ * Instance returned by userEvent.setup() with bound options.
+ */
 export interface UserEventInstance {
+    /** Simulates a click on the element */
     click: (element: Gtk.Widget) => Promise<void>;
+    /** Simulates a double-click on the element */
     dblClick: (element: Gtk.Widget) => Promise<void>;
+    /** Activates the element (e.g., pressing Enter in an Entry) */
     activate: (element: Gtk.Widget) => Promise<void>;
+    /** Types text into an input element */
     type: (element: Gtk.Widget, text: string) => Promise<void>;
+    /** Clears the text content of an input element */
     clear: (element: Gtk.Widget) => Promise<void>;
 }
+/**
+ * Simulates user interactions with GTK widgets. Provides methods that mimic
+ * real user behavior like clicking, typing, and clearing input fields.
+ * Use userEvent.setup() to create an instance with custom options.
+ */
 export declare const userEvent: {
     setup: (options?: UserEventOptions) => UserEventInstance;
     click: (element: Gtk.Widget) => Promise<void>;

package/dist/user-event.js

@@ -34,6 +34,11 @@ const createUserEventInstance = (_options) => {
         },
     };
 };
+/**
+ * Simulates user interactions with GTK widgets. Provides methods that mimic
+ * real user behavior like clicking, typing, and clearing input fields.
+ * Use userEvent.setup() to create an instance with custom options.
+ */
 export const userEvent = {
     setup: (options) => createUserEventInstance(options),
     click: async (element) => {

package/dist/wait-for.d.ts

@@ -1,6 +1,20 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
 import type { WaitForOptions } from "./types.js";
+/**
+ * Waits for a callback to succeed without throwing an error.
+ * @param callback - Function to execute repeatedly until it succeeds
+ * @param options - Wait options (timeout, interval, onTimeout)
+ * @returns Promise resolving to the callback's return value
+ * @throws If the callback keeps failing after the timeout period
+ */
 export declare const waitFor: <T>(callback: () => T, options?: WaitForOptions) => Promise<T>;
 type ElementOrCallback = Gtk.Widget | (() => Gtk.Widget | null);
+/**
+ * Waits for an element to be removed from the widget tree.
+ * @param elementOrCallback - The element to watch or a callback returning the element
+ * @param options - Wait options (timeout, interval, onTimeout)
+ * @returns Promise resolving when the element is removed
+ * @throws If the element is already removed when called, or if timeout is reached
+ */
 export declare const waitForElementToBeRemoved: (elementOrCallback: ElementOrCallback, options?: WaitForOptions) => Promise<void>;
 export {};

package/dist/wait-for.js

@@ -1,5 +1,12 @@
 const DEFAULT_TIMEOUT = 1000;
 const DEFAULT_INTERVAL = 50;
+/**
+ * Waits for a callback to succeed without throwing an error.
+ * @param callback - Function to execute repeatedly until it succeeds
+ * @param options - Wait options (timeout, interval, onTimeout)
+ * @returns Promise resolving to the callback's return value
+ * @throws If the callback keeps failing after the timeout period
+ */
 export const waitFor = async (callback, options) => {
     const { timeout = DEFAULT_TIMEOUT, interval = DEFAULT_INTERVAL, onTimeout } = options ?? {};
     const startTime = Date.now();
@@ -36,6 +43,13 @@ const isElementRemoved = (element) => {
         return true;
     }
 };
+/**
+ * Waits for an element to be removed from the widget tree.
+ * @param elementOrCallback - The element to watch or a callback returning the element
+ * @param options - Wait options (timeout, interval, onTimeout)
+ * @returns Promise resolving when the element is removed
+ * @throws If the element is already removed when called, or if timeout is reached
+ */
 export const waitForElementToBeRemoved = async (elementOrCallback, options) => {
     const { timeout = DEFAULT_TIMEOUT, interval = DEFAULT_INTERVAL, onTimeout } = options ?? {};
     const initialElement = getElement(elementOrCallback);

package/dist/within.d.ts

@@ -1,3 +1,18 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
 import type { BoundQueries } from "./types.js";
+/**
+ * Scopes queries to a specific container element.
+ * Returns an object with all query methods bound to the given container,
+ * allowing you to search only within a subtree of the widget hierarchy.
+ *
+ * @param container - The widget to scope queries to
+ * @returns An object containing all query methods bound to the container
+ *
+ * @example
+ * ```tsx
+ * const dialog = await screen.findByRole(AccessibleRole.DIALOG);
+ * const { findByText } = within(dialog);
+ * const button = await findByText("Confirm");
+ * ```
+ */
 export declare const within: (container: Gtk.Widget) => BoundQueries;

package/dist/within.js

@@ -1,4 +1,19 @@
 import * as queries from "./queries.js";
+/**
+ * Scopes queries to a specific container element.
+ * Returns an object with all query methods bound to the given container,
+ * allowing you to search only within a subtree of the widget hierarchy.
+ *
+ * @param container - The widget to scope queries to
+ * @returns An object containing all query methods bound to the container
+ *
+ * @example
+ * ```tsx
+ * const dialog = await screen.findByRole(AccessibleRole.DIALOG);
+ * const { findByText } = within(dialog);
+ * const button = await findByText("Confirm");
+ * ```
+ */
 export const within = (container) => ({
     findByRole: (role, options) => queries.findByRole(container, role, options),
     findByLabelText: (text, options) => queries.findByLabelText(container, text, options),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/testing",
-  "version": "0.1.45",
+  "version": "0.1.46",
   "description": "Testing utilities for GTKX applications",
   "keywords": [
     "gtk",
@@ -32,9 +32,9 @@
     "dist"
   ],
   "dependencies": {
-    "@gtkx/native": "0.1.45",
-    "@gtkx/ffi": "0.1.45",
-    "@gtkx/react": "0.1.45"
+    "@gtkx/ffi": "0.1.46",
+    "@gtkx/native": "0.1.46",
+    "@gtkx/react": "0.1.46"
   },
   "scripts": {
     "build": "tsc -b && cp ../../README.md .",