@gtkx/testing 0.9.4 → 0.10.0

package/README.md

@@ -1,47 +1,43 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/eugeniodepalo/gtkx/HEAD/logo.svg" alt="GTKX Logo" width="128" height="128">
+  <img src="https://raw.githubusercontent.com/eugeniodepalo/gtkx/main/logo.svg" alt="GTKX" width="80" height="80">
 </p>
 
 <h1 align="center">GTKX</h1>
 
 <p align="center">
-  <strong>Build native GTK4 desktop apps with React</strong>
+  <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> ·
-  <a href="#contributing">Contributing</a>
+  <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>
 </p>
 
 ---
 
-GTKX lets you build native Linux desktop applications using React and TypeScript. Write familiar React code that renders as native GTK4 widgets—no Electron, no web views.
-
-## Features
-
-- **React** — Hooks, state, props, and components you already know
-- **HMR** — Edit code and see changes instantly via Vite
-- **Native** — Direct FFI bindings to GTK4 via Rust and libffi
-- **CLI** — `npx @gtkx/cli@latest create` scaffolds a ready-to-go project
-- **CSS-in-JS** — Emotion-style `css` template literals for GTK styling
-- **Testing** — Testing Library-style `screen`, `userEvent`, and queries
+GTKX lets you write Linux desktop applications using React. Your components render as native GTK4 widgets through a Rust FFI bridge—no webviews, no Electron, just native performance with the developer experience you already know.
 
 ## Quick Start
 
 ```bash
-npx @gtkx/cli@latest create my-app
+npx @gtkx/cli create my-app
 cd my-app
 npm run dev
 ```
 
-Edit your code and see changes instantly—no restart needed.
-
-### Example
+## Example
 
 ```tsx
-import { render, ApplicationWindow, Box, Button, quit } from "@gtkx/react";
+import {
+  GtkApplicationWindow,
+  GtkBox,
+  GtkButton,
+  GtkLabel,
+  quit,
+  render,
+} from "@gtkx/react";
 import * as Gtk from "@gtkx/ffi/gtk";
 import { useState } from "react";
 
@@ -49,67 +45,59 @@ const App = () => {
   const [count, setCount] = useState(0);
 
   return (
-    <ApplicationWindow title="Counter" onCloseRequest={quit}>
-      <Box orientation={Gtk.Orientation.VERTICAL} spacing={12}>
-        {`Count: ${count}`}
-        <Button label="Increment" onClicked={() => setCount((c) => c + 1)} />
-      </Box>
-    </ApplicationWindow>
+    <GtkApplicationWindow
+      title="Counter"
+      defaultWidth={300}
+      defaultHeight={200}
+      onCloseRequest={quit}
+    >
+      <GtkBox
+        orientation={Gtk.Orientation.VERTICAL}
+        spacing={20}
+        valign={Gtk.Align.CENTER}
+      >
+        <GtkLabel label={`Count: ${count}`} cssClasses={["title-1"]} />
+        <GtkButton label="Increment" onClicked={() => setCount((c) => c + 1)} />
+      </GtkBox>
+    </GtkApplicationWindow>
   );
 };
 
-render(<App />, "org.example.Counter");
+render(<App />, "com.example.counter");
 ```
 
-## Styling
-
-```tsx
-import { css } from "@gtkx/css";
-import { Button } from "@gtkx/react";
-
-const primary = css`
-  padding: 16px 32px;
-  border-radius: 24px;
-  background: linear-gradient(135deg, #3584e4, #9141ac);
-  color: white;
-`;
-
-<Button label="Click me" cssClasses={[primary]} />;
-```
-
-## Testing
-
-```tsx
-import { cleanup, render, screen, userEvent } from "@gtkx/testing";
-import * as Gtk from "@gtkx/ffi/gtk";
-
-afterEach(() => cleanup());
+## Features
 
-test("increments count", async () => {
-  await render(<App />);
+- **React 19** — Hooks, concurrent features, and the component model you know
+- **Native GTK4 widgets** — Real native controls, not web components in a webview
+- **Adwaita support** — Modern GNOME styling with Libadwaita components
+- **Hot Module Replacement** — Fast refresh during development
+- **TypeScript first** — Full type safety with auto-generated bindings
+- **CSS-in-JS styling** — Familiar styling patterns adapted for GTK
+- **Testing utilities** — Component testing similar to Testing Library
 
-  const button = await screen.findByRole(Gtk.AccessibleRole.BUTTON, {
-    name: "Increment",
-  });
+## Examples
 
-  await userEvent.click(button);
+Explore complete applications in the [`examples/`](./examples) directory:
 
-  await screen.findByText("Count: 1");
-});
-```
+- **[gtk-demo](./examples/gtk-demo)** — Full replica of the official GTK demo app
+- **[hello-world](./examples/hello-world)** — Minimal application showing a counter
+- **[todo](./examples/todo)** — Full-featured todo application with Adwaita styling and testing
+- **[deploying](./examples/deploying)** — Example of packaging and distributing a GTKX app
 
-## Requirements
+## Documentation
 
-- Node.js 20+ (Deno support experimental)
-- GTK4 Runtime (`gtk4` on Fedora, `libgtk-4-1` on Ubuntu)
+Visit [https://eugeniodepalo.github.io/gtkx](https://eugeniodepalo.github.io/gtkx/) for the full documentation.
 
 ## Contributing
 
-We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+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).
+
+## Community
 
-- [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)
+- [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
 
 ## License
 
-[MPL-2.0](LICENSE)
+[MPL-2.0](./LICENSE)

package/dist/fire-event.d.ts

@@ -1,17 +1,23 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
 import type { Arg } from "@gtkx/native";
 /**
- * Low-level utility to emit GTK signals on widgets. For common interactions
- * like clicking or typing, use `userEvent` instead.
+ * Emits a GTK signal on a widget.
  *
- * @param element - The GTK widget to emit the signal on
- * @param signalName - The name of the signal to emit
- * @param args - Additional arguments to pass to the signal handlers
+ * Low-level utility for triggering signals directly. Prefer {@link userEvent}
+ * for common interactions like clicking and typing.
  *
- * @example
- * await fireEvent(button, "clicked")
+ * @param element - The widget to emit the signal on
+ * @param signalName - GTK signal name (e.g., "clicked", "activate")
+ * @param args - Additional signal arguments
  *
  * @example
- * await fireEvent(widget, "custom-signal", { type: { type: "int", size: 32 }, value: 42 })
+ * ```tsx
+ * import { fireEvent } from "@gtkx/testing";
+ *
+ * // Emit custom signal
+ * await fireEvent(widget, "my-custom-signal");
+ * ```
+ *
+ * @see {@link userEvent} for high-level user interactions
  */
 export declare const fireEvent: (element: Gtk.Widget, signalName: string, ...args: Arg[]) => Promise<void>;

package/dist/fire-event.js

@@ -1,18 +1,24 @@
 import { call } from "@gtkx/native";
 import { tick } from "./timing.js";
 /**
- * Low-level utility to emit GTK signals on widgets. For common interactions
- * like clicking or typing, use `userEvent` instead.
+ * Emits a GTK signal on a widget.
  *
- * @param element - The GTK widget to emit the signal on
- * @param signalName - The name of the signal to emit
- * @param args - Additional arguments to pass to the signal handlers
+ * Low-level utility for triggering signals directly. Prefer {@link userEvent}
+ * for common interactions like clicking and typing.
  *
- * @example
- * await fireEvent(button, "clicked")
+ * @param element - The widget to emit the signal on
+ * @param signalName - GTK signal name (e.g., "clicked", "activate")
+ * @param args - Additional signal arguments
  *
  * @example
- * await fireEvent(widget, "custom-signal", { type: { type: "int", size: 32 }, value: 42 })
+ * ```tsx
+ * import { fireEvent } from "@gtkx/testing";
+ *
+ * // Emit custom signal
+ * await fireEvent(widget, "my-custom-signal");
+ * ```
+ *
+ * @see {@link userEvent} for high-level user interactions
  */
 export const fireEvent = async (element, signalName, ...args) => {
     call("libgobject-2.0.so.0", "g_signal_emit_by_name", [{ type: { type: "gobject" }, value: element.id }, { type: { type: "string" }, value: signalName }, ...args], { type: "undefined" });

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 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 { cleanup, render } from "./render.js";
 export { screen } from "./screen.js";
+export { tick } from "./timing.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";

package/dist/index.js

@@ -1,7 +1,8 @@
 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 { cleanup, render } from "./render.js";
 export { screen } from "./screen.js";
+export { tick } from "./timing.js";
 export { userEvent } from "./user-event.js";
 export { waitFor, waitForElementToBeRemoved } from "./wait-for.js";
 export { within } from "./within.js";

package/dist/queries.d.ts

@@ -2,66 +2,101 @@ import * as Gtk from "@gtkx/ffi/gtk";
 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.
+ * Finds a single element by accessible role.
+ *
+ * Waits for the element to appear, throwing if not found within timeout.
+ *
  * @param container - The container to search within
- * @param role - The accessible role to match
- * @param options - Additional filtering options (name, checked, expanded)
+ * @param role - The GTK accessible role to match
+ * @param options - Query options including name, state filters, and timeout
  * @returns Promise resolving to the matching widget
+ *
+ * @example
+ * ```tsx
+ * const button = await findByRole(container, Gtk.AccessibleRole.BUTTON, { name: "Submit" });
+ * ```
  */
 export declare const findByRole: (container: Container, role: Gtk.AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget>;
 /**
- * Waits for and finds all widgets matching the specified accessible role.
+ * Finds all elements matching an accessible role.
+ *
  * @param container - The container to search within
- * @param role - The accessible role to match
- * @param options - Additional filtering options (name, checked, expanded)
+ * @param role - The GTK accessible role to match
+ * @param options - Query options including name, state filters, and timeout
  * @returns Promise resolving to array of matching widgets
  */
 export declare const findAllByRole: (container: Container, role: Gtk.AccessibleRole, options?: ByRoleOptions) => Promise<Gtk.Widget[]>;
 /**
- * Waits for and finds a single widget matching the specified label text.
+ * Finds a single element by its label or text content.
+ *
+ * Matches button labels, input placeholders, window titles, and other
+ * accessible text content.
+ *
  * @param container - The container to search within
- * @param text - The text, pattern, or matcher function
- * @param options - Text matching options (exact, normalizer, timeout)
+ * @param text - Text to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization and timeout
  * @returns Promise resolving to the matching widget
+ *
+ * @example
+ * ```tsx
+ * const button = await findByLabelText(container, "Click me");
+ * const input = await findByLabelText(container, /search/i);
+ * ```
  */
 export declare const findByLabelText: (container: Container, text: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
 /**
- * Waits for and finds all widgets matching the specified label text.
+ * Finds all elements matching label or text content.
+ *
  * @param container - The container to search within
- * @param text - The text, pattern, or matcher function
- * @param options - Text matching options (exact, normalizer, timeout)
+ * @param text - Text to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization and timeout
  * @returns Promise resolving to array of matching widgets
  */
 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.
+ * Finds a single element by visible text content.
+ *
+ * Similar to {@link findByLabelText} but focuses on directly visible text.
+ *
  * @param container - The container to search within
- * @param text - The text, pattern, or matcher function
- * @param options - Text matching options (exact, normalizer, timeout)
+ * @param text - Text to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization and timeout
  * @returns Promise resolving to the matching 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.
+ * Finds all elements matching visible text content.
+ *
  * @param container - The container to search within
- * @param text - The text, pattern, or matcher function
- * @param options - Text matching options (exact, normalizer, timeout)
+ * @param text - Text to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization and timeout
  * @returns Promise resolving to array of matching widgets
  */
 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.
+ * Finds a single element by test ID (widget name).
+ *
+ * Uses the widget's `name` property as a test identifier.
+ * Set via the `name` prop on GTKX components.
+ *
  * @param container - The container to search within
- * @param testId - The test ID, pattern, or matcher function
- * @param options - Text matching options (exact, normalizer, timeout)
+ * @param testId - Test ID to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization and timeout
  * @returns Promise resolving to the matching widget
+ *
+ * @example
+ * ```tsx
+ * // In component: <GtkButton name="submit-btn" />
+ * const button = await findByTestId(container, "submit-btn");
+ * ```
  */
 export declare const findByTestId: (container: Container, testId: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget>;
 /**
- * Waits for and finds all widgets matching the specified test ID.
+ * Finds all elements matching a test ID pattern.
+ *
  * @param container - The container to search within
- * @param testId - The test ID, pattern, or matcher function
- * @param options - Text matching options (exact, normalizer, timeout)
+ * @param testId - Test ID to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization and timeout
  * @returns Promise resolving to array of matching widgets
  */
 export declare const findAllByTestId: (container: Container, testId: TextMatch, options?: TextMatchOptions) => Promise<Gtk.Widget[]>;

package/dist/queries.js

@@ -148,7 +148,6 @@ const getWidgetCheckedState = (widget) => {
         case Gtk.AccessibleRole.SWITCH:
             return widget.getActive();
         default:
-            return undefined;
     }
 };
 const getWidgetExpandedState = (widget) => {
@@ -162,7 +161,6 @@ const getWidgetExpandedState = (widget) => {
             return undefined;
         return parent.getExpanded?.();
     }
-    return undefined;
 };
 const matchByRoleOptions = (widget, options) => {
     if (!options)
@@ -186,9 +184,9 @@ const matchByRoleOptions = (widget, options) => {
 };
 const formatRole = (role) => Gtk.AccessibleRole[role] ?? String(role);
 const formatByRoleError = (role, options) => {
-    const parts = [`role "${formatRole(role)}"`];
+    const parts = [`role '${formatRole(role)}'`];
     if (options?.name)
-        parts.push(`name "${options.name}"`);
+        parts.push(`name '${options.name}'`);
     if (options?.checked !== undefined)
         parts.push(`checked=${options.checked}`);
     if (options?.pressed !== undefined)
@@ -216,7 +214,7 @@ const getAllByRole = (container, role, options) => {
 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)}`);
+        throw new Error(`Expected 1 element with ${formatByRoleError(role, options)}, found ${matches.length}`);
     }
     const [first] = matches;
     if (!first)
@@ -229,18 +227,18 @@ const getAllByLabelText = (container, text, options) => {
         return matchText(widgetText, text, node, options);
     });
     if (matches.length === 0) {
-        throw new Error(`Unable to find any elements with label text "${text}"`);
+        throw new Error(`Unable to find any elements with label text '${text}'`);
     }
     return matches;
 };
 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}"`);
+        throw new Error(`Expected 1 element with label text '${text}', found ${matches.length}`);
     }
     const [first] = matches;
     if (!first)
-        throw new Error(`Unable to find element with label text "${text}"`);
+        throw new Error(`Unable to find element with label text '${text}'`);
     return first;
 };
 const getAllByText = (container, text, options) => {
@@ -249,18 +247,18 @@ const getAllByText = (container, text, options) => {
         return matchText(widgetText, text, node, options);
     });
     if (matches.length === 0) {
-        throw new Error(`Unable to find any elements with text "${text}"`);
+        throw new Error(`Unable to find any elements with text '${text}'`);
     }
     return matches;
 };
 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}"`);
+        throw new Error(`Expected 1 element with text '${text}', found ${matches.length}`);
     }
     const [first] = matches;
     if (!first)
-        throw new Error(`Unable to find element with text "${text}"`);
+        throw new Error(`Unable to find element with text '${text}'`);
     return first;
 };
 const getAllByTestId = (container, testId, options) => {
@@ -269,95 +267,130 @@ const getAllByTestId = (container, testId, options) => {
         return matchText(widgetTestId, testId, node, options);
     });
     if (matches.length === 0) {
-        throw new Error(`Unable to find any elements with test id "${testId}"`);
+        throw new Error(`Unable to find any elements with test id '${testId}'`);
     }
     return matches;
 };
 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}"`);
+        throw new Error(`Expected 1 element with test id '${testId}', found ${matches.length}`);
     }
     const [first] = matches;
     if (!first)
-        throw new Error(`Unable to find element with test id "${testId}"`);
+        throw new Error(`Unable to find element with test id '${testId}'`);
     return first;
 };
 /**
- * Waits for and finds a single widget matching the specified accessible role.
+ * Finds a single element by accessible role.
+ *
+ * Waits for the element to appear, throwing if not found within timeout.
+ *
  * @param container - The container to search within
- * @param role - The accessible role to match
- * @param options - Additional filtering options (name, checked, expanded)
+ * @param role - The GTK accessible role to match
+ * @param options - Query options including name, state filters, and timeout
  * @returns Promise resolving to the matching widget
+ *
+ * @example
+ * ```tsx
+ * const button = await findByRole(container, Gtk.AccessibleRole.BUTTON, { name: "Submit" });
+ * ```
  */
 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.
+ * Finds all elements matching an accessible role.
+ *
  * @param container - The container to search within
- * @param role - The accessible role to match
- * @param options - Additional filtering options (name, checked, expanded)
+ * @param role - The GTK accessible role to match
+ * @param options - Query options including name, state filters, and timeout
  * @returns Promise resolving to array of matching widgets
  */
 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.
+ * Finds a single element by its label or text content.
+ *
+ * Matches button labels, input placeholders, window titles, and other
+ * accessible text content.
+ *
  * @param container - The container to search within
- * @param text - The text, pattern, or matcher function
- * @param options - Text matching options (exact, normalizer, timeout)
+ * @param text - Text to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization and timeout
  * @returns Promise resolving to the matching widget
+ *
+ * @example
+ * ```tsx
+ * const button = await findByLabelText(container, "Click me");
+ * const input = await findByLabelText(container, /search/i);
+ * ```
  */
 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.
+ * Finds all elements matching label or text content.
+ *
  * @param container - The container to search within
- * @param text - The text, pattern, or matcher function
- * @param options - Text matching options (exact, normalizer, timeout)
+ * @param text - Text to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization and timeout
  * @returns Promise resolving to array of matching widgets
  */
 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.
+ * Finds a single element by visible text content.
+ *
+ * Similar to {@link findByLabelText} but focuses on directly visible text.
+ *
  * @param container - The container to search within
- * @param text - The text, pattern, or matcher function
- * @param options - Text matching options (exact, normalizer, timeout)
+ * @param text - Text to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization and timeout
  * @returns Promise resolving to the matching widget
  */
 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.
+ * Finds all elements matching visible text content.
+ *
  * @param container - The container to search within
- * @param text - The text, pattern, or matcher function
- * @param options - Text matching options (exact, normalizer, timeout)
+ * @param text - Text to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization and timeout
  * @returns Promise resolving to array of matching widgets
  */
 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.
+ * Finds a single element by test ID (widget name).
+ *
+ * Uses the widget's `name` property as a test identifier.
+ * Set via the `name` prop on GTKX components.
+ *
  * @param container - The container to search within
- * @param testId - The test ID, pattern, or matcher function
- * @param options - Text matching options (exact, normalizer, timeout)
+ * @param testId - Test ID to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization and timeout
  * @returns Promise resolving to the matching widget
+ *
+ * @example
+ * ```tsx
+ * // In component: <GtkButton name="submit-btn" />
+ * const button = await findByTestId(container, "submit-btn");
+ * ```
  */
 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.
+ * Finds all elements matching a test ID pattern.
+ *
  * @param container - The container to search within
- * @param testId - The test ID, pattern, or matcher function
- * @param options - Text matching options (exact, normalizer, timeout)
+ * @param testId - Test ID to match (string, RegExp, or custom matcher)
+ * @param options - Query options including normalization and timeout
  * @returns Promise resolving to array of matching widgets
  */
 export const findAllByTestId = async (container, testId, options) => waitFor(() => getAllByTestId(container, testId, options), {