@gtkx/testing 0.3.4 → 0.4.0

package/README.md

@@ -41,7 +41,14 @@ Edit your code and see changes instantly—no restart needed.
 ### Example
 
 ```tsx
-import { render, ApplicationWindow, Box, Button, Label, quit } from "@gtkx/react";
+import {
+  render,
+  ApplicationWindow,
+  Box,
+  Button,
+  Label,
+  quit,
+} from "@gtkx/react";
 import { Orientation } from "@gtkx/ffi/gtk";
 import { useState } from "react";
 
@@ -74,7 +81,7 @@ const primary = css`
   color: white;
 `;
 
-<Button label="Click me" cssClasses={[primary]} />
+<Button label="Click me" cssClasses={[primary]} />;
 ```
 
 GTK also provides built-in classes like `suggested-action`, `destructive-action`, `card`, and `heading`.
@@ -90,7 +97,9 @@ afterEach(() => cleanup());
 test("increments count", async () => {
   await render(<App />);
 
-  const button = await screen.findByRole(AccessibleRole.BUTTON, { name: "Increment" });
+  const button = await screen.findByRole(AccessibleRole.BUTTON, {
+    name: "Increment",
+  });
   await userEvent.click(button);
 
   await screen.findByText("Count: 1");
@@ -103,10 +112,10 @@ User events: `click`, `dblClick`, `type`, `clear`, `tab`, `selectOptions`
 
 ## Examples
 
-| Example | Description |
-| ------- | ----------- |
-| [gtk4-demo](examples/gtk4-demo) | Widget showcase |
-| [todo](examples/todo) | Todo app with tests |
+| Example                         | Description         |
+| ------------------------------- | ------------------- |
+| [gtk4-demo](examples/gtk4-demo) | Widget showcase     |
+| [todo](examples/todo)           | Todo app with tests |
 
 ```bash
 cd examples/gtk4-demo && pnpm dev
@@ -114,15 +123,15 @@ cd examples/gtk4-demo && pnpm dev
 
 ## Packages
 
-| Package | Description |
-| ------- | ----------- |
-| [@gtkx/cli](packages/cli) | CLI with HMR dev server |
-| [@gtkx/react](packages/react) | React reconciler and JSX components |
-| [@gtkx/ffi](packages/ffi) | TypeScript bindings for GTK4/GLib/GIO |
-| [@gtkx/native](packages/native) | Rust native module (libffi bridge) |
-| [@gtkx/css](packages/css) | CSS-in-JS styling |
-| [@gtkx/testing](packages/testing) | Testing utilities |
-| [@gtkx/gir](packages/gir) | GObject Introspection parser |
+| Package                           | Description                           |
+| --------------------------------- | ------------------------------------- |
+| [@gtkx/cli](packages/cli)         | CLI with HMR dev server               |
+| [@gtkx/react](packages/react)     | React reconciler and JSX components   |
+| [@gtkx/ffi](packages/ffi)         | TypeScript bindings for GTK4/GLib/GIO |
+| [@gtkx/native](packages/native)   | Rust native module (libffi bridge)    |
+| [@gtkx/css](packages/css)         | CSS-in-JS styling                     |
+| [@gtkx/testing](packages/testing) | Testing utilities                     |
+| [@gtkx/gir](packages/gir)         | GObject Introspection parser          |
 
 ## Requirements
 
@@ -136,7 +145,6 @@ We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 - [Report a bug](https://github.com/eugeniodepalo/gtkx/issues/new?template=bug_report.md)
 - [Request a feature](https://github.com/eugeniodepalo/gtkx/issues/new?template=feature_request.md)
-- [Read the Code of Conduct](CODE_OF_CONDUCT.md)
 
 ## License
 

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { fireEvent } from "./fire-event.js";
 export { findAllByLabelText, findAllByRole, findAllByTestId, findAllByText, findByLabelText, findByRole, findByTestId, findByText, } from "./queries.js";
 export { cleanup, render, teardown } from "./render.js";
 export { screen } from "./screen.js";
-export type { BoundQueries, ByRoleOptions, RenderOptions, RenderResult, TextMatchOptions, WaitForOptions, } from "./types.js";
+export type { BoundQueries, ByRoleOptions, NormalizerOptions, RenderOptions, RenderResult, TextMatch, TextMatchFunction, TextMatchOptions, WaitForOptions, } from "./types.js";
 export type { TabOptions } from "./user-event.js";
 export { userEvent } from "./user-event.js";
 export { waitFor, waitForElementToBeRemoved } from "./wait-for.js";

package/dist/queries.d.ts

@@ -1,6 +1,6 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
 import { AccessibleRole } from "@gtkx/ffi/gtk";
-import type { ByRoleOptions, TextMatchOptions } from "./types.js";
+import type { ByRoleOptions, TextMatch, TextMatchOptions } from "./types.js";
 type Container = Gtk.Application | Gtk.Widget;
 /**
  * Waits for and finds a single widget matching the specified accessible role.
@@ -21,49 +21,49 @@ export declare const findAllByRole: (container: Container, role: AccessibleRole,
 /**
  * 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 text - The text, pattern, or matcher function
  * @param options - Text matching options (exact, normalizer, timeout)
  * @returns Promise resolving to the matching widget
  */
-export declare const findByLabelText: (container: Container, text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget>;
+export declare const findByLabelText: (container: Container, text: TextMatch, 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 text - The text, pattern, or matcher function
  * @param options - Text matching options (exact, normalizer, timeout)
  * @returns Promise resolving to array of matching widgets
  */
-export declare const findAllByLabelText: (container: Container, text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
+export declare const findAllByLabelText: (container: Container, text: TextMatch, 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 text - The text, pattern, or matcher function
  * @param options - Text matching options (exact, normalizer, timeout)
  * @returns Promise resolving to the matching widget
  */
-export declare const findByText: (container: Container, text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget>;
+export declare const findByText: (container: Container, text: TextMatch, 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 text - The text, pattern, or matcher function
  * @param options - Text matching options (exact, normalizer, timeout)
  * @returns Promise resolving to array of matching widgets
  */
-export declare const findAllByText: (container: Container, text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
+export declare const findAllByText: (container: Container, text: TextMatch, 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 testId - The test ID, pattern, or matcher function
  * @param options - Text matching options (exact, normalizer, timeout)
  * @returns Promise resolving to the matching widget
  */
-export declare const findByTestId: (container: Container, testId: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget>;
+export declare const findByTestId: (container: Container, testId: TextMatch, 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 testId - The test ID, pattern, or matcher function
  * @param options - Text matching options (exact, normalizer, timeout)
  * @returns Promise resolving to array of matching widgets
  */
-export declare const findAllByTestId: (container: Container, testId: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
+export declare const findAllByTestId: (container: Container, testId: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
 export {};

package/dist/queries.js

@@ -1,22 +1,42 @@
 import { getInterface } from "@gtkx/ffi";
-import { Accessible, AccessibleRole, Button, CheckButton, Editable, Expander, Frame, Label, StackPage, Switch, ToggleButton, Window, } from "@gtkx/ffi/gtk";
+import { Accessible, AccessibleRole, Button, CheckButton, Editable, Expander, Frame, Label, MenuButton, StackPage, Switch, ToggleButton, Window, } from "@gtkx/ffi/gtk";
 import { findAll } from "./traversal.js";
 import { waitFor } from "./wait-for.js";
-const DEFAULT_NORMALIZER = (text) => text.trim().replace(/\s+/g, " ");
+const buildNormalizer = (options) => {
+    if (options?.normalizer) {
+        return options.normalizer;
+    }
+    const trim = options?.trim ?? true;
+    const collapseWhitespace = options?.collapseWhitespace ?? true;
+    return (text) => {
+        let result = text;
+        if (trim) {
+            result = result.trim();
+        }
+        if (collapseWhitespace) {
+            result = result.replace(/\s+/g, " ");
+        }
+        return result;
+    };
+};
 const normalizeText = (text, options) => {
-    const normalizer = options?.normalizer ?? DEFAULT_NORMALIZER;
+    const normalizer = buildNormalizer(options);
     return normalizer(text);
 };
-const matchText = (actual, expected, options) => {
+const matchText = (actual, expected, widget, options) => {
     if (actual === null)
         return false;
     const normalizedActual = normalizeText(actual, options);
-    const exact = options?.exact ?? true;
-    if (typeof expected === "string") {
-        const normalizedExpected = normalizeText(expected, options);
-        return exact ? normalizedActual === normalizedExpected : normalizedActual.includes(normalizedExpected);
+    if (typeof expected === "function") {
+        return expected(normalizedActual, widget);
+    }
+    if (expected instanceof RegExp) {
+        expected.lastIndex = 0;
+        return expected.test(normalizedActual);
     }
-    return expected.test(normalizedActual);
+    const normalizedExpected = normalizeText(expected, options);
+    const exact = options?.exact ?? true;
+    return exact ? normalizedActual === normalizedExpected : normalizedActual.includes(normalizedExpected);
 };
 const ROLES_WITH_INTERNAL_LABELS = new Set([
     AccessibleRole.BUTTON,
@@ -31,54 +51,68 @@ const ROLES_WITH_INTERNAL_LABELS = new Set([
 ]);
 const isInternalLabel = (widget) => {
     const accessible = getInterface(widget, Accessible);
-    if (accessible.getAccessibleRole() !== AccessibleRole.LABEL)
+    if (!accessible || accessible.getAccessibleRole() !== AccessibleRole.LABEL)
         return false;
     const parent = widget.getParent();
     if (!parent)
         return false;
-    const parentRole = getInterface(parent, Accessible).getAccessibleRole();
-    return ROLES_WITH_INTERNAL_LABELS.has(parentRole);
+    const parentAccessible = getInterface(parent, Accessible);
+    if (!parentAccessible)
+        return false;
+    return ROLES_WITH_INTERNAL_LABELS.has(parentAccessible.getAccessibleRole());
+};
+const collectChildLabels = (widget) => {
+    const labels = [];
+    let child = widget.getFirstChild();
+    while (child) {
+        const childAccessible = getInterface(child, Accessible);
+        if (childAccessible?.getAccessibleRole() === AccessibleRole.LABEL) {
+            const labelText = getInterface(child, Label)?.getLabel();
+            if (labelText)
+                labels.push(labelText);
+        }
+        labels.push(...collectChildLabels(child));
+        child = child.getNextSibling();
+    }
+    return labels;
 };
 const getWidgetText = (widget) => {
     if (isInternalLabel(widget))
         return null;
-    const role = getInterface(widget, Accessible).getAccessibleRole();
+    const role = getInterface(widget, Accessible)?.getAccessibleRole();
+    if (role === undefined)
+        return null;
     switch (role) {
         case AccessibleRole.BUTTON:
         case AccessibleRole.LINK:
-        case AccessibleRole.TAB:
-            return getInterface(widget, Button).getLabel();
+        case AccessibleRole.TAB: {
+            const directLabel = getInterface(widget, Button)?.getLabel() ??
+                getInterface(widget, MenuButton)?.getLabel() ??
+                getInterface(widget, Expander)?.getLabel();
+            if (directLabel)
+                return directLabel;
+            const childLabels = collectChildLabels(widget);
+            return childLabels.length > 0 ? childLabels.join(" ") : null;
+        }
         case AccessibleRole.TOGGLE_BUTTON:
-            return getInterface(widget, ToggleButton).getLabel();
+            return getInterface(widget, ToggleButton)?.getLabel() ?? null;
         case AccessibleRole.CHECKBOX:
         case AccessibleRole.RADIO:
-            return getInterface(widget, CheckButton).getLabel();
+            return getInterface(widget, CheckButton)?.getLabel() ?? null;
         case AccessibleRole.LABEL:
-            return getInterface(widget, Label).getLabel();
+            return getInterface(widget, Label)?.getLabel() ?? null;
         case AccessibleRole.TEXT_BOX:
         case AccessibleRole.SEARCH_BOX:
         case AccessibleRole.SPIN_BUTTON:
-            return getInterface(widget, Editable).getText();
+            return getInterface(widget, Editable)?.getText() ?? null;
         case AccessibleRole.GROUP:
-            try {
-                return getInterface(widget, Frame).getLabel();
-            }
-            catch {
-                return null;
-            }
+            return getInterface(widget, Frame)?.getLabel() ?? null;
         case AccessibleRole.WINDOW:
         case AccessibleRole.DIALOG:
         case AccessibleRole.ALERT_DIALOG:
-            return getInterface(widget, Window).getTitle();
+            return getInterface(widget, Window)?.getTitle() ?? null;
         case AccessibleRole.TAB_PANEL:
-            try {
-                return getInterface(widget, StackPage).getTitle();
-            }
-            catch {
-                return null;
-            }
-        case AccessibleRole.SWITCH:
-            return null;
+            return getInterface(widget, StackPage)?.getTitle() ?? null;
         default:
             return null;
     }
@@ -87,26 +121,32 @@ const getWidgetTestId = (widget) => {
     return widget.getName();
 };
 const getWidgetCheckedState = (widget) => {
-    const role = getInterface(widget, Accessible).getAccessibleRole();
+    const accessible = getInterface(widget, Accessible);
+    if (!accessible)
+        return undefined;
+    const role = accessible.getAccessibleRole();
     switch (role) {
         case AccessibleRole.CHECKBOX:
         case AccessibleRole.RADIO:
-            return getInterface(widget, CheckButton).getActive();
+            return getInterface(widget, CheckButton)?.getActive();
         case AccessibleRole.TOGGLE_BUTTON:
-            return getInterface(widget, ToggleButton).getActive();
+            return getInterface(widget, ToggleButton)?.getActive();
         case AccessibleRole.SWITCH:
-            return getInterface(widget, Switch).getActive();
+            return getInterface(widget, Switch)?.getActive();
         default:
             return undefined;
     }
 };
 const getWidgetExpandedState = (widget) => {
-    const role = getInterface(widget, Accessible).getAccessibleRole();
+    const accessible = getInterface(widget, Accessible);
+    if (!accessible)
+        return undefined;
+    const role = accessible.getAccessibleRole();
     if (role === AccessibleRole.BUTTON) {
         const parent = widget.getParent();
         if (!parent)
             return undefined;
-        return getInterface(parent, Expander).getExpanded();
+        return getInterface(parent, Expander)?.getExpanded();
     }
     return undefined;
 };
@@ -115,7 +155,7 @@ const matchByRoleOptions = (widget, options) => {
         return true;
     if (options.name !== undefined) {
         const text = getWidgetText(widget);
-        if (!matchText(text, options.name, options))
+        if (!matchText(text, options.name, widget, options))
             return false;
     }
     if (options.checked !== undefined) {
@@ -149,7 +189,8 @@ const formatByRoleError = (role, options) => {
 };
 const getAllByRole = (container, role, options) => {
     const matches = findAll(container, (node) => {
-        if (getInterface(node, Accessible).getAccessibleRole() !== role)
+        const accessible = getInterface(node, Accessible);
+        if (!accessible || accessible.getAccessibleRole() !== role)
             return false;
         return matchByRoleOptions(node, options);
     });
@@ -171,7 +212,7 @@ const getByRole = (container, role, options) => {
 const getAllByLabelText = (container, text, options) => {
     const matches = findAll(container, (node) => {
         const widgetText = getWidgetText(node);
-        return matchText(widgetText, text, options);
+        return matchText(widgetText, text, node, options);
     });
     if (matches.length === 0) {
         throw new Error(`Unable to find any elements with label text "${text}"`);
@@ -191,7 +232,7 @@ const getByLabelText = (container, text, options) => {
 const getAllByText = (container, text, options) => {
     const matches = findAll(container, (node) => {
         const widgetText = getWidgetText(node);
-        return matchText(widgetText, text, options);
+        return matchText(widgetText, text, node, options);
     });
     if (matches.length === 0) {
         throw new Error(`Unable to find any elements with text "${text}"`);
@@ -211,7 +252,7 @@ const getByText = (container, text, options) => {
 const getAllByTestId = (container, testId, options) => {
     const matches = findAll(container, (node) => {
         const widgetTestId = getWidgetTestId(node);
-        return matchText(widgetTestId, testId, options);
+        return matchText(widgetTestId, testId, node, options);
     });
     if (matches.length === 0) {
         throw new Error(`Unable to find any elements with test id "${testId}"`);
@@ -235,7 +276,9 @@ const getByTestId = (container, testId, options) => {
  * @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), { timeout: options?.timeout });
+export const findByRole = async (container, role, options) => waitFor(() => getByRole(container, role, options), {
+    timeout: options?.timeout,
+});
 /**
  * Waits for and finds all widgets matching the specified accessible role.
  * @param container - The container to search within
@@ -243,52 +286,66 @@ export const findByRole = async (container, role, options) => waitFor(() => getB
  * @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), { timeout: options?.timeout });
+export const findAllByRole = async (container, role, options) => waitFor(() => getAllByRole(container, role, options), {
+    timeout: options?.timeout,
+});
 /**
  * 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 text - The text, pattern, or matcher function
  * @param options - Text matching options (exact, normalizer, timeout)
  * @returns Promise resolving to the matching widget
  */
-export const findByLabelText = async (container, text, options) => waitFor(() => getByLabelText(container, text, options), { timeout: options?.timeout });
+export const findByLabelText = async (container, text, options) => waitFor(() => getByLabelText(container, text, options), {
+    timeout: options?.timeout,
+});
 /**
  * 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 text - The text, pattern, or matcher function
  * @param options - Text matching options (exact, normalizer, timeout)
  * @returns Promise resolving to array of matching widgets
  */
-export const findAllByLabelText = async (container, text, options) => waitFor(() => getAllByLabelText(container, text, options), { timeout: options?.timeout });
+export const findAllByLabelText = async (container, text, options) => waitFor(() => getAllByLabelText(container, text, options), {
+    timeout: options?.timeout,
+});
 /**
  * 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 text - The text, pattern, or matcher function
  * @param options - Text matching options (exact, normalizer, timeout)
  * @returns Promise resolving to the matching widget
  */
-export const findByText = async (container, text, options) => waitFor(() => getByText(container, text, options), { timeout: options?.timeout });
+export const findByText = async (container, text, options) => waitFor(() => getByText(container, text, options), {
+    timeout: options?.timeout,
+});
 /**
  * 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 text - The text, pattern, or matcher function
  * @param options - Text matching options (exact, normalizer, timeout)
  * @returns Promise resolving to array of matching widgets
  */
-export const findAllByText = async (container, text, options) => waitFor(() => getAllByText(container, text, options), { timeout: options?.timeout });
+export const findAllByText = async (container, text, options) => waitFor(() => getAllByText(container, text, options), {
+    timeout: options?.timeout,
+});
 /**
  * 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 testId - The test ID, pattern, or matcher function
  * @param options - Text matching options (exact, normalizer, timeout)
  * @returns Promise resolving to the matching widget
  */
-export const findByTestId = async (container, testId, options) => waitFor(() => getByTestId(container, testId, options), { timeout: options?.timeout });
+export const findByTestId = async (container, testId, options) => waitFor(() => getByTestId(container, testId, options), {
+    timeout: options?.timeout,
+});
 /**
  * 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 testId - The test ID, pattern, or matcher function
  * @param options - Text matching options (exact, normalizer, timeout)
  * @returns Promise resolving to array of matching widgets
  */
-export const findAllByTestId = async (container, testId, options) => waitFor(() => getAllByTestId(container, testId, options), { timeout: options?.timeout });
+export const findAllByTestId = async (container, testId, options) => waitFor(() => getAllByTestId(container, testId, options), {
+    timeout: options?.timeout,
+});

package/dist/render.js

@@ -11,15 +11,19 @@ let container = null;
 const getWidgetLabel = (widget) => {
     if (!hasLabel(widget))
         return null;
-    const role = getInterface(widget, Gtk.Accessible).getAccessibleRole();
+    const accessible = getInterface(widget, Gtk.Accessible);
+    if (!accessible)
+        return null;
+    const role = accessible.getAccessibleRole();
     if (role === Gtk.AccessibleRole.LABEL) {
-        return getInterface(widget, Gtk.Label).getLabel();
+        return getInterface(widget, Gtk.Label)?.getLabel() ?? null;
     }
-    return getInterface(widget, Gtk.Button).getLabel();
+    return getInterface(widget, Gtk.Button)?.getLabel() ?? null;
 };
 const printWidgetTree = (root, indent = 0) => {
     const prefix = "  ".repeat(indent);
-    const role = Gtk.AccessibleRole[getInterface(root, Gtk.Accessible).getAccessibleRole()] ?? "UNKNOWN";
+    const accessibleRole = getInterface(root, Gtk.Accessible)?.getAccessibleRole();
+    const role = accessibleRole !== undefined ? (Gtk.AccessibleRole[accessibleRole] ?? "UNKNOWN") : "UNKNOWN";
     const labelText = getWidgetLabel(root);
     const label = labelText ? ` label="${labelText}"` : "";
     let result = `${prefix}<${root.constructor.name} role=${role}${label}>\n`;

package/dist/screen.d.ts

@@ -1,6 +1,6 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
 import type { AccessibleRole } from "@gtkx/ffi/gtk";
-import type { ByRoleOptions, TextMatchOptions } from "./types.js";
+import type { ByRoleOptions, TextMatch, 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
@@ -13,12 +13,12 @@ export declare const setScreenRoot: (root: Gtk.Application | null) => void;
  */
 export declare const screen: {
     findByRole: (role: AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget>;
-    findByLabelText: (text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget>;
-    findByText: (text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget>;
-    findByTestId: (testId: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget>;
+    findByLabelText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
+    findByText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
+    findByTestId: (testId: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
     findAllByRole: (role: AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget[]>;
-    findAllByLabelText: (text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
-    findAllByText: (text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
-    findAllByTestId: (testId: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
+    findAllByLabelText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
+    findAllByText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
+    findAllByTestId: (testId: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
     debug: () => void;
 };

package/dist/types.d.ts

@@ -1,14 +1,40 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
 import type { AccessibleRole } 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.
+ */
+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.
+ */
+export type TextMatch = string | RegExp | TextMatchFunction;
+/**
+ * Options for normalizing text before comparison.
+ */
+export interface NormalizerOptions {
+    /** Whether to trim whitespace from text. Defaults to true. */
+    trim?: boolean;
+    /** Whether to collapse multiple whitespace into single spaces. Defaults to true. */
+    collapseWhitespace?: boolean;
+}
 /**
  * Options for text matching in queries.
  */
 export interface TextMatchOptions {
     /** Whether to match the entire string exactly. Defaults to true. */
     exact?: boolean;
-    /** Custom function to normalize text before comparison. */
+    /**
+     * Custom function to normalize text before comparison.
+     * Cannot be used with trim/collapseWhitespace options.
+     */
     normalizer?: (text: string) => string;
+    /** Whether to trim whitespace from text. Defaults to true. */
+    trim?: boolean;
+    /** Whether to collapse multiple whitespace into single spaces. Defaults to true. */
+    collapseWhitespace?: boolean;
     /** Maximum time in milliseconds to wait for a match. */
     timeout?: number;
 }
@@ -16,8 +42,8 @@ export interface TextMatchOptions {
  * Options for querying elements by their accessible role.
  */
 export interface ByRoleOptions extends TextMatchOptions {
-    /** Filter by the element's accessible name. */
-    name?: string | RegExp;
+    /** Filter by the element's accessible name. Supports string, RegExp, or function matcher. */
+    name?: TextMatch;
     /** Filter checkboxes/switches by checked state. */
     checked?: boolean;
     /** Filter toggle buttons by pressed state. */
@@ -62,19 +88,19 @@ export interface BoundQueries {
     /** Find a single element by its accessible role. */
     findByRole: (role: AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget>;
     /** Find a single element by its associated label text. */
-    findByLabelText: (text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget>;
+    findByLabelText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
     /** Find a single element by its text content. */
-    findByText: (text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget>;
+    findByText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
     /** Find a single element by its test ID. */
-    findByTestId: (testId: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget>;
+    findByTestId: (testId: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
     /** Find all elements matching an accessible role. */
     findAllByRole: (role: AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget[]>;
     /** Find all elements with matching label text. */
-    findAllByLabelText: (text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
+    findAllByLabelText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
     /** Find all elements with matching text content. */
-    findAllByText: (text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
+    findAllByText: (text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
     /** Find all elements with matching test ID. */
-    findAllByTestId: (testId: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
+    findAllByTestId: (testId: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
 }
 /**
  * The result returned by the render function. Includes query methods

package/dist/user-event.js

@@ -3,18 +3,29 @@ import { Accessible, AccessibleRole, DirectionType, Editable, Widget, } from "@g
 import { fireEvent } from "./fire-event.js";
 import { tick } from "./timing.js";
 import { isEditable } from "./widget.js";
-const TOGGLEABLE_ROLES = new Set([AccessibleRole.CHECKBOX, AccessibleRole.RADIO, AccessibleRole.TOGGLE_BUTTON]);
+const TOGGLEABLE_ROLES = new Set([
+    AccessibleRole.CHECKBOX,
+    AccessibleRole.RADIO,
+    AccessibleRole.TOGGLE_BUTTON,
+    AccessibleRole.SWITCH,
+]);
 const isToggleable = (widget) => {
-    const role = getInterface(widget, Accessible).getAccessibleRole();
-    return TOGGLEABLE_ROLES.has(role);
+    const accessible = getInterface(widget, Accessible);
+    if (!accessible)
+        return false;
+    return TOGGLEABLE_ROLES.has(accessible.getAccessibleRole());
 };
 const click = async (element) => {
     if (isToggleable(element)) {
-        const role = getInterface(element, Accessible).getAccessibleRole();
+        const role = getInterface(element, Accessible)?.getAccessibleRole();
         if (role === AccessibleRole.CHECKBOX || role === AccessibleRole.RADIO) {
             const checkButton = element;
             checkButton.setActive(!checkButton.getActive());
         }
+        else if (role === AccessibleRole.SWITCH) {
+            const switchWidget = element;
+            switchWidget.setActive(!switchWidget.getActive());
+        }
         else {
             const toggleButton = element;
             toggleButton.setActive(!toggleButton.getActive());
@@ -42,7 +53,7 @@ const tab = async (element, options) => {
     const direction = options?.shift ? DirectionType.TAB_BACKWARD : DirectionType.TAB_FORWARD;
     const root = element.getRoot();
     if (root) {
-        getInterface(root, Widget).childFocus(direction);
+        getInterface(root, Widget)?.childFocus(direction);
     }
     await tick();
 };
@@ -51,6 +62,8 @@ const type = async (element, text) => {
         throw new Error("Cannot type into element: element is not editable (TEXT_BOX, SEARCH_BOX, or SPIN_BUTTON)");
     }
     const editable = getInterface(element, Editable);
+    if (!editable)
+        return;
     const currentText = editable.getText();
     editable.setText(currentText + text);
     await tick();
@@ -59,19 +72,21 @@ const clear = async (element) => {
     if (!isEditable(element)) {
         throw new Error("Cannot clear element: element is not editable (TEXT_BOX, SEARCH_BOX, or SPIN_BUTTON)");
     }
-    getInterface(element, Editable).setText("");
+    getInterface(element, Editable)?.setText("");
     await tick();
 };
 const SELECTABLE_ROLES = new Set([AccessibleRole.COMBO_BOX, AccessibleRole.LIST]);
 const isSelectable = (widget) => {
-    const role = getInterface(widget, Accessible).getAccessibleRole();
-    return SELECTABLE_ROLES.has(role);
+    const accessible = getInterface(widget, Accessible);
+    if (!accessible)
+        return false;
+    return SELECTABLE_ROLES.has(accessible.getAccessibleRole());
 };
 const selectOptions = async (element, values) => {
     if (!isSelectable(element)) {
         throw new Error("Cannot select options: element is not a selectable widget (COMBO_BOX or LIST)");
     }
-    const role = getInterface(element, Accessible).getAccessibleRole();
+    const role = getInterface(element, Accessible)?.getAccessibleRole();
     const valueArray = Array.isArray(values) ? values : [values];
     if (role === AccessibleRole.COMBO_BOX) {
         if (valueArray.length > 1) {
@@ -98,13 +113,14 @@ const selectOptions = async (element, values) => {
             const row = listBox.getRowAtIndex(value);
             if (row) {
                 listBox.selectRow(row);
+                row.activate();
             }
         }
     }
     await tick();
 };
 const deselectOptions = async (element, values) => {
-    const role = getInterface(element, Accessible).getAccessibleRole();
+    const role = getInterface(element, Accessible)?.getAccessibleRole();
     if (role !== AccessibleRole.LIST) {
         throw new Error("Cannot deselect options: only ListBox supports deselection");
     }

package/dist/widget.js

@@ -5,8 +5,10 @@ const EDITABLE_ROLES = new Set([AccessibleRole.TEXT_BOX, AccessibleRole.SEARCH_B
  * Checks if a widget has an editable accessible role (text box, search box, or spin button).
  */
 export const isEditable = (widget) => {
-    const role = getInterface(widget, Accessible).getAccessibleRole();
-    return EDITABLE_ROLES.has(role);
+    const accessible = getInterface(widget, Accessible);
+    if (!accessible)
+        return false;
+    return EDITABLE_ROLES.has(accessible.getAccessibleRole());
 };
 const LABEL_ROLES = new Set([
     AccessibleRole.BUTTON,
@@ -22,6 +24,8 @@ const LABEL_ROLES = new Set([
  * Checks if a widget has an accessible role that supports labels.
  */
 export const hasLabel = (widget) => {
-    const role = getInterface(widget, Accessible).getAccessibleRole();
-    return LABEL_ROLES.has(role);
+    const accessible = getInterface(widget, Accessible);
+    if (!accessible)
+        return false;
+    return LABEL_ROLES.has(accessible.getAccessibleRole());
 };

package/package.json

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