@gtkx/testing 0.1.20 → 0.1.22

package/README.md

@@ -0,0 +1,208 @@
+<p align="center">
+  <img src="logo.svg" alt="GTKX Logo" width="128" height="128">
+</p>
+
+<h1 align="center">GTKX</h1>
+
+<p align="center">
+  <strong>Build native GTK4 desktop applications with React and TypeScript</strong>
+</p>
+
+<p align="center">
+  <a href="https://eugeniodepalo.github.io/gtkx">Documentation</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#examples">Examples</a>
+</p>
+
+---
+
+GTKX bridges React's component model with GTK4's native widget system. Write familiar React code and render it as native Linux desktop applications with full access to GTK4 widgets, signals, and styling.
+
+## Features
+
+- **React Components** — Use React hooks, state, and component patterns you already know
+- **Type-Safe** — Full TypeScript support with auto-generated types from GTK4 introspection data
+- **Native Performance** — Direct FFI bindings to GTK4 via Rust and libffi
+- **CSS-in-JS Styling** — Emotion-style `css` template literals for GTK widgets
+- **Testing Library** — Familiar `screen`, `userEvent`, and query APIs for testing components
+
+## Quick Start
+
+```bash
+# Install dependencies
+pnpm add @gtkx/react react
+
+# For styling (optional)
+pnpm add @gtkx/css
+
+# For testing (optional)
+pnpm add -D @gtkx/testing
+```
+
+Create your first app:
+
+```tsx
+// index.tsx
+import { render } from "@gtkx/react";
+import { App } from "./app.js";
+
+render(<App />, "org.example.MyApp");
+```
+
+```tsx
+// app.tsx
+import { ApplicationWindow, Box, Button, Label, quit } from "@gtkx/react";
+import { Orientation } from "@gtkx/ffi/gtk";
+import { useState } from "react";
+
+export const App = () => {
+  const [count, setCount] = useState(0);
+
+  return (
+    <ApplicationWindow
+      title="My App"
+      defaultWidth={400}
+      defaultHeight={300}
+      onCloseRequest={quit}
+    >
+      <Box orientation={Orientation.VERTICAL} spacing={12} margin={20}>
+        <Label.Root label={`Count: ${count}`} />
+        <Button
+          label="Increment"
+          onClicked={() => setCount((c) => c + 1)}
+        />
+      </Box>
+    </ApplicationWindow>
+  );
+};
+```
+
+Run with:
+
+```bash
+pnpm tsx index.tsx
+```
+
+## Styling
+
+Use `@gtkx/css` for CSS-in-JS styling:
+
+```tsx
+import { css } from "@gtkx/css";
+import { Button } from "@gtkx/react";
+
+const primaryButton = css`
+  padding: 16px 32px;
+  border-radius: 24px;
+  background: linear-gradient(135deg, #3584e4, #9141ac);
+  color: white;
+  font-weight: bold;
+`;
+
+const MyButton = () => (
+  <Button label="Click me" cssClasses={[primaryButton]} />
+);
+```
+
+GTK also provides built-in CSS classes like `suggested-action`, `destructive-action`, `card`, and `heading`.
+
+## Testing
+
+Use `@gtkx/testing` for Testing Library-style component tests:
+
+```tsx
+import { cleanup, render, screen, userEvent, fireEvent } from "@gtkx/testing";
+import { AccessibleRole } from "@gtkx/ffi/gtk";
+import { afterEach, describe, expect, it } from "vitest";
+import { App } from "./app.js";
+
+describe("Counter", () => {
+  afterEach(() => cleanup());
+
+  it("increments count when clicking button", async () => {
+    render(<App />);
+
+    const button = await screen.findByRole(AccessibleRole.BUTTON, {
+      name: "Increment",
+    });
+    await userEvent.click(button);
+
+    await screen.findByText("Count: 1");
+  });
+
+  it("can also use fireEvent for synchronous events", async () => {
+    render(<App />);
+
+    const button = await screen.findByRole(AccessibleRole.BUTTON, {
+      name: "Increment",
+    });
+    fireEvent.click(button);
+
+    await screen.findByText("Count: 1");
+  });
+});
+```
+
+### Available APIs
+
+**Queries** - Find elements in the rendered tree:
+- `getBy*` / `getAllBy*` - Throws if not found
+- `queryBy*` / `queryAllBy*` - Returns null/empty array if not found
+- `findBy*` / `findAllBy*` - Async, waits for element
+
+Query types: `ByRole`, `ByText`, `ByLabelText`, `ByTestId`
+
+**User Interactions**:
+- `userEvent.click(element)` - Simulate click
+- `userEvent.dblClick(element)` - Simulate double click
+- `userEvent.type(element, text)` - Type text into input
+- `userEvent.clear(element)` - Clear input text
+- `userEvent.setup()` - Create reusable instance
+
+**Low-level Events**:
+- `fireEvent(element, signalName)` - Emit any GTK signal
+- `fireEvent.click(element)` - Emit clicked signal
+- `fireEvent.activate(element)` - Emit activate signal
+
+**Utilities**:
+- `waitFor(callback)` - Wait for condition
+- `waitForElementToBeRemoved(element)` - Wait for element removal
+
+## Examples
+
+### Counter
+
+A minimal counter app demonstrating state management:
+
+```bash
+turbo start --filter=counter-example
+```
+
+### GTK4 Demo
+
+A comprehensive showcase of GTK4 widgets and features:
+
+```bash
+turbo start --filter=gtk4-demo
+```
+
+## Packages
+
+| Package | Description |
+|---------|-------------|
+| [@gtkx/react](packages/react) | React reconciler and JSX components |
+| [@gtkx/ffi](packages/ffi) | TypeScript FFI bindings for GTK4 |
+| [@gtkx/native](packages/native) | Rust native module for FFI bridge |
+| [@gtkx/css](packages/css) | CSS-in-JS styling for GTK widgets |
+| [@gtkx/testing](packages/testing) | Testing utilities for GTKX components |
+| [@gtkx/gir](packages/gir) | GObject Introspection parser for codegen |
+
+## Requirements
+
+- Node.js 20+
+- GTK4 development libraries
+- Linux (GTK4 is Linux-native)
+
+## License
+
+[MPL-2.0](LICENSE)

package/dist/fire-event.d.ts

@@ -0,0 +1,10 @@
+import type * as Gtk from "@gtkx/ffi/gtk";
+type FireEventFunction = {
+    (element: Gtk.Widget, signalName: string): void;
+    click: (element: Gtk.Widget) => void;
+    activate: (element: Gtk.Widget) => void;
+    toggled: (element: Gtk.Widget) => void;
+    changed: (element: Gtk.Widget) => void;
+};
+export declare const fireEvent: FireEventFunction;
+export {};

package/dist/fire-event.js

@@ -0,0 +1,24 @@
+import { call } from "@gtkx/native";
+import { getWidgetPtr } from "./widget.js";
+const emitSignal = (widget, signalName) => {
+    call("libgobject-2.0.so.0", "g_signal_emit_by_name", [
+        { type: { type: "gobject" }, value: getWidgetPtr(widget) },
+        { type: { type: "string" }, value: signalName },
+    ], { type: "undefined" });
+};
+export const fireEvent = Object.assign((element, signalName) => {
+    emitSignal(element, signalName);
+}, {
+    click: (element) => {
+        emitSignal(element, "clicked");
+    },
+    activate: (element) => {
+        emitSignal(element, "activate");
+    },
+    toggled: (element) => {
+        emitSignal(element, "toggled");
+    },
+    changed: (element) => {
+        emitSignal(element, "changed");
+    },
+});

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-export { findByLabelText, findByRole, findByText, getByLabelText, getByRole, getByText, } from "./queries.js";
-export { cleanup, render, setup, teardown } from "./render.js";
+export { fireEvent } from "./fire-event.js";
+export { findAllByLabelText, findAllByRole, findAllByTestId, findAllByText, findByLabelText, findByRole, findByTestId, findByText, getAllByLabelText, getAllByRole, getAllByTestId, getAllByText, getByLabelText, getByRole, getByTestId, getByText, queryAllByLabelText, queryAllByRole, queryAllByTestId, queryAllByText, queryByLabelText, queryByRole, queryByTestId, queryByText, } from "./queries.js";
+export { cleanup, render, teardown } from "./render.jsx";
 export { screen } from "./screen.js";
-export type { ByRoleOptions, RenderResult, WaitForOptions } from "./types.js";
+export type { ByRoleOptions, RenderOptions, RenderResult, TextMatchOptions, WaitForOptions, } from "./types.js";
+export type { UserEventInstance, UserEventOptions } from "./user-event.js";
 export { userEvent } from "./user-event.js";
-export { waitFor } from "./wait-for.js";
+export { waitFor, waitForElementToBeRemoved } from "./wait-for.js";

package/dist/index.js

@@ -1,5 +1,6 @@
-export { findByLabelText, findByRole, findByText, getByLabelText, getByRole, getByText, } from "./queries.js";
-export { cleanup, render, setup, teardown } from "./render.js";
+export { fireEvent } from "./fire-event.js";
+export { findAllByLabelText, findAllByRole, findAllByTestId, findAllByText, findByLabelText, findByRole, findByTestId, findByText, getAllByLabelText, getAllByRole, getAllByTestId, getAllByText, getByLabelText, getByRole, getByTestId, getByText, queryAllByLabelText, queryAllByRole, queryAllByTestId, queryAllByText, queryByLabelText, queryByRole, queryByTestId, queryByText, } from "./queries.js";
+export { cleanup, render, teardown } from "./render.jsx";
 export { screen } from "./screen.js";
 export { userEvent } from "./user-event.js";
-export { waitFor } from "./wait-for.js";
+export { waitFor, waitForElementToBeRemoved } from "./wait-for.js";

package/dist/queries.d.ts

@@ -1,11 +1,29 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
 import { AccessibleRole } from "@gtkx/ffi/gtk";
-import type { ByRoleOptions } from "./types.js";
+import type { ByRoleOptions, TextMatchOptions } from "./types.js";
 type Container = Gtk.Application | Gtk.Widget;
+export declare const getAllByRole: (container: Container, role: AccessibleRole, options?: ByRoleOptions) => Gtk.Widget[];
 export declare const getByRole: (container: Container, role: AccessibleRole, options?: ByRoleOptions) => Gtk.Widget;
-export declare const getByLabelText: (container: Container, text: string | RegExp) => Gtk.Widget;
-export declare const getByText: (container: Container, text: string | RegExp) => Gtk.Widget;
+export declare const queryAllByRole: (container: Container, role: AccessibleRole, options?: ByRoleOptions) => Gtk.Widget[];
+export declare const queryByRole: (container: Container, role: AccessibleRole, options?: ByRoleOptions) => Gtk.Widget | null;
+export declare const getAllByLabelText: (container: Container, text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget[];
+export declare const getByLabelText: (container: Container, text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget;
+export declare const queryAllByLabelText: (container: Container, text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget[];
+export declare const queryByLabelText: (container: Container, text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget | null;
+export declare const getAllByText: (container: Container, text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget[];
+export declare const getByText: (container: Container, text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget;
+export declare const queryAllByText: (container: Container, text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget[];
+export declare const queryByText: (container: Container, text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget | null;
+export declare const getAllByTestId: (container: Container, testId: string | RegExp, options?: TextMatchOptions) => Gtk.Widget[];
+export declare const getByTestId: (container: Container, testId: string | RegExp, options?: TextMatchOptions) => Gtk.Widget;
+export declare const queryAllByTestId: (container: Container, testId: string | RegExp, options?: TextMatchOptions) => Gtk.Widget[];
+export declare const queryByTestId: (container: Container, testId: string | RegExp, options?: TextMatchOptions) => Gtk.Widget | null;
 export declare const findByRole: (container: Container, role: AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget>;
-export declare const findByLabelText: (container: Container, text: string | RegExp) => Promise<Gtk.Widget>;
-export declare const findByText: (container: Container, text: string | RegExp) => Promise<Gtk.Widget>;
+export declare const findAllByRole: (container: Container, role: AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget[]>;
+export declare const findByLabelText: (container: Container, text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget>;
+export declare const findAllByLabelText: (container: Container, text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
+export declare const findByText: (container: Container, text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget>;
+export declare const findAllByText: (container: Container, text: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
+export declare const findByTestId: (container: Container, testId: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget>;
+export declare const findAllByTestId: (container: Container, testId: string | RegExp, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;
 export {};

package/dist/queries.js

@@ -2,14 +2,22 @@ import { AccessibleRole } from "@gtkx/ffi/gtk";
 import { call } from "@gtkx/native";
 import { findAll } from "./traversal.js";
 import { waitFor } from "./wait-for.js";
-const matchText = (actual, expected) => {
+import { getWidgetPtr } from "./widget.js";
+const DEFAULT_NORMALIZER = (text) => text.trim().replace(/\s+/g, " ");
+const normalizeText = (text, options) => {
+    const normalizer = options?.normalizer ?? DEFAULT_NORMALIZER;
+    return normalizer(text);
+};
+const matchText = (actual, expected, options) => {
     if (actual === null)
         return false;
-    return typeof expected === "string" ? actual === expected : expected.test(actual);
-};
-const getWidgetPtr = (widget) => {
-    const w = widget;
-    return w.ptr ?? null;
+    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);
+    }
+    return expected.test(normalizedActual);
 };
 const callGetter = (ptr, funcName) => {
     const result = call("libgtk-4.so.1", funcName, [{ type: { type: "gobject" }, value: ptr }], {
@@ -62,56 +70,215 @@ const getWidgetText = (widget) => {
             return null;
     }
 };
+const getWidgetTestId = (widget) => {
+    const ptr = getWidgetPtr(widget);
+    if (!ptr)
+        return null;
+    const result = call("libgtk-4.so.1", "gtk_widget_get_name", [{ type: { type: "gobject" }, value: ptr }], {
+        type: "string",
+        borrowed: true,
+    });
+    return result;
+};
+const getWidgetCheckedState = (widget) => {
+    const ptr = getWidgetPtr(widget);
+    if (!ptr)
+        return undefined;
+    const accessible = widget;
+    const role = accessible.getAccessibleRole();
+    if (role === AccessibleRole.CHECKBOX || role === AccessibleRole.RADIO) {
+        const result = call("libgtk-4.so.1", "gtk_check_button_get_active", [{ type: { type: "gobject" }, value: ptr }], {
+            type: "boolean",
+        });
+        return result === true;
+    }
+    if (role === AccessibleRole.TOGGLE_BUTTON) {
+        const result = call("libgtk-4.so.1", "gtk_toggle_button_get_active", [{ type: { type: "gobject" }, value: ptr }], { type: "boolean" });
+        return result === true;
+    }
+    return undefined;
+};
+const getWidgetExpandedState = (widget) => {
+    const ptr = getWidgetPtr(widget);
+    if (!ptr)
+        return undefined;
+    const accessible = widget;
+    const role = accessible.getAccessibleRole();
+    if (role === AccessibleRole.BUTTON) {
+        const expanderPtr = call("libgtk-4.so.1", "gtk_widget_get_parent", [{ type: { type: "gobject" }, value: ptr }], { type: "gobject" });
+        if (!expanderPtr)
+            return undefined;
+        const result = call("libgtk-4.so.1", "gtk_expander_get_expanded", [{ type: { type: "gobject" }, value: expanderPtr }], { type: "boolean" });
+        return result === true;
+    }
+    return undefined;
+};
+const matchByRoleOptions = (widget, options) => {
+    if (!options)
+        return true;
+    if (options.name !== undefined) {
+        const text = getWidgetText(widget);
+        if (!matchText(text, options.name, options))
+            return false;
+    }
+    if (options.checked !== undefined) {
+        const checked = getWidgetCheckedState(widget);
+        if (checked !== options.checked)
+            return false;
+    }
+    if (options.expanded !== undefined) {
+        const expanded = getWidgetExpandedState(widget);
+        if (expanded !== options.expanded)
+            return false;
+    }
+    return true;
+};
 const formatRole = (role) => AccessibleRole[role] ?? String(role);
-export const getByRole = (container, role, options) => {
+const formatByRoleError = (role, options) => {
+    const parts = [`role "${formatRole(role)}"`];
+    if (options?.name)
+        parts.push(`name "${options.name}"`);
+    if (options?.checked !== undefined)
+        parts.push(`checked=${options.checked}`);
+    if (options?.pressed !== undefined)
+        parts.push(`pressed=${options.pressed}`);
+    if (options?.selected !== undefined)
+        parts.push(`selected=${options.selected}`);
+    if (options?.expanded !== undefined)
+        parts.push(`expanded=${options.expanded}`);
+    if (options?.level !== undefined)
+        parts.push(`level=${options.level}`);
+    return parts.join(" and ");
+};
+export const getAllByRole = (container, role, options) => {
     const matches = findAll(container, (node) => {
         const accessible = node;
         if (accessible.getAccessibleRole() !== role)
             return false;
-        if (options?.name) {
-            const text = getWidgetText(node);
-            return matchText(text, options.name);
-        }
-        return true;
+        return matchByRoleOptions(node, options);
     });
-    const nameInfo = options?.name ? ` and name "${options.name}"` : "";
-    const [match, ...rest] = matches;
-    if (!match) {
-        throw new Error(`Unable to find element with role "${formatRole(role)}"${nameInfo}`);
+    if (matches.length === 0) {
+        throw new Error(`Unable to find any elements with ${formatByRoleError(role, options)}`);
     }
-    if (rest.length > 0) {
-        throw new Error(`Found ${matches.length} elements with role "${formatRole(role)}"${nameInfo}`);
+    return matches;
+};
+export const getByRole = (container, role, options) => {
+    const matches = getAllByRole(container, role, options);
+    if (matches.length > 1) {
+        throw new Error(`Found ${matches.length} elements with ${formatByRoleError(role, options)}`);
     }
-    return match;
+    return matches[0];
 };
-export const getByLabelText = (container, text) => {
+export const queryAllByRole = (container, role, options) => {
+    return findAll(container, (node) => {
+        const accessible = node;
+        if (accessible.getAccessibleRole() !== role)
+            return false;
+        return matchByRoleOptions(node, options);
+    });
+};
+export const queryByRole = (container, role, options) => {
+    const matches = queryAllByRole(container, role, options);
+    if (matches.length > 1) {
+        throw new Error(`Found ${matches.length} elements with ${formatByRoleError(role, options)}`);
+    }
+    return matches[0] ?? null;
+};
+export const getAllByLabelText = (container, text, options) => {
     const matches = findAll(container, (node) => {
         const widgetText = getWidgetText(node);
-        return matchText(widgetText, text);
+        return matchText(widgetText, text, options);
     });
-    const [match, ...rest] = matches;
-    if (!match) {
-        throw new Error(`Unable to find element with label text "${text}"`);
+    if (matches.length === 0) {
+        throw new Error(`Unable to find any elements with label text "${text}"`);
+    }
+    return matches;
+};
+export const getByLabelText = (container, text, options) => {
+    const matches = getAllByLabelText(container, text, options);
+    if (matches.length > 1) {
+        throw new Error(`Found ${matches.length} elements with label text "${text}"`);
     }
-    if (rest.length > 0) {
+    return matches[0];
+};
+export const queryAllByLabelText = (container, text, options) => {
+    return findAll(container, (node) => {
+        const widgetText = getWidgetText(node);
+        return matchText(widgetText, text, options);
+    });
+};
+export const queryByLabelText = (container, text, options) => {
+    const matches = queryAllByLabelText(container, text, options);
+    if (matches.length > 1) {
         throw new Error(`Found ${matches.length} elements with label text "${text}"`);
     }
-    return match;
+    return matches[0] ?? null;
 };
-export const getByText = (container, text) => {
+export const getAllByText = (container, text, options) => {
     const matches = findAll(container, (node) => {
         const widgetText = getWidgetText(node);
-        return matchText(widgetText, text);
+        return matchText(widgetText, text, options);
     });
-    const [match, ...rest] = matches;
-    if (!match) {
-        throw new Error(`Unable to find element with text "${text}"`);
+    if (matches.length === 0) {
+        throw new Error(`Unable to find any elements with text "${text}"`);
     }
-    if (rest.length > 0) {
+    return matches;
+};
+export const getByText = (container, text, options) => {
+    const matches = getAllByText(container, text, options);
+    if (matches.length > 1) {
         throw new Error(`Found ${matches.length} elements with text "${text}"`);
     }
-    return match;
+    return matches[0];
+};
+export const queryAllByText = (container, text, options) => {
+    return findAll(container, (node) => {
+        const widgetText = getWidgetText(node);
+        return matchText(widgetText, text, options);
+    });
+};
+export const queryByText = (container, text, options) => {
+    const matches = queryAllByText(container, text, options);
+    if (matches.length > 1) {
+        throw new Error(`Found ${matches.length} elements with text "${text}"`);
+    }
+    return matches[0] ?? null;
+};
+export const getAllByTestId = (container, testId, options) => {
+    const matches = findAll(container, (node) => {
+        const widgetTestId = getWidgetTestId(node);
+        return matchText(widgetTestId, testId, options);
+    });
+    if (matches.length === 0) {
+        throw new Error(`Unable to find any elements with test id "${testId}"`);
+    }
+    return matches;
+};
+export const getByTestId = (container, testId, options) => {
+    const matches = getAllByTestId(container, testId, options);
+    if (matches.length > 1) {
+        throw new Error(`Found ${matches.length} elements with test id "${testId}"`);
+    }
+    return matches[0];
+};
+export const queryAllByTestId = (container, testId, options) => {
+    return findAll(container, (node) => {
+        const widgetTestId = getWidgetTestId(node);
+        return matchText(widgetTestId, testId, options);
+    });
+};
+export const queryByTestId = (container, testId, options) => {
+    const matches = queryAllByTestId(container, testId, options);
+    if (matches.length > 1) {
+        throw new Error(`Found ${matches.length} elements with test id "${testId}"`);
+    }
+    return matches[0] ?? null;
 };
 export const findByRole = async (container, role, options) => waitFor(() => getByRole(container, role, options));
-export const findByLabelText = async (container, text) => waitFor(() => getByLabelText(container, text));
-export const findByText = async (container, text) => waitFor(() => getByText(container, text));
+export const findAllByRole = async (container, role, options) => waitFor(() => getAllByRole(container, role, options));
+export const findByLabelText = async (container, text, options) => waitFor(() => getByLabelText(container, text, options));
+export const findAllByLabelText = async (container, text, options) => waitFor(() => getAllByLabelText(container, text, options));
+export const findByText = async (container, text, options) => waitFor(() => getByText(container, text, options));
+export const findAllByText = async (container, text, options) => waitFor(() => getAllByText(container, text, options));
+export const findByTestId = async (container, testId, options) => waitFor(() => getByTestId(container, testId, options));
+export const findAllByTestId = async (container, testId, options) => waitFor(() => getAllByTestId(container, testId, options));

package/dist/render.d.ts

@@ -1,6 +1,5 @@
 import type { ReactNode } from "react";
-import type { RenderResult } from "./types.js";
-export declare const setup: () => void;
-export declare const render: (element: ReactNode) => RenderResult;
+import type { RenderOptions, RenderResult } from "./types.js";
+export declare const render: (element: ReactNode, options?: RenderOptions) => RenderResult;
 export declare const cleanup: () => void;
 export declare const teardown: () => void;

package/dist/render.js

@@ -1,20 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
 import { start, stop } from "@gtkx/ffi";
 import * as Gtk from "@gtkx/ffi/gtk";
 import { reconciler } from "@gtkx/react";
-import { beforeAll } from "vitest";
 import * as queries from "./queries.js";
 import { setScreenRoot } from "./screen.js";
 const APP_ID = "com.gtkx.testing";
 let app = null;
 let container = null;
-export const setup = () => {
-    beforeAll(() => {
-        if (!app) {
-            app = start(APP_ID);
-            reconciler.setApp(app);
-        }
-    });
-};
 const hasGetLabel = (widget) => typeof widget.getLabel === "function";
 const printWidgetTree = (root, indent = 0) => {
     const accessible = root;
@@ -65,21 +57,48 @@ const ensureInitialized = () => {
     }
     return { app, container };
 };
-export const render = (element) => {
+const wrapElement = (element, Wrapper) => {
+    if (!Wrapper)
+        return element;
+    return _jsx(Wrapper, { children: element });
+};
+export const render = (element, options) => {
     const { app: application, container: fiberRoot } = ensureInitialized();
     const instance = reconciler.getInstance();
-    updateSync(instance, element, fiberRoot);
+    const wrappedElement = wrapElement(element, options?.wrapper);
+    updateSync(instance, wrappedElement, fiberRoot);
     setScreenRoot(application);
     return {
         container: application,
-        getByRole: (role, options) => queries.getByRole(application, role, options),
-        getByLabelText: (text) => queries.getByLabelText(application, text),
-        getByText: (text) => queries.getByText(application, text),
-        findByRole: (role, options) => queries.findByRole(application, role, options),
-        findByLabelText: (text) => queries.findByLabelText(application, text),
-        findByText: (text) => queries.findByText(application, text),
+        getByRole: (role, opts) => queries.getByRole(application, role, opts),
+        getByLabelText: (text, opts) => queries.getByLabelText(application, text, opts),
+        getByText: (text, opts) => queries.getByText(application, text, opts),
+        getByTestId: (testId, opts) => queries.getByTestId(application, testId, opts),
+        queryByRole: (role, opts) => queries.queryByRole(application, role, opts),
+        queryByLabelText: (text, opts) => queries.queryByLabelText(application, text, opts),
+        queryByText: (text, opts) => queries.queryByText(application, text, opts),
+        queryByTestId: (testId, opts) => queries.queryByTestId(application, testId, opts),
+        getAllByRole: (role, opts) => queries.getAllByRole(application, role, opts),
+        getAllByLabelText: (text, opts) => queries.getAllByLabelText(application, text, opts),
+        getAllByText: (text, opts) => queries.getAllByText(application, text, opts),
+        getAllByTestId: (testId, opts) => queries.getAllByTestId(application, testId, opts),
+        queryAllByRole: (role, opts) => queries.queryAllByRole(application, role, opts),
+        queryAllByLabelText: (text, opts) => queries.queryAllByLabelText(application, text, opts),
+        queryAllByText: (text, opts) => queries.queryAllByText(application, text, opts),
+        queryAllByTestId: (testId, opts) => queries.queryAllByTestId(application, testId, opts),
+        findByRole: (role, opts) => queries.findByRole(application, role, opts),
+        findByLabelText: (text, opts) => queries.findByLabelText(application, text, opts),
+        findByText: (text, opts) => queries.findByText(application, text, opts),
+        findByTestId: (testId, opts) => queries.findByTestId(application, testId, opts),
+        findAllByRole: (role, opts) => queries.findAllByRole(application, role, opts),
+        findAllByLabelText: (text, opts) => queries.findAllByLabelText(application, text, opts),
+        findAllByText: (text, opts) => queries.findAllByText(application, text, opts),
+        findAllByTestId: (testId, opts) => queries.findAllByTestId(application, testId, opts),
         unmount: () => updateSync(instance, null, fiberRoot),
-        rerender: (newElement) => updateSync(instance, newElement, fiberRoot),
+        rerender: (newElement) => {
+            const wrapped = wrapElement(newElement, options?.wrapper);
+            updateSync(instance, wrapped, fiberRoot);
+        },
         debug: () => {
             const activeWindow = application.getActiveWindow();
             if (activeWindow) {

package/dist/screen.d.ts

@@ -1,13 +1,31 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
 import type { AccessibleRole } from "@gtkx/ffi/gtk";
-import type { ByRoleOptions } from "./types.js";
+import type { ByRoleOptions, TextMatchOptions } from "./types.js";
 export declare const setScreenRoot: (root: Gtk.Application | null) => void;
 export declare const screen: {
     getByRole: (role: AccessibleRole, options?: ByRoleOptions) => Gtk.Widget;
-    getByLabelText: (text: string | RegExp) => Gtk.Widget;
-    getByText: (text: string | RegExp) => Gtk.Widget;
+    getByLabelText: (text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget;
+    getByText: (text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget;
+    getByTestId: (testId: string | RegExp, options?: TextMatchOptions) => Gtk.Widget;
+    queryByRole: (role: AccessibleRole, options?: ByRoleOptions) => Gtk.Widget | null;
+    queryByLabelText: (text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget | null;
+    queryByText: (text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget | null;
+    queryByTestId: (testId: string | RegExp, options?: TextMatchOptions) => Gtk.Widget | null;
+    getAllByRole: (role: AccessibleRole, options?: ByRoleOptions) => Gtk.Widget[];
+    getAllByLabelText: (text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget[];
+    getAllByText: (text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget[];
+    getAllByTestId: (testId: string | RegExp, options?: TextMatchOptions) => Gtk.Widget[];
+    queryAllByRole: (role: AccessibleRole, options?: ByRoleOptions) => Gtk.Widget[];
+    queryAllByLabelText: (text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget[];
+    queryAllByText: (text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget[];
+    queryAllByTestId: (testId: string | RegExp, options?: TextMatchOptions) => Gtk.Widget[];
     findByRole: (role: AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget>;
-    findByLabelText: (text: string | RegExp) => Promise<Gtk.Widget>;
-    findByText: (text: string | RegExp) => 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>;
+    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[]>;
     debug: () => void;
 };

package/dist/screen.js

@@ -11,11 +11,29 @@ const getRoot = () => {
 };
 export const screen = {
     getByRole: (role, options) => queries.getByRole(getRoot(), role, options),
-    getByLabelText: (text) => queries.getByLabelText(getRoot(), text),
-    getByText: (text) => queries.getByText(getRoot(), text),
+    getByLabelText: (text, options) => queries.getByLabelText(getRoot(), text, options),
+    getByText: (text, options) => queries.getByText(getRoot(), text, options),
+    getByTestId: (testId, options) => queries.getByTestId(getRoot(), testId, options),
+    queryByRole: (role, options) => queries.queryByRole(getRoot(), role, options),
+    queryByLabelText: (text, options) => queries.queryByLabelText(getRoot(), text, options),
+    queryByText: (text, options) => queries.queryByText(getRoot(), text, options),
+    queryByTestId: (testId, options) => queries.queryByTestId(getRoot(), testId, options),
+    getAllByRole: (role, options) => queries.getAllByRole(getRoot(), role, options),
+    getAllByLabelText: (text, options) => queries.getAllByLabelText(getRoot(), text, options),
+    getAllByText: (text, options) => queries.getAllByText(getRoot(), text, options),
+    getAllByTestId: (testId, options) => queries.getAllByTestId(getRoot(), testId, options),
+    queryAllByRole: (role, options) => queries.queryAllByRole(getRoot(), role, options),
+    queryAllByLabelText: (text, options) => queries.queryAllByLabelText(getRoot(), text, options),
+    queryAllByText: (text, options) => queries.queryAllByText(getRoot(), text, options),
+    queryAllByTestId: (testId, options) => queries.queryAllByTestId(getRoot(), testId, options),
     findByRole: (role, options) => queries.findByRole(getRoot(), role, options),
-    findByLabelText: (text) => queries.findByLabelText(getRoot(), text),
-    findByText: (text) => queries.findByText(getRoot(), text),
+    findByLabelText: (text, options) => queries.findByLabelText(getRoot(), text, options),
+    findByText: (text, options) => queries.findByText(getRoot(), text, options),
+    findByTestId: (testId, options) => queries.findByTestId(getRoot(), testId, options),
+    findAllByRole: (role, options) => queries.findAllByRole(getRoot(), role, options),
+    findAllByLabelText: (text, options) => queries.findAllByLabelText(getRoot(), text, options),
+    findAllByText: (text, options) => queries.findAllByText(getRoot(), text, options),
+    findAllByTestId: (testId, options) => queries.findAllByTestId(getRoot(), testId, options),
     debug: () => {
         console.log("Screen debug - root:", getRoot());
     },

package/dist/traversal.d.ts

@@ -1,5 +1,4 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
 type Container = Gtk.Application | Gtk.Widget;
-export declare const traverse: (container: Container) => Generator<Gtk.Widget>;
 export declare const findAll: (container: Container, predicate: (node: Gtk.Widget) => boolean) => Gtk.Widget[];
 export {};

package/dist/traversal.js

@@ -13,7 +13,7 @@ const traverseApplication = function* (app) {
         yield* traverseWidgetTree(window);
     }
 };
-export const traverse = function* (container) {
+const traverse = function* (container) {
     if (isApplication(container)) {
         yield* traverseApplication(container);
     }

package/dist/types.d.ts

@@ -1,21 +1,54 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
 import type { AccessibleRole } from "@gtkx/ffi/gtk";
-import type { ReactNode } from "react";
-export interface ByRoleOptions {
+import type { ComponentType, ReactNode } from "react";
+export interface TextMatchOptions {
+    exact?: boolean;
+    normalizer?: (text: string) => string;
+}
+export interface ByRoleOptions extends TextMatchOptions {
     name?: string | RegExp;
+    checked?: boolean;
+    pressed?: boolean;
+    selected?: boolean;
+    expanded?: boolean;
+    level?: number;
 }
 export interface WaitForOptions {
     timeout?: number;
     interval?: number;
+    onTimeout?: (error: Error) => Error;
+}
+export interface RenderOptions {
+    wrapper?: ComponentType<{
+        children: ReactNode;
+    }>;
 }
 export interface RenderResult {
     container: Gtk.Application;
     getByRole: (role: AccessibleRole, options?: ByRoleOptions) => Gtk.Widget;
-    getByLabelText: (text: string | RegExp) => Gtk.Widget;
-    getByText: (text: string | RegExp) => Gtk.Widget;
+    getByLabelText: (text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget;
+    getByText: (text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget;
+    getByTestId: (testId: string | RegExp, options?: TextMatchOptions) => Gtk.Widget;
+    queryByRole: (role: AccessibleRole, options?: ByRoleOptions) => Gtk.Widget | null;
+    queryByLabelText: (text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget | null;
+    queryByText: (text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget | null;
+    queryByTestId: (testId: string | RegExp, options?: TextMatchOptions) => Gtk.Widget | null;
+    getAllByRole: (role: AccessibleRole, options?: ByRoleOptions) => Gtk.Widget[];
+    getAllByLabelText: (text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget[];
+    getAllByText: (text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget[];
+    getAllByTestId: (testId: string | RegExp, options?: TextMatchOptions) => Gtk.Widget[];
+    queryAllByRole: (role: AccessibleRole, options?: ByRoleOptions) => Gtk.Widget[];
+    queryAllByLabelText: (text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget[];
+    queryAllByText: (text: string | RegExp, options?: TextMatchOptions) => Gtk.Widget[];
+    queryAllByTestId: (testId: string | RegExp, options?: TextMatchOptions) => Gtk.Widget[];
     findByRole: (role: AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget>;
-    findByLabelText: (text: string | RegExp) => Promise<Gtk.Widget>;
-    findByText: (text: string | RegExp) => 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>;
+    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[]>;
     unmount: () => void;
     rerender: (element: ReactNode) => void;
     debug: () => void;

package/dist/user-event.d.ts

@@ -1,5 +1,17 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
+export interface UserEventOptions {
+    delay?: number;
+}
+export interface UserEventInstance {
+    click: (element: Gtk.Widget) => Promise<void>;
+    dblClick: (element: Gtk.Widget) => Promise<void>;
+    type: (element: Gtk.Widget, text: string) => Promise<void>;
+    clear: (element: Gtk.Widget) => Promise<void>;
+}
 export declare const userEvent: {
+    setup: (options?: UserEventOptions) => UserEventInstance;
     click: (element: Gtk.Widget) => Promise<void>;
+    dblClick: (element: Gtk.Widget) => Promise<void>;
     type: (element: Gtk.Widget, text: string) => Promise<void>;
+    clear: (element: Gtk.Widget) => Promise<void>;
 };

package/dist/user-event.js

@@ -1,20 +1,44 @@
 import { call } from "@gtkx/native";
-const hasSetText = (widget) => typeof widget.setText === "function";
-const hasGetText = (widget) => typeof widget.getText === "function";
-const hasPtr = (widget) => widget.ptr !== undefined;
+import { getWidgetPtr, hasGetText, hasSetText } from "./widget.js";
 const emitSignal = (widget, signalName) => {
-    if (!hasPtr(widget)) {
-        throw new Error("Widget does not have a ptr property");
-    }
     call("libgobject-2.0.so.0", "g_signal_emit_by_name", [
-        { type: { type: "gobject" }, value: widget.ptr },
+        { type: { type: "gobject" }, value: getWidgetPtr(widget) },
         { type: { type: "string" }, value: signalName },
     ], { type: "undefined" });
 };
+const createUserEventInstance = (_options) => {
+    return {
+        click: async (element) => {
+            emitSignal(element, "clicked");
+        },
+        dblClick: async (element) => {
+            emitSignal(element, "clicked");
+            emitSignal(element, "clicked");
+        },
+        type: async (element, text) => {
+            if (!hasSetText(element)) {
+                throw new Error("Cannot type into element: no setText method available");
+            }
+            const currentText = hasGetText(element) ? element.getText() : "";
+            element.setText(currentText + text);
+        },
+        clear: async (element) => {
+            if (!hasSetText(element)) {
+                throw new Error("Cannot clear element: no setText method available");
+            }
+            element.setText("");
+        },
+    };
+};
 export const userEvent = {
+    setup: (options) => createUserEventInstance(options),
     click: async (element) => {
         emitSignal(element, "clicked");
     },
+    dblClick: async (element) => {
+        emitSignal(element, "clicked");
+        emitSignal(element, "clicked");
+    },
     type: async (element, text) => {
         if (!hasSetText(element)) {
             throw new Error("Cannot type into element: no setText method available");
@@ -22,4 +46,10 @@ export const userEvent = {
         const currentText = hasGetText(element) ? element.getText() : "";
         element.setText(currentText + text);
     },
+    clear: async (element) => {
+        if (!hasSetText(element)) {
+            throw new Error("Cannot clear element: no setText method available");
+        }
+        element.setText("");
+    },
 };

package/dist/wait-for.d.ts

@@ -1,2 +1,6 @@
+import type * as Gtk from "@gtkx/ffi/gtk";
 import type { WaitForOptions } from "./types.js";
 export declare const waitFor: <T>(callback: () => T, options?: WaitForOptions) => Promise<T>;
+type ElementOrCallback = Gtk.Widget | (() => Gtk.Widget | null);
+export declare const waitForElementToBeRemoved: (elementOrCallback: ElementOrCallback, options?: WaitForOptions) => Promise<void>;
+export {};

package/dist/wait-for.js

@@ -1,7 +1,7 @@
 const DEFAULT_TIMEOUT = 1000;
 const DEFAULT_INTERVAL = 50;
 export const waitFor = async (callback, options) => {
-    const { timeout = DEFAULT_TIMEOUT, interval = DEFAULT_INTERVAL } = options ?? {};
+    const { timeout = DEFAULT_TIMEOUT, interval = DEFAULT_INTERVAL, onTimeout } = options ?? {};
     const startTime = Date.now();
     let lastError = null;
     while (Date.now() - startTime < timeout) {
@@ -13,5 +13,47 @@ export const waitFor = async (callback, options) => {
             await new Promise((resolve) => setTimeout(resolve, interval));
         }
     }
-    throw new Error(`Timed out after ${timeout}ms. Last error: ${lastError?.message}`);
+    const timeoutError = new Error(`Timed out after ${timeout}ms. Last error: ${lastError?.message}`);
+    if (onTimeout) {
+        throw onTimeout(timeoutError);
+    }
+    throw timeoutError;
+};
+const getElement = (elementOrCallback) => {
+    if (typeof elementOrCallback === "function") {
+        return elementOrCallback();
+    }
+    return elementOrCallback;
+};
+const isElementRemoved = (element) => {
+    if (element === null)
+        return true;
+    try {
+        const parent = element.getParent();
+        return parent === null;
+    }
+    catch {
+        return true;
+    }
+};
+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.");
+    }
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout) {
+        const element = getElement(elementOrCallback);
+        if (isElementRemoved(element)) {
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+    const timeoutError = new Error(`Timed out after ${timeout}ms waiting for element to be removed.`);
+    if (onTimeout) {
+        throw onTimeout(timeoutError);
+    }
+    throw timeoutError;
 };

package/dist/widget.d.ts

@@ -0,0 +1,11 @@
+import type * as Gtk from "@gtkx/ffi/gtk";
+export declare const getWidgetPtr: (widget: Gtk.Widget) => unknown;
+type WidgetWithSetText = {
+    setText: (text: string) => void;
+};
+type WidgetWithGetText = {
+    getText: () => string;
+};
+export declare const hasSetText: (widget: unknown) => widget is WidgetWithSetText;
+export declare const hasGetText: (widget: unknown) => widget is WidgetWithGetText;
+export {};

package/dist/widget.js

@@ -0,0 +1,5 @@
+export const getWidgetPtr = (widget) => {
+    return widget.ptr;
+};
+export const hasSetText = (widget) => typeof widget.setText === "function";
+export const hasGetText = (widget) => typeof widget.getText === "function";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/testing",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "Testing utilities for GTKX applications",
   "keywords": [
     "gtk",
@@ -36,15 +36,15 @@
     "dist"
   ],
   "dependencies": {
-    "@gtkx/ffi": "0.1.20",
-    "@gtkx/native": "0.1.20",
-    "@gtkx/react": "0.1.20"
+    "@gtkx/ffi": "0.1.22",
+    "@gtkx/native": "0.1.22",
+    "@gtkx/react": "0.1.22"
   },
   "peerDependencies": {
     "react": "^19"
   },
   "scripts": {
-    "build": "tsc -b",
-    "test": "xvfb-run -a vitest run"
+    "build": "tsc -b && cp ../../README.md .",
+    "test": "GDK_BACKEND=x11 xvfb-run -a vitest run"
   }
 }