@gtkx/testing 0.17.2 → 0.18.0

package/README.md

@@ -10,9 +10,9 @@
 
 <p align="center">
  <a href="https://www.npmjs.com/package/@gtkx/react"><img src="https://img.shields.io/npm/v/@gtkx/react.svg" alt="npm version"></a>
- <a href="https://github.com/eugeniodepalo/gtkx/actions"><img src="https://img.shields.io/github/actions/workflow/status/eugeniodepalo/gtkx/ci.yml" alt="CI"></a>
- <a href="https://github.com/eugeniodepalo/gtkx/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MPL--2.0-blue.svg" alt="License"></a>
- <a href="https://github.com/eugeniodepalo/gtkx/discussions"><img src="https://img.shields.io/badge/discussions-GitHub-blue" alt="GitHub Discussions"></a>
+ <a href="https://github.com/gtkx-org/gtkx/actions"><img src="https://img.shields.io/github/actions/workflow/status/eugeniodepalo/gtkx/ci.yml" alt="CI"></a>
+ <a href="https://github.com/gtkx-org/gtkx/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MPL--2.0-blue.svg" alt="License"></a>
+ <a href="https://github.com/gtkx-org/gtkx/discussions"><img src="https://img.shields.io/badge/discussions-GitHub-blue" alt="GitHub Discussions"></a>
 </p>
 
 ---
@@ -90,16 +90,16 @@ Explore complete applications in the [`examples/`](./examples) directory:
 
 ## Documentation
 
-Visit [https://eugeniodepalo.github.io/gtkx](https://eugeniodepalo.github.io/gtkx/) for the full documentation.
+Visit [https://gtkx.dev](https://gtkx.dev) for the full documentation.
 
 ## Contributing
 
-Contributions are welcome! Please see the [contributing guidelines](./CONTRIBUTING.md) and check out the [good first issues](https://github.com/eugeniodepalo/gtkx/labels/good%20first%20issue).
+Contributions are welcome! Please see the [contributing guidelines](./CONTRIBUTING.md) and check out the [good first issues](https://github.com/gtkx-org/gtkx/labels/good%20first%20issue).
 
 ## Community
 
-- [GitHub Discussions](https://github.com/eugeniodepalo/gtkx/discussions) — Questions, ideas, and general discussion
-- [Issue Tracker](https://github.com/eugeniodepalo/gtkx/issues) — Bug reports and feature requests
+- [GitHub Discussions](https://github.com/gtkx-org/gtkx/discussions) — Questions, ideas, and general discussion
+- [Issue Tracker](https://github.com/gtkx-org/gtkx/issues) — Bug reports and feature requests
 
 ## License
 

package/dist/fire-event.js

@@ -29,6 +29,6 @@ export const fireEvent = async (element, signalName, ...args) => {
     const gtype = typeFromName(element.constructor.glibTypeName);
     const signalId = signalLookup(signalName, gtype);
     const instanceValue = Value.newFromObject(element);
-    signalEmitv([instanceValue, ...args], signalId, 0, null);
+    signalEmitv([instanceValue, ...args], signalId, 0);
     await tick();
 };

package/dist/index.d.ts

@@ -12,7 +12,8 @@ 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, RenderHookOptions, RenderHookResult, RenderOptions, RenderResult, ScreenshotResult, TextMatch, TextMatchFunction, TextMatchOptions, WaitForOptions, } from "./types.js";
+export type { Container } from "./traversal.js";
+export type { BoundQueries, ByRoleOptions, NormalizerOptions, RenderHookOptions, RenderHookResult, RenderOptions, RenderResult, ScreenshotResult, TextMatch, TextMatchFunction, TextMatchOptions, WaitForOptions, WrapperComponent, } 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/pretty-widget.js

@@ -1,10 +1,19 @@
-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";
 const DEFAULT_MAX_LENGTH = 7000;
 const INDENT = "  ";
+const debugIdMap = new WeakMap();
+let nextDebugId = 0;
+const getWidgetDebugId = (widget) => {
+    let id = debugIdMap.get(widget);
+    if (!id) {
+        id = String(nextDebugId++);
+        debugIdMap.set(widget, id);
+    }
+    return id;
+};
 const shouldHighlight = () => {
     if (typeof process === "undefined")
         return false;
@@ -42,7 +51,7 @@ const escapeAttrValue = (value) => {
 const formatAttributes = (widget, colors, includeIds) => {
     const attrs = [];
     if (includeIds) {
-        attrs.push(["id", String(getNativeId(widget.handle))]);
+        attrs.push(["id", getWidgetDebugId(widget)]);
     }
     const name = widget.getName();
     if (name) {

package/dist/queries.d.ts

@@ -1,4 +1,4 @@
-import type * as Gtk from "@gtkx/ffi/gtk";
+import * as Gtk from "@gtkx/ffi/gtk";
 import { type Container } from "./traversal.js";
 import type { ByRoleOptions, TextMatch, TextMatchOptions } from "./types.js";
 /**
@@ -21,12 +21,16 @@ export declare const queryAllByRole: (container: Container, role: Gtk.Accessible
  */
 export declare const queryByRole: (container: Container, role: Gtk.AccessibleRole, options?: ByRoleOptions) => Gtk.Widget | null;
 /**
- * Finds all elements matching label text without throwing.
+ * Finds all elements that are labelled by a GtkLabel whose text matches.
+ *
+ * Uses GtkLabel's mnemonic widget association to find form elements
+ * by their label text. Only returns widgets that are properly labelled
+ * via GtkLabel's mnemonic-widget property.
  *
  * @param container - The container to search within
- * @param text - Text to match (string, RegExp, or custom matcher)
+ * @param text - Label text to match (string, RegExp, or custom matcher)
  * @param options - Query options including normalization
- * @returns Array of matching widgets (empty if none found)
+ * @returns Array of labelled widgets (empty if none found)
  */
 export declare const queryAllByLabelText: (container: Container, text: TextMatch, options?: TextMatchOptions) => Gtk.Widget[];
 /**
@@ -103,20 +107,19 @@ export declare const findByRole: (container: Container, role: Gtk.AccessibleRole
  */
 export declare const findAllByRole: (container: Container, role: Gtk.AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget[]>;
 /**
- * Finds a single element by its label or text content.
+ * Finds a single element that is labelled by a GtkLabel whose text matches.
  *
- * Matches button labels, input placeholders, window titles, and other
- * accessible text content.
+ * Waits for the element to appear, throwing if not found within timeout.
+ * Uses GtkLabel's mnemonic widget association to find form elements.
  *
  * @param container - The container to search within
- * @param text - Text to match (string, RegExp, or custom matcher)
+ * @param text - Label text to match (string, RegExp, or custom matcher)
  * @param options - Query options including normalization and timeout
- * @returns Promise resolving to the matching widget
+ * @returns Promise resolving to the labelled widget
  *
  * @example
  * ```tsx
- * const button = await findByLabelText(container, "Click me");
- * const input = await findByLabelText(container, /search/i);
+ * const input = await findByLabelText(container, "Username");
  * ```
  */
 export declare const findByLabelText: (container: Container, text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;

package/dist/queries.js

@@ -1,8 +1,8 @@
-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_INTERVAL = 50;
+import * as Gtk from "@gtkx/ffi/gtk";
+import { buildMultipleFoundError, buildNotFoundError } from "./error-builder.js";
+import { findAll, traverse } from "./traversal.js";
+import { waitFor } from "./wait-for.js";
+import { getWidgetCheckedState, getWidgetExpandedState, getWidgetPressedState, getWidgetSelectedState, getWidgetTestId, getWidgetText, } from "./widget-text.js";
 const buildNormalizer = (options) => {
     if (options?.normalizer) {
         return options.normalizer;
@@ -37,7 +37,9 @@ const matchText = (actual, expected, widget, options) => {
     }
     const normalizedExpected = normalizeText(expected, options);
     const exact = options?.exact ?? true;
-    return exact ? normalizedActual === normalizedExpected : normalizedActual.includes(normalizedExpected);
+    return exact
+        ? normalizedActual === normalizedExpected
+        : normalizedActual.toLowerCase().includes(normalizedExpected.toLowerCase());
 };
 const matchByRoleOptions = (widget, options) => {
     if (!options)
@@ -52,32 +54,22 @@ const matchByRoleOptions = (widget, options) => {
         if (checked !== options.checked)
             return false;
     }
+    if (options.pressed !== undefined) {
+        const pressed = getWidgetPressedState(widget);
+        if (pressed !== options.pressed)
+            return false;
+    }
     if (options.expanded !== undefined) {
         const expanded = getWidgetExpandedState(widget);
         if (expanded !== options.expanded)
             return false;
     }
-    return true;
-};
-const waitFor = async (callback, 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) {
-        try {
-            return await callback();
-        }
-        catch (error) {
-            lastError = error;
-            await new Promise((resolve) => setTimeout(resolve, interval));
-        }
-    }
-    const timeoutError = buildTimeoutError(timeout, lastError);
-    if (onTimeout) {
-        throw onTimeout(timeoutError);
+    if (options.selected !== undefined) {
+        const selected = getWidgetSelectedState(widget);
+        if (selected !== options.selected)
+            return false;
     }
-    throw timeoutError;
+    return true;
 };
 /**
  * Finds all elements matching a role without throwing.
@@ -111,18 +103,33 @@ export const queryByRole = (container, role, options) => {
     return matches[0] ?? null;
 };
 /**
- * Finds all elements matching label text without throwing.
+ * Finds all elements that are labelled by a GtkLabel whose text matches.
+ *
+ * Uses GtkLabel's mnemonic widget association to find form elements
+ * by their label text. Only returns widgets that are properly labelled
+ * via GtkLabel's mnemonic-widget property.
  *
  * @param container - The container to search within
- * @param text - Text to match (string, RegExp, or custom matcher)
+ * @param text - Label text to match (string, RegExp, or custom matcher)
  * @param options - Query options including normalization
- * @returns Array of matching widgets (empty if none found)
+ * @returns Array of labelled widgets (empty if none found)
  */
 export const queryAllByLabelText = (container, text, options) => {
-    return findAll(container, (node) => {
-        const widgetText = getWidgetText(node);
-        return matchText(widgetText, text, node, options);
-    });
+    const results = [];
+    for (const node of traverse(container)) {
+        if (!(node instanceof Gtk.Label))
+            continue;
+        const labelText = node.getLabel();
+        if (!labelText)
+            continue;
+        if (!matchText(labelText, text, node, options))
+            continue;
+        const target = node.getMnemonicWidget();
+        if (target) {
+            results.push(target);
+        }
+    }
+    return results;
 };
 /**
  * Finds a single element matching label text without throwing.
@@ -286,20 +293,19 @@ export const findAllByRole = async (container, role, options) => waitFor(() => g
     timeout: options?.timeout,
 });
 /**
- * Finds a single element by its label or text content.
+ * Finds a single element that is labelled by a GtkLabel whose text matches.
  *
- * Matches button labels, input placeholders, window titles, and other
- * accessible text content.
+ * Waits for the element to appear, throwing if not found within timeout.
+ * Uses GtkLabel's mnemonic widget association to find form elements.
  *
  * @param container - The container to search within
- * @param text - Text to match (string, RegExp, or custom matcher)
+ * @param text - Label text to match (string, RegExp, or custom matcher)
  * @param options - Query options including normalization and timeout
- * @returns Promise resolving to the matching widget
+ * @returns Promise resolving to the labelled widget
  *
  * @example
  * ```tsx
- * const button = await findByLabelText(container, "Click me");
- * const input = await findByLabelText(container, /search/i);
+ * const input = await findByLabelText(container, "Username");
  * ```
  */
 export const findByLabelText = async (container, text, options) => waitFor(() => getByLabelText(container, text, options), {

package/dist/render-hook.js

@@ -49,7 +49,7 @@ export const renderHook = async (callback, options) => {
         return null;
     };
     const renderResult = await render(_jsx(TestComponent, { props: currentProps }), {
-        wrapper: options?.wrapper ?? false,
+        wrapper: options?.wrapper ?? true,
     });
     return {
         result: resultRef,

package/dist/render.d.ts

@@ -1,4 +1,4 @@
-import type { ReactNode } from "react";
+import { type ReactNode } from "react";
 import type { RenderOptions, RenderResult } from "./types.js";
 /**
  * Renders a React element for testing.

package/dist/render.js

@@ -2,10 +2,12 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { start, stop } from "@gtkx/ffi";
 import * as Gio from "@gtkx/ffi/gio";
 import { ApplicationContext, GtkApplicationWindow, reconciler } from "@gtkx/react";
+import { createRef } from "react";
 import { bindQueries } from "./bind-queries.js";
 import { prettyWidget } from "./pretty-widget.js";
 import { setScreenRoot } from "./screen.js";
 import { tick } from "./timing.js";
+import { isApplication, traverse } from "./traversal.js";
 let application = null;
 let container = null;
 let lastRenderError = null;
@@ -30,14 +32,30 @@ const ensureInitialized = () => {
     }
     return { app: application, container };
 };
-const DefaultWrapper = ({ children }) => (_jsx(GtkApplicationWindow, { defaultWidth: 800, defaultHeight: 600, children: children }));
-const wrapElement = (element, wrapper = true) => {
-    if (wrapper === false)
+const DefaultWrapper = ({ children, ref }) => (_jsx(GtkApplicationWindow, { ref: ref, defaultWidth: 800, defaultHeight: 600, children: children }));
+const findFirstWidget = (root) => {
+    for (const widget of traverse(root)) {
+        if (isApplication(root))
+            return widget;
+        return root;
+    }
+    return null;
+};
+const wrapElement = (element, wrapperRef, wrapper) => {
+    if (wrapper === false || wrapper === undefined)
         return element;
-    if (wrapper === true)
-        return _jsx(DefaultWrapper, { children: element });
-    const Wrapper = wrapper;
-    return _jsx(Wrapper, { children: element });
+    const Wrapper = wrapper === true ? DefaultWrapper : wrapper;
+    return _jsx(Wrapper, { ref: wrapperRef, children: element });
+};
+const resolveContainer = (wrapper, wrapperRef, baseElement) => {
+    if (wrapper !== false && wrapper !== undefined && wrapperRef.current) {
+        return wrapperRef.current;
+    }
+    const firstWidget = findFirstWidget(baseElement);
+    if (!firstWidget) {
+        throw new Error("render() produced no widgets. Ensure the element renders visible content.");
+    }
+    return firstWidget;
 };
 /**
  * Renders a React element for testing.
@@ -66,18 +84,23 @@ const wrapElement = (element, wrapper = true) => {
 export const render = async (element, options) => {
     const { app: application, container: fiberRoot } = ensureInitialized();
     const instance = reconciler.getInstance();
-    const wrappedElement = wrapElement(element, options?.wrapper);
+    const baseElement = options?.baseElement ?? application;
+    const wrapper = options?.wrapper ?? true;
+    const wrapperRef = createRef();
+    const wrappedElement = wrapElement(element, wrapperRef, wrapper);
     const withContext = _jsx(ApplicationContext.Provider, { value: application, children: wrappedElement });
     await update(instance, withContext, fiberRoot);
     setScreenRoot(application);
     return {
-        container: application,
-        ...bindQueries(application),
+        container: resolveContainer(wrapper, wrapperRef, baseElement),
+        baseElement,
+        ...bindQueries(baseElement),
         unmount: () => update(instance, null, fiberRoot),
-        rerender: (newElement) => {
-            const wrapped = wrapElement(newElement, options?.wrapper);
+        rerender: async (newElement) => {
+            const newWrapperRef = createRef();
+            const wrapped = wrapElement(newElement, newWrapperRef, wrapper);
             const withCtx = _jsx(ApplicationContext.Provider, { value: application, children: wrapped });
-            return update(instance, withCtx, fiberRoot);
+            await update(instance, withCtx, fiberRoot);
         },
         debug: () => {
             console.log(prettyWidget(application));

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
-import type { ComponentType, ReactNode } from "react";
+import type { ComponentType, ReactNode, Ref } from "react";
+import type { Container } from "./traversal.js";
 /**
  * Custom function for matching text content.
  *
@@ -69,6 +70,14 @@ export type WaitForOptions = {
     /** Custom error handler called on timeout */
     onTimeout?: (error: Error) => Error;
 };
+/**
+ * A wrapper component that exposes its root GTK widget via `ref`.
+ * Accept `ref` as a prop and pass it through to the root intrinsic element.
+ */
+export type WrapperComponent = ComponentType<{
+    children: ReactNode;
+    ref?: Ref<Gtk.Widget>;
+}>;
 /**
  * Options for {@link render}.
  */
@@ -77,11 +86,15 @@ export type RenderOptions = {
      * Wrapper component or boolean.
      * - `true` (default): Wrap in GtkApplicationWindow
      * - `false`: No wrapper
-     * - Component: Custom wrapper component
+     * - Component: Custom wrapper that passes `ref` to its root element
+     */
+    wrapper?: boolean | WrapperComponent;
+    /**
+     * The element queries are bound to.
+     * Defaults to the GTK Application (searches all toplevel windows).
+     * Provide a specific widget or application to scope queries.
      */
-    wrapper?: boolean | ComponentType<{
-        children: ReactNode;
-    }>;
+    baseElement?: Container;
 };
 /**
  * Query methods bound to a container.
@@ -129,8 +142,10 @@ export type BoundQueries = {
  * Provides query methods and utilities for testing rendered components.
  */
 export type RenderResult = BoundQueries & {
-    /** The GTK Application container */
-    container: Gtk.Application;
+    /** The direct container widget wrapping the rendered content */
+    container: Gtk.Widget;
+    /** The element queries are bound to (defaults to the GTK Application) */
+    baseElement: Container;
     /** Unmount the rendered component */
     unmount: () => Promise<void>;
     /** Re-render with a new element */
@@ -161,13 +176,11 @@ export type RenderHookOptions<Props> = {
     initialProps?: Props;
     /**
      * Wrapper component or boolean.
-     * - `false` (default): No wrapper
-     * - `true`: Wrap in GtkApplicationWindow
-     * - Component: Custom wrapper component
+     * - `true` (default): Wrap in GtkApplicationWindow
+     * - `false`: No wrapper
+     * - Component: Custom wrapper that passes `ref` to its root element
      */
-    wrapper?: boolean | ComponentType<{
-        children: ReactNode;
-    }>;
+    wrapper?: boolean | WrapperComponent;
 };
 /**
  * Result returned by {@link renderHook}.

package/dist/user-event.d.ts

@@ -37,10 +37,10 @@ export type PointerInput = "click" | "down" | "up" | "[MouseLeft]" | "[MouseLeft
  */
 export declare const userEvent: {
     /**
-     * Clicks or toggles a widget.
+     * Activates a widget.
      *
-     * For toggleable widgets (checkboxes, switches, toggle buttons),
-     * toggles the active state. For buttons, emits clicked signal.
+     * Uses GTK's native {@link Gtk.Widget.activate} to trigger the widget's
+     * default action — clicking buttons, toggling checkboxes/switches, etc.
      */
     click: (element: Gtk.Widget) => Promise<void>;
     /**

package/dist/user-event.js

@@ -4,35 +4,9 @@ import * as Gtk from "@gtkx/ffi/gtk";
 import { fireEvent } from "./fire-event.js";
 import { tick } from "./timing.js";
 import { isEditable } from "./widget.js";
-const TOGGLEABLE_ROLES = new Set([
-    Gtk.AccessibleRole.CHECKBOX,
-    Gtk.AccessibleRole.RADIO,
-    Gtk.AccessibleRole.TOGGLE_BUTTON,
-    Gtk.AccessibleRole.SWITCH,
-]);
-const isToggleable = (widget) => {
-    return TOGGLEABLE_ROLES.has(widget.getAccessibleRole());
-};
 const click = async (element) => {
-    if (isToggleable(element)) {
-        const role = element.getAccessibleRole();
-        if (role === Gtk.AccessibleRole.CHECKBOX || role === Gtk.AccessibleRole.RADIO) {
-            const checkButton = element;
-            checkButton.setActive(!checkButton.getActive());
-        }
-        else if (role === Gtk.AccessibleRole.SWITCH) {
-            const switchWidget = element;
-            switchWidget.setActive(!switchWidget.getActive());
-        }
-        else {
-            const toggleButton = element;
-            toggleButton.setActive(!toggleButton.getActive());
-        }
-        await tick();
-    }
-    else {
-        await fireEvent(element, "clicked");
-    }
+    element.activate();
+    await tick();
 };
 const emitClickSequence = async (element, nPress) => {
     const controller = getOrCreateController(element, Gtk.GestureClick);
@@ -43,8 +17,8 @@ const emitClickSequence = async (element, nPress) => {
             Value.newFromDouble(0),
             Value.newFromDouble(0),
         ];
-        signalEmitv(args, getSignalId(controller, "pressed"), 0, null);
-        signalEmitv(args, getSignalId(controller, "released"), 0, null);
+        signalEmitv(args, getSignalId(controller, "pressed"), 0);
+        signalEmitv(args, getSignalId(controller, "released"), 0);
     }
     await tick();
 };
@@ -181,12 +155,12 @@ const getSignalId = (target, signalName) => {
 };
 const hover = async (element) => {
     const controller = getOrCreateController(element, Gtk.EventControllerMotion);
-    signalEmitv([Value.newFromObject(controller), Value.newFromDouble(0), Value.newFromDouble(0)], getSignalId(controller, "enter"), 0, null);
+    signalEmitv([Value.newFromObject(controller), Value.newFromDouble(0), Value.newFromDouble(0)], getSignalId(controller, "enter"), 0);
     await tick();
 };
 const unhover = async (element) => {
     const controller = getOrCreateController(element, Gtk.EventControllerMotion);
-    signalEmitv([Value.newFromObject(controller)], getSignalId(controller, "leave"), 0, null);
+    signalEmitv([Value.newFromObject(controller)], getSignalId(controller, "leave"), 0);
     await tick();
 };
 const KEY_MAP = {
@@ -247,19 +221,39 @@ const parseKeyboardInput = (input) => {
     }
     return actions;
 };
+const MODIFIER_KEYVAL_TO_MASK = {
+    [Gdk.KEY_Shift_L]: Gdk.ModifierType.SHIFT_MASK,
+    [Gdk.KEY_Shift_R]: Gdk.ModifierType.SHIFT_MASK,
+    [Gdk.KEY_Control_L]: Gdk.ModifierType.CONTROL_MASK,
+    [Gdk.KEY_Control_R]: Gdk.ModifierType.CONTROL_MASK,
+    [Gdk.KEY_Alt_L]: Gdk.ModifierType.ALT_MASK,
+    [Gdk.KEY_Alt_R]: Gdk.ModifierType.ALT_MASK,
+    [Gdk.KEY_Meta_L]: Gdk.ModifierType.META_MASK,
+    [Gdk.KEY_Meta_R]: Gdk.ModifierType.META_MASK,
+};
 let gdkModifierType = null;
 const keyboard = async (element, input) => {
     gdkModifierType ??= typeFromName("GdkModifierType");
     const controller = getOrCreateController(element, Gtk.EventControllerKey);
     const actions = parseKeyboardInput(input);
+    let modifierState = 0;
     for (const action of actions) {
+        const mask = MODIFIER_KEYVAL_TO_MASK[action.keyval];
+        if (mask) {
+            if (action.press) {
+                modifierState |= mask;
+            }
+            else {
+                modifierState &= ~mask;
+            }
+        }
         const signalName = action.press ? "key-pressed" : "key-released";
-        const returnValue = action.press ? Value.newFromBoolean(false) : null;
+        const returnValue = action.press ? Value.newFromBoolean(false) : undefined;
         signalEmitv([
             Value.newFromObject(controller),
             Value.newFromUint(action.keyval),
             Value.newFromUint(0),
-            Value.newFromFlags(gdkModifierType, 0),
+            Value.newFromFlags(gdkModifierType, modifierState),
         ], getSignalId(controller, signalName), 0, returnValue);
         if (action.press && action.keyval === Gdk.KEY_Return && isEditable(element)) {
             await fireEvent(element, "activate");
@@ -282,14 +276,14 @@ const pointer = async (element, input) => {
         Value.newFromDouble(0),
     ];
     if (input === "[MouseLeft]" || input === "click") {
-        signalEmitv(pressedArgs, getSignalId(controller, "pressed"), 0, null);
-        signalEmitv(releasedArgs, getSignalId(controller, "released"), 0, null);
+        signalEmitv(pressedArgs, getSignalId(controller, "pressed"), 0);
+        signalEmitv(releasedArgs, getSignalId(controller, "released"), 0);
     }
     else if (input === "[MouseLeft>]" || input === "down") {
-        signalEmitv(pressedArgs, getSignalId(controller, "pressed"), 0, null);
+        signalEmitv(pressedArgs, getSignalId(controller, "pressed"), 0);
     }
     else if (input === "[/MouseLeft]" || input === "up") {
-        signalEmitv(releasedArgs, getSignalId(controller, "released"), 0, null);
+        signalEmitv(releasedArgs, getSignalId(controller, "released"), 0);
     }
     await tick();
 };
@@ -316,10 +310,10 @@ const pointer = async (element, input) => {
  */
 export const userEvent = {
     /**
-     * Clicks or toggles a widget.
+     * Activates a widget.
      *
-     * For toggleable widgets (checkboxes, switches, toggle buttons),
-     * toggles the active state. For buttons, emits clicked signal.
+     * Uses GTK's native {@link Gtk.Widget.activate} to trigger the widget's
+     * default action — clicking buttons, toggling checkboxes/switches, etc.
      */
     click,
     /**

package/dist/wait-for.js

@@ -1,4 +1,5 @@
 import { getConfig } from "./config.js";
+import { buildTimeoutError } from "./error-builder.js";
 const DEFAULT_INTERVAL = 50;
 /**
  * Waits for a callback to succeed.
@@ -33,7 +34,7 @@ export const waitFor = async (callback, options) => {
             await new Promise((resolve) => setTimeout(resolve, interval));
         }
     }
-    const timeoutError = new Error(`Timed out after ${timeout}ms. Last error: ${lastError?.message}`);
+    const timeoutError = buildTimeoutError(timeout, lastError);
     if (onTimeout) {
         throw onTimeout(timeoutError);
     }

package/dist/widget-text.d.ts

@@ -20,6 +20,13 @@ export declare const getWidgetTestId: (widget: Gtk.Widget) => string | null;
  * @returns The checked state or null if not applicable
  */
 export declare const getWidgetCheckedState: (widget: Gtk.Widget) => boolean | null;
+/**
+ * Gets the pressed state from toggle button widgets.
+ *
+ * @param widget - The widget to get the pressed state from
+ * @returns The pressed state or null if not applicable
+ */
+export declare const getWidgetPressedState: (widget: Gtk.Widget) => boolean | null;
 /**
  * Gets the expanded state from expander widgets.
  *
@@ -27,3 +34,10 @@ export declare const getWidgetCheckedState: (widget: Gtk.Widget) => boolean | nu
  * @returns The expanded state or null if not applicable
  */
 export declare const getWidgetExpandedState: (widget: Gtk.Widget) => boolean | null;
+/**
+ * Gets the selected state from selectable widgets.
+ *
+ * @param widget - The widget to get the selected state from
+ * @returns The selected state or null if not applicable
+ */
+export declare const getWidgetSelectedState: (widget: Gtk.Widget) => boolean | null;

package/dist/widget-text.js

@@ -5,9 +5,11 @@ const ROLES_WITH_INTERNAL_LABELS = new Set([
     Gtk.AccessibleRole.TOGGLE_BUTTON,
     Gtk.AccessibleRole.CHECKBOX,
     Gtk.AccessibleRole.RADIO,
+    Gtk.AccessibleRole.LIST_ITEM,
     Gtk.AccessibleRole.MENU_ITEM,
     Gtk.AccessibleRole.MENU_ITEM_CHECKBOX,
     Gtk.AccessibleRole.MENU_ITEM_RADIO,
+    Gtk.AccessibleRole.ROW,
     Gtk.AccessibleRole.TAB,
     Gtk.AccessibleRole.LINK,
 ]);
@@ -22,13 +24,40 @@ const isInternalLabel = (widget) => {
     const parentRole = parent.getAccessibleRole();
     if (!parentRole)
         return false;
-    return ROLES_WITH_INTERNAL_LABELS.has(parentRole);
+    if (ROLES_WITH_INTERNAL_LABELS.has(parentRole))
+        return true;
+    const labelText = getLabelText(widget);
+    if (!labelText)
+        return false;
+    let ancestor = parent;
+    while (ancestor) {
+        if (ancestor.getAccessibleRole === undefined)
+            return false;
+        const role = ancestor.getAccessibleRole();
+        if (role && ROLES_WITH_INTERNAL_LABELS.has(role)) {
+            return getDefaultText(ancestor) === labelText;
+        }
+        ancestor = ancestor.getParent();
+    }
+    return false;
 };
 const getLabelText = (widget) => {
     const asLabel = widget;
     const asInscription = widget;
     return asLabel.getLabel?.() ?? asInscription.getText?.() ?? null;
 };
+const getDefaultText = (widget) => {
+    if ("getLabel" in widget && typeof widget.getLabel === "function") {
+        return widget.getLabel() ?? null;
+    }
+    if ("getText" in widget && typeof widget.getText === "function") {
+        return widget.getText() ?? null;
+    }
+    if ("getTitle" in widget && typeof widget.getTitle === "function") {
+        return widget.getTitle() ?? null;
+    }
+    return getNativeInterface(widget, Gtk.Editable)?.getText() ?? null;
+};
 const collectChildLabels = (widget) => {
     const labels = [];
     let child = widget.getFirstChild();
@@ -58,32 +87,16 @@ export const getWidgetText = (widget) => {
     switch (role) {
         case Gtk.AccessibleRole.BUTTON:
         case Gtk.AccessibleRole.LINK:
-        case Gtk.AccessibleRole.TAB: {
-            const directLabel = widget.getLabel?.() ??
-                widget.getLabel?.() ??
-                widget.getLabel?.();
+        case Gtk.AccessibleRole.TAB:
+        case Gtk.AccessibleRole.MENU_ITEM:
+        case Gtk.AccessibleRole.MENU_ITEM_CHECKBOX:
+        case Gtk.AccessibleRole.MENU_ITEM_RADIO: {
+            const directLabel = getDefaultText(widget);
             if (directLabel)
                 return directLabel;
             const childLabels = collectChildLabels(widget);
             return childLabels.length > 0 ? childLabels.join(" ") : null;
         }
-        case Gtk.AccessibleRole.TOGGLE_BUTTON:
-            return widget.getLabel?.() ?? null;
-        case Gtk.AccessibleRole.CHECKBOX:
-        case Gtk.AccessibleRole.RADIO:
-            return widget.getLabel?.() ?? null;
-        case Gtk.AccessibleRole.LABEL:
-            return getLabelText(widget);
-        case Gtk.AccessibleRole.TEXT_BOX:
-        case Gtk.AccessibleRole.SEARCH_BOX:
-        case Gtk.AccessibleRole.SPIN_BUTTON:
-            return getNativeInterface(widget, Gtk.Editable)?.getText() ?? null;
-        case Gtk.AccessibleRole.GROUP:
-            return widget.getLabel?.() ?? null;
-        case Gtk.AccessibleRole.WINDOW:
-        case Gtk.AccessibleRole.DIALOG:
-        case Gtk.AccessibleRole.ALERT_DIALOG:
-            return widget.getTitle() ?? null;
         case Gtk.AccessibleRole.TAB_PANEL: {
             const parent = widget.getParent();
             if (parent) {
@@ -96,7 +109,7 @@ export const getWidgetText = (widget) => {
             return null;
         }
         default:
-            return null;
+            return getDefaultText(widget);
     }
 };
 /**
@@ -128,6 +141,19 @@ export const getWidgetCheckedState = (widget) => {
             return null;
     }
 };
+/**
+ * Gets the pressed state from toggle button widgets.
+ *
+ * @param widget - The widget to get the pressed state from
+ * @returns The pressed state or null if not applicable
+ */
+export const getWidgetPressedState = (widget) => {
+    const role = widget.getAccessibleRole();
+    if (role === Gtk.AccessibleRole.TOGGLE_BUTTON) {
+        return widget.getActive();
+    }
+    return null;
+};
 /**
  * Gets the expanded state from expander widgets.
  *
@@ -135,12 +161,24 @@ export const getWidgetCheckedState = (widget) => {
  * @returns The expanded state or null if not applicable
  */
 export const getWidgetExpandedState = (widget) => {
+    if (widget instanceof Gtk.Expander) {
+        return widget.getExpanded();
+    }
+    if (widget instanceof Gtk.TreeExpander) {
+        return widget.getListRow()?.getExpanded() ?? null;
+    }
+    return null;
+};
+/**
+ * Gets the selected state from selectable widgets.
+ *
+ * @param widget - The widget to get the selected state from
+ * @returns The selected state or null if not applicable
+ */
+export const getWidgetSelectedState = (widget) => {
     const role = widget.getAccessibleRole();
-    if (role === Gtk.AccessibleRole.BUTTON) {
-        const parent = widget.getParent();
-        if (!parent)
-            return null;
-        return parent.getExpanded?.() ?? null;
+    if (role === Gtk.AccessibleRole.ROW) {
+        return widget.isSelected();
     }
     return null;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/testing",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "description": "Testing utilities for GTKX applications",
   "keywords": [
     "gtkx",
@@ -13,13 +13,13 @@
     "linux",
     "desktop"
   ],
-  "homepage": "https://eugeniodepalo.github.io/gtkx",
+  "homepage": "https://gtkx.dev",
   "bugs": {
-    "url": "https://github.com/eugeniodepalo/gtkx/issues"
+    "url": "https://github.com/gtkx-org/gtkx/issues"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/eugeniodepalo/gtkx.git",
+    "url": "https://github.com/gtkx-org/gtkx.git",
     "directory": "packages/testing"
   },
   "license": "MPL-2.0",
@@ -36,13 +36,13 @@
     "dist"
   ],
   "dependencies": {
-    "@gtkx/react": "0.17.2",
-    "@gtkx/ffi": "0.17.2"
+    "@gtkx/ffi": "0.18.0",
+    "@gtkx/react": "0.18.0"
   },
   "devDependencies": {
     "@types/react-reconciler": "^0.33.0",
     "react-reconciler": "^0.33.0",
-    "@gtkx/vitest": "0.17.2"
+    "@gtkx/vitest": "0.18.0"
   },
   "scripts": {
     "build": "tsc -b && cp ../../README.md .",