@gtkx/testing 0.9.3 → 0.10.0

package/dist/user-event.js

@@ -59,7 +59,7 @@ const tab = async (element, options) => {
 };
 const type = async (element, text) => {
     if (!isEditable(element)) {
-        throw new Error("Cannot type into element: element is not editable (TEXT_BOX, SEARCH_BOX, or SPIN_BUTTON)");
+        throw new Error("Cannot type into element: expected editable widget (TEXT_BOX, SEARCH_BOX, or SPIN_BUTTON)");
     }
     const editable = getNativeObject(element.id, Gtk.Editable);
     if (!editable)
@@ -70,7 +70,7 @@ const type = async (element, text) => {
 };
 const clear = async (element) => {
     if (!isEditable(element)) {
-        throw new Error("Cannot clear element: element is not editable (TEXT_BOX, SEARCH_BOX, or SPIN_BUTTON)");
+        throw new Error("Cannot clear element: expected editable widget (TEXT_BOX, SEARCH_BOX, or SPIN_BUTTON)");
     }
     getNativeObject(element.id, Gtk.Editable)?.setText("");
     await tick();
@@ -82,34 +82,53 @@ const isSelectable = (widget) => {
         return false;
     return SELECTABLE_ROLES.has(accessible.getAccessibleRole());
 };
+const selectListViewItems = (selectionModel, positions, exclusive) => {
+    if (positions.length === 0) {
+        selectionModel.unselectRange(0, selectionModel.getNItems());
+        return;
+    }
+    if (exclusive && positions.length === 1) {
+        selectionModel.selectItem(positions[0], true);
+        return;
+    }
+    const nItems = selectionModel.getNItems();
+    const selected = new Gtk.Bitset();
+    const mask = Gtk.Bitset.newRange(0, nItems);
+    for (const pos of positions) {
+        selected.add(pos);
+    }
+    selectionModel.setSelection(selected, mask);
+};
+const isListView = (widget) => {
+    return widget instanceof Gtk.ListView || widget instanceof Gtk.GridView || widget instanceof Gtk.ColumnView;
+};
 const selectOptions = async (element, values) => {
+    const valueArray = Array.isArray(values) ? values : [values];
+    if (isListView(element)) {
+        const selectionModel = element.getModel();
+        const isMultiSelection = selectionModel instanceof Gtk.MultiSelection;
+        selectListViewItems(selectionModel, valueArray, !isMultiSelection);
+        await tick();
+        return;
+    }
     if (!isSelectable(element)) {
-        throw new Error("Cannot select options: element is not a selectable widget (COMBO_BOX or LIST)");
+        throw new Error("Cannot select options: expected selectable widget (COMBO_BOX or LIST)");
     }
     const role = getNativeObject(element.id, Gtk.Accessible)?.getAccessibleRole();
-    const valueArray = Array.isArray(values) ? values : [values];
     if (role === Gtk.AccessibleRole.COMBO_BOX) {
-        if (valueArray.length > 1) {
-            throw new Error("Cannot select multiple options on a ComboBox/DropDown");
-        }
-        const value = valueArray[0];
-        if (typeof value !== "number") {
-            throw new Error("ComboBox/DropDown selection requires a numeric index");
+        if (Array.isArray(values) && values.length > 1) {
+            throw new Error("Cannot select multiple options: ComboBox only supports single selection");
         }
-        const isDropDown = element.constructor.name === "DropDown";
-        if (isDropDown) {
-            element.setSelected(value);
+        if (element instanceof Gtk.DropDown) {
+            element.setSelected(valueArray[0]);
         }
         else {
-            element.setActive(value);
+            element.setActive(valueArray[0]);
         }
     }
     else if (role === Gtk.AccessibleRole.LIST) {
         const listBox = element;
         for (const value of valueArray) {
-            if (typeof value !== "number") {
-                throw new Error("ListBox selection requires numeric indices");
-            }
             const row = listBox.getRowAtIndex(value);
             if (row) {
                 listBox.selectRow(row);
@@ -120,12 +139,20 @@ const selectOptions = async (element, values) => {
     await tick();
 };
 const deselectOptions = async (element, values) => {
+    const valueArray = Array.isArray(values) ? values : [values];
+    if (isListView(element)) {
+        const selectionModel = element.getModel();
+        for (const pos of valueArray) {
+            selectionModel.unselectItem(pos);
+        }
+        await tick();
+        return;
+    }
     const role = getNativeObject(element.id, Gtk.Accessible)?.getAccessibleRole();
     if (role !== Gtk.AccessibleRole.LIST) {
         throw new Error("Cannot deselect options: only ListBox supports deselection");
     }
     const listBox = element;
-    const valueArray = Array.isArray(values) ? values : [values];
     for (const value of valueArray) {
         const row = listBox.getRowAtIndex(value);
         if (row) {
@@ -135,17 +162,91 @@ const deselectOptions = async (element, values) => {
     await tick();
 };
 /**
- * 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 const userEvent = {
+    /**
+     * Clicks or toggles a widget.
+     *
+     * For toggleable widgets (checkboxes, switches, toggle buttons),
+     * toggles the active state. For buttons, emits clicked signal.
+     */
     click,
+    /**
+     * Double-clicks a widget.
+     *
+     * Emits two consecutive clicked signals.
+     */
     dblClick,
+    /**
+     * Triple-clicks a widget.
+     *
+     * Emits three consecutive clicked signals. Useful for text selection.
+     */
     tripleClick,
+    /**
+     * Activates a widget.
+     *
+     * Calls the widget's activate method.
+     */
     activate,
+    /**
+     * Simulates Tab key navigation.
+     *
+     * @param element - Starting element
+     * @param options - Use `shift: true` for backwards navigation
+     */
     tab,
+    /**
+     * 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,
+    /**
+     * Clears an editable widget's content.
+     *
+     * Sets the text to empty string.
+     */
     clear,
+    /**
+     * 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,
+    /**
+     * 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,
 };

package/dist/wait-for.d.ts

@@ -1,20 +1,42 @@
 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)
+ * Waits for a callback to succeed.
+ *
+ * Repeatedly calls the callback until it returns without throwing,
+ * or until the timeout is reached.
+ *
+ * @param callback - Function to execute repeatedly
+ * @param options - Timeout and interval configuration
  * @returns Promise resolving to the callback's return value
- * @throws If the callback keeps failing after the timeout period
+ *
+ * @example
+ * ```tsx
+ * import { waitFor } from "@gtkx/testing";
+ *
+ * await waitFor(() => {
+ *   expect(counter.value).toBe(5);
+ * }, { timeout: 2000 });
+ * ```
  */
 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
+ *
+ * Polls until the element no longer has a parent or no longer exists.
+ *
+ * @param elementOrCallback - Element or function returning element to watch
+ * @param options - Timeout and interval configuration
+ *
+ * @example
+ * ```tsx
+ * import { waitForElementToBeRemoved } from "@gtkx/testing";
+ *
+ * const loader = await screen.findByRole(Gtk.AccessibleRole.PROGRESS_BAR);
+ * await waitForElementToBeRemoved(loader);
+ * // Loader is now gone
+ * ```
  */
 export declare const waitForElementToBeRemoved: (elementOrCallback: ElementOrCallback, options?: WaitForOptions) => Promise<void>;
 export {};

package/dist/wait-for.js

@@ -1,11 +1,23 @@
 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)
+ * Waits for a callback to succeed.
+ *
+ * Repeatedly calls the callback until it returns without throwing,
+ * or until the timeout is reached.
+ *
+ * @param callback - Function to execute repeatedly
+ * @param options - Timeout and interval configuration
  * @returns Promise resolving to the callback's return value
- * @throws If the callback keeps failing after the timeout period
+ *
+ * @example
+ * ```tsx
+ * import { waitFor } from "@gtkx/testing";
+ *
+ * await waitFor(() => {
+ *   expect(counter.value).toBe(5);
+ * }, { timeout: 2000 });
+ * ```
  */
 export const waitFor = async (callback, options) => {
     const { timeout = DEFAULT_TIMEOUT, interval = DEFAULT_INTERVAL, onTimeout } = options ?? {};
@@ -45,17 +57,26 @@ const isElementRemoved = (element) => {
 };
 /**
  * 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
+ *
+ * Polls until the element no longer has a parent or no longer exists.
+ *
+ * @param elementOrCallback - Element or function returning element to watch
+ * @param options - Timeout and interval configuration
+ *
+ * @example
+ * ```tsx
+ * import { waitForElementToBeRemoved } from "@gtkx/testing";
+ *
+ * const loader = await screen.findByRole(Gtk.AccessibleRole.PROGRESS_BAR);
+ * await waitForElementToBeRemoved(loader);
+ * // Loader is now gone
+ * ```
  */
 export const waitForElementToBeRemoved = async (elementOrCallback, options) => {
     const { timeout = DEFAULT_TIMEOUT, interval = DEFAULT_INTERVAL, onTimeout } = options ?? {};
     const initialElement = getElement(elementOrCallback);
     if (initialElement === null) {
-        throw new Error("The element(s) given to waitForElementToBeRemoved are already removed. " +
-            "waitForElementToBeRemoved requires that the element is present before waiting for removal.");
+        throw new Error("Elements already removed: waitForElementToBeRemoved requires elements to be present initially");
     }
     const startTime = Date.now();
     while (Date.now() - startTime < timeout) {

package/dist/within.d.ts

@@ -1,18 +1,29 @@
 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.
+ * Creates scoped query methods for a container widget.
+ *
+ * Use this to query within a specific section of your UI rather than
+ * the entire application.
  *
  * @param container - The widget to scope queries to
- * @returns An object containing all query methods bound to the container
+ * @returns Object with query methods bound to the container
  *
  * @example
  * ```tsx
- * const dialog = await screen.findByRole(AccessibleRole.DIALOG);
- * const { findByText } = within(dialog);
- * const button = await findByText("Confirm");
+ * import { render, within } from "@gtkx/testing";
+ *
+ * test("scoped queries", async () => {
+ *   await render(<MyPage />);
+ *
+ *   const sidebar = await screen.findByRole(Gtk.AccessibleRole.NAVIGATION);
+ *   const sidebarQueries = within(sidebar);
+ *
+ *   // Only searches within the sidebar
+ *   const navButton = await sidebarQueries.findByRole(Gtk.AccessibleRole.BUTTON);
+ * });
  * ```
+ *
+ * @see {@link screen} for global queries
  */
 export declare const within: (container: Gtk.Widget) => BoundQueries;

package/dist/within.js

@@ -1,18 +1,29 @@
 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.
+ * Creates scoped query methods for a container widget.
+ *
+ * Use this to query within a specific section of your UI rather than
+ * the entire application.
  *
  * @param container - The widget to scope queries to
- * @returns An object containing all query methods bound to the container
+ * @returns Object with query methods bound to the container
  *
  * @example
  * ```tsx
- * const dialog = await screen.findByRole(AccessibleRole.DIALOG);
- * const { findByText } = within(dialog);
- * const button = await findByText("Confirm");
+ * import { render, within } from "@gtkx/testing";
+ *
+ * test("scoped queries", async () => {
+ *   await render(<MyPage />);
+ *
+ *   const sidebar = await screen.findByRole(Gtk.AccessibleRole.NAVIGATION);
+ *   const sidebarQueries = within(sidebar);
+ *
+ *   // Only searches within the sidebar
+ *   const navButton = await sidebarQueries.findByRole(Gtk.AccessibleRole.BUTTON);
+ * });
  * ```
+ *
+ * @see {@link screen} for global queries
  */
 export const within = (container) => ({
     findByRole: (role, options) => queries.findByRole(container, role, options),

package/package.json

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