@gtkx/testing 2.0.0-beta.1 → 2.0.0-beta.10

package/src/fire-event.ts

@@ -7,13 +7,21 @@ import { runInAct } from "./act.js";
  */
 type WidgetEvent = {
     /** The GObject instance the signal is emitted on. */
-    target: GObject.Object;
+    target: Pick<GObject.Object, "__type__">;
     /** Name of the signal to emit. */
     signalName: string;
     /** Arguments passed to the signal handlers. */
     args: unknown[];
 };
 
+const requireObject = (target: object): GObject.Object => {
+    if (!(target instanceof GObject.Object)) {
+        throw new TypeError("Expected a GObject instance");
+    }
+
+    return target;
+};
+
 /**
  * Records a signal emission without delivering it, so it can be inspected or held and passed to
  * {@link fireEvent} later.
@@ -23,18 +31,28 @@ type WidgetEvent = {
  * @param args Arguments to pass to the signal handlers.
  * @returns The recorded emission.
  */
-const createEvent = (target: GObject.Object, signalName: string, ...args: unknown[]): WidgetEvent => ({
-    target,
+const createEvent = (
+    target: Pick<GObject.Object, "__type__">,
+    signalName: string,
+    ...args: unknown[]
+): WidgetEvent => ({
+    target: requireObject(target),
     signalName,
     args,
 });
 
 const dispatchEvent = async (event: WidgetEvent): Promise<void> => {
+    const target = requireObject(event.target);
+
     await runInAct(() => {
-        event.target.emit(event.signalName, ...event.args);
+        Reflect.apply(GObject.signalEmit, undefined, [target, event.signalName, ...event.args]);
     });
 };
 
+const isWidgetEvent = (value: object): value is WidgetEvent =>
+    "target" in value && "signalName" in value && "args" in value &&
+    typeof value.signalName === "string" && Array.isArray(value.args);
+
 /**
  * Emits a recorded signal emission inside React's act environment, so any resulting state updates are
  * flushed before the promise resolves.
@@ -50,14 +68,18 @@ function fireEvent(event: WidgetEvent): Promise<void>;
  * @param signalName Name of the signal to emit.
  * @param args Arguments passed to the signal handlers.
  */
-function fireEvent(target: GObject.Object, signalName: string, ...args: unknown[]): Promise<void>;
+function fireEvent(
+    target: Pick<GObject.Object, "__type__">,
+    signalName: string,
+    ...args: unknown[]
+): Promise<void>;
 
 function fireEvent(
-    eventOrTarget: WidgetEvent | GObject.Object,
+    eventOrTarget: WidgetEvent | Pick<GObject.Object, "__type__">,
     signalName?: string,
     ...args: unknown[]
 ): Promise<void> {
-    if (!(eventOrTarget instanceof GObject.Object)) {
+    if (signalName === undefined && isWidgetEvent(eventOrTarget)) {
         return dispatchEvent(eventOrTarget);
     }
 
@@ -65,7 +87,9 @@ function fireEvent(
         throw new Error("Unable to fire an event: pass a signal name, or an event built by createEvent.");
     }
 
-    return dispatchEvent(createEvent(eventOrTarget, signalName, ...args));
+    const target = requireObject(eventOrTarget);
+
+    return dispatchEvent({ target, signalName, args });
 }
 
 export { createEvent, fireEvent, type WidgetEvent };

package/src/matchers.ts

@@ -1,4 +1,4 @@
-import type { SyncExpectationResult } from "@vitest/expect";
+import type { SyncMatcherResult } from "vitest";
 import * as GObject from "@gtkx/gi/gobject";
 import * as Gtk from "@gtkx/gi/gtk";
 import type { ByRoleOptions, Matcher, MatcherOptions } from "./types.js";
@@ -57,7 +57,7 @@ type TextContentOptions = {
 /** The expected value for a style class: an exact class name or a regular expression. */
 type ClassExpectation = string | RegExp;
 /** The outcome of a matcher: whether it passed, and the failure text built on demand. */
-type MatcherResult = Pick<SyncExpectationResult, "message" | "pass">;
+type MatcherResult = Pick<SyncMatcherResult, "message" | "pass">;
 
 /** The matcher state bound as `this`, supplying the test runner's deep equality check. */
 type MatcherContext = {
@@ -77,7 +77,7 @@ type TextQueryArgs = [text: Matcher, options?: MatcherOptions];
 type ContainmentMatcher<Args extends unknown[]> = (received: unknown, ...args: Args) => MatcherResult;
 type TextMatcherContext = { matcherName: string; widget: Gtk.Widget; actual: string | null };
 type ClassArguments = { expected: ClassExpectation[]; isExact: boolean };
-type QueryAll<Args extends unknown[]> = (container: Container, ...args: Args) => Gtk.Widget[];
+type QueryAll<Args extends unknown[]> = (container: Container, ...args: Args) => object[];
 
 type BooleanAccessibleState =
     Gtk.AccessibleState.BUSY |
@@ -195,11 +195,11 @@ type MatcherImplementations = {
     /** Asserts the widget's accessible role. */
     toHaveRole: (received: unknown, expected: Gtk.AccessibleRole) => MatcherResult;
     /** Asserts the widget is, or is an ancestor of, the given widget. */
-    toContainElement: (received: unknown, descendant: Gtk.Widget | null) => MatcherResult;
+    toContainElement: (received: unknown, descendant: Gtk.Accessible | null) => MatcherResult;
     /** Asserts the widget comes before the given widget in the widget tree, neither containing the other. */
-    toAppearBefore: (received: unknown, other: Gtk.Widget) => MatcherResult;
+    toAppearBefore: (received: unknown, other: Gtk.Accessible) => MatcherResult;
     /** Asserts the widget comes after the given widget in the widget tree, neither containing the other. */
-    toAppearAfter: (received: unknown, other: Gtk.Widget) => MatcherResult;
+    toAppearAfter: (received: unknown, other: Gtk.Accessible) => MatcherResult;
     /** Asserts at least one widget under the received one matches the `ByRole` query. */
     toContainAnyByRole: ContainmentMatcher<RoleQueryArgs>;
     /** Asserts exactly one widget under the received one matches the `ByRole` query. */
@@ -525,9 +525,6 @@ const isAppearingBefore = (first: Gtk.Widget, second: Gtk.Widget): boolean => {
     return isSeparateWidget(first, second) && root === getTreeRoot(second) && isPrecedingWidget(root, first, second);
 };
 
-const camelCase = (name: string): string =>
-    name.replaceAll(/-([a-z])/g, (_match, letter: string) => letter.toUpperCase());
-
 const isAsymmetricMatcher = (value: unknown): boolean =>
     typeof value === "object" && value !== null && typeof Reflect.get(value, "asymmetricMatch") === "function";
 
@@ -588,26 +585,8 @@ function readErrorMessageText(widget: Gtk.Widget): string | null {
     return texts.length > 0 ? texts.join(" ") : null;
 }
 
-function assertReadableProperty(object: GObject.Object, name: string, property: string, value: unknown): void {
-    if (typeof value === "function") {
-        throw new TypeError(
-            `toHaveObjectProperty: "${name}" is shadowed by a method of the same name; ` +
-            `call ${property}() and assert on its result instead`,
-        );
-    }
-
-    if (value === undefined && !Reflect.has(object, property)) {
-        throw new TypeError(
-            `toHaveObjectProperty: no readable property "${name}" on ${describeObject(object)}; ` +
-            "construct-only and write-only properties cannot be read back",
-        );
-    }
-}
-
 function readObjectProperty(object: GObject.Object, name: string): unknown {
-    const property = camelCase(name);
-    const value: unknown = Reflect.get(object, property);
-    assertReadableProperty(object, name, property, value);
+    const value: unknown = Reflect.apply(GObject.getProperty, undefined, [object, name]);
 
     return value;
 }
@@ -804,14 +783,14 @@ function toBePartiallyPressed(received: unknown): MatcherResult {
     return stateResult(widget, "partially pressed", state === MIXED_TRISTATE);
 }
 
-function toAppearBefore(received: unknown, other: Gtk.Widget): MatcherResult {
+function toAppearBefore(received: unknown, other: Gtk.Accessible): MatcherResult {
     const widget = asWidget(received, "toAppearBefore");
     const target = asWidget(other, "toAppearBefore");
 
     return orderResult(widget, target, "before", isAppearingBefore(widget, target));
 }
 
-function toAppearAfter(received: unknown, other: Gtk.Widget): MatcherResult {
+function toAppearAfter(received: unknown, other: Gtk.Accessible): MatcherResult {
     const widget = asWidget(received, "toAppearAfter");
     const target = asWidget(other, "toAppearAfter");
 
@@ -943,15 +922,16 @@ function toHaveRole(received: unknown, expected: Gtk.AccessibleRole): MatcherRes
     };
 }
 
-function toContainElement(received: unknown, descendant: Gtk.Widget | null): MatcherResult {
+function toContainElement(received: unknown, descendant: Gtk.Accessible | null): MatcherResult {
     const widget = asWidget(received, "toContainElement");
-    const isPass = descendant !== null && (descendant === widget || descendant.isAncestor(widget));
+    const target = descendant === null ? null : asWidget(descendant, "toContainElement");
+    const isPass = target !== null && (target === widget || target.isAncestor(widget));
 
     return {
         pass: isPass,
         message: () =>
             `expected widget ${negationPrefix(isPass)}to contain ` +
-            `${descendant === null ? "null" : describeWidget(descendant)}\n${describeWidget(widget)}`,
+            `${target === null ? "null" : describeWidget(target)}\n${describeWidget(widget)}`,
     };
 }
 
@@ -1020,64 +1000,62 @@ const registerMatchers = (): void => {
     registration.isRegistered = true;
 };
 
-declare module "@vitest/expect" {
-    /* eslint-disable @typescript-eslint/consistent-type-definitions -- declaration merging requires interfaces */
-    interface WidgetMatchers {
-        toHaveDisplayValue(expected?: TextExpectation): void;
-        toHaveTextContent(expected?: TextExpectation, options?: TextContentOptions): void;
-        toHaveAccessibleName(expected?: TextExpectation): void;
-        toHaveAccessibleDescription(expected?: TextExpectation): void;
-        toHaveAccessibleErrorMessage(expected?: TextExpectation): void;
-        toHaveSelection(expected?: TextExpectation): void;
+declare module "vitest" {
+    /* eslint-disable @typescript-eslint/consistent-type-definitions, @typescript-eslint/no-unused-vars --
+       declaration merging requires an interface with vitest's exact type parameters */
+    interface Matchers<R extends void | Promise<void> = void | Promise<void>, T = unknown> {
+        toHaveDisplayValue(expected?: TextExpectation): R;
+        toHaveTextContent(expected?: TextExpectation, options?: TextContentOptions): R;
+        toHaveAccessibleName(expected?: TextExpectation): R;
+        toHaveAccessibleDescription(expected?: TextExpectation): R;
+        toHaveAccessibleErrorMessage(expected?: TextExpectation): R;
+        toHaveSelection(expected?: TextExpectation): R;
         /* eslint-disable-next-line unicorn/consistent-boolean-name -- expected is the jest-dom matcher argument name */
-        toHaveAccessibleState(state: BooleanAccessibleState, expected?: boolean): void;
-        toHaveAccessibleState(state: TristateAccessibleState, expected?: Gtk.AccessibleTristate): void;
-        toHaveAccessibleState(state: Gtk.AccessibleState.INVALID, expected?: Gtk.AccessibleInvalidState): void;
-        toHaveAccessibleProperty(property: StringAccessibleProperty, expected?: string): void;
+        toHaveAccessibleState(state: BooleanAccessibleState, expected?: boolean): R;
+        toHaveAccessibleState(state: TristateAccessibleState, expected?: Gtk.AccessibleTristate): R;
+        toHaveAccessibleState(state: Gtk.AccessibleState.INVALID, expected?: Gtk.AccessibleInvalidState): R;
+        toHaveAccessibleProperty(property: StringAccessibleProperty, expected?: string): R;
         /* eslint-disable-next-line unicorn/consistent-boolean-name -- expected is the jest-dom matcher argument name */
-        toHaveAccessibleProperty(property: BooleanAccessibleProperty, expected?: boolean): void;
-        toHaveAccessibleProperty(property: NumberAccessibleProperty, expected?: number): void;
+        toHaveAccessibleProperty(property: BooleanAccessibleProperty, expected?: boolean): R;
+        toHaveAccessibleProperty(property: NumberAccessibleProperty, expected?: number): R;
         toHaveAccessibleProperty(
             property: Gtk.AccessibleProperty.AUTOCOMPLETE,
             expected?: Gtk.AccessibleAutocomplete,
-        ): void;
-        toHaveAccessibleProperty(property: Gtk.AccessibleProperty.ORIENTATION, expected?: Gtk.Orientation): void;
-        toHaveAccessibleProperty(property: Gtk.AccessibleProperty.SORT, expected?: Gtk.AccessibleSort): void;
-        toBeChecked(): void;
-        toBePartiallyChecked(): void;
-        toBePressed(): void;
-        toBePartiallyPressed(): void;
-        toBeDisabled(): void;
-        toBeEnabled(): void;
-        toBeVisible(): void;
-        toBeRooted(): void;
-        toBeEmptyWidget(): void;
-        toBeInvalid(): void;
-        toBeValid(): void;
-        toBeRequired(): void;
-        toHaveFocus(): void;
-        toHaveValue(expected?: number | string): void;
-        toHaveRole(expected: Gtk.AccessibleRole): void;
-        toContainElement(descendant: Gtk.Widget | null): void;
-        toAppearBefore(other: Gtk.Widget): void;
-        toAppearAfter(other: Gtk.Widget): void;
-        toContainAnyByRole(...args: RoleQueryArgs): void;
-        toContainOneByRole(...args: RoleQueryArgs): void;
-        toContainAnyByText(...args: TextQueryArgs): void;
-        toContainOneByText(...args: TextQueryArgs): void;
-        toContainAnyByLabelText(...args: TextQueryArgs): void;
-        toContainOneByLabelText(...args: TextQueryArgs): void;
-        toContainAnyByPlaceholderText(...args: TextQueryArgs): void;
-        toContainOneByPlaceholderText(...args: TextQueryArgs): void;
-        toContainAnyByDisplayValue(...args: TextQueryArgs): void;
-        toContainOneByDisplayValue(...args: TextQueryArgs): void;
-        toHaveClass(...args: (ClassExpectation | { exact: boolean })[]): void;
-        toHaveObjectProperty(name: string, expected?: unknown): void;
+        ): R;
+        toHaveAccessibleProperty(property: Gtk.AccessibleProperty.ORIENTATION, expected?: Gtk.Orientation): R;
+        toHaveAccessibleProperty(property: Gtk.AccessibleProperty.SORT, expected?: Gtk.AccessibleSort): R;
+        toBeChecked(): R;
+        toBePartiallyChecked(): R;
+        toBePressed(): R;
+        toBePartiallyPressed(): R;
+        toBeDisabled(): R;
+        toBeEnabled(): R;
+        toBeVisible(): R;
+        toBeRooted(): R;
+        toBeEmptyWidget(): R;
+        toBeInvalid(): R;
+        toBeValid(): R;
+        toBeRequired(): R;
+        toHaveFocus(): R;
+        toHaveValue(expected?: number | string): R;
+        toHaveRole(expected: Gtk.AccessibleRole): R;
+        toContainElement(descendant: Gtk.Accessible | null): R;
+        toAppearBefore(other: Gtk.Accessible): R;
+        toAppearAfter(other: Gtk.Accessible): R;
+        toContainAnyByRole(...args: RoleQueryArgs): R;
+        toContainOneByRole(...args: RoleQueryArgs): R;
+        toContainAnyByText(...args: TextQueryArgs): R;
+        toContainOneByText(...args: TextQueryArgs): R;
+        toContainAnyByLabelText(...args: TextQueryArgs): R;
+        toContainOneByLabelText(...args: TextQueryArgs): R;
+        toContainAnyByPlaceholderText(...args: TextQueryArgs): R;
+        toContainOneByPlaceholderText(...args: TextQueryArgs): R;
+        toContainAnyByDisplayValue(...args: TextQueryArgs): R;
+        toContainOneByDisplayValue(...args: TextQueryArgs): R;
+        toHaveClass(...args: (ClassExpectation | { exact: boolean })[]): R;
+        toHaveObjectProperty(name: string, expected?: unknown): R;
     }
-
-    interface Assertion extends WidgetMatchers {}
-    interface AsymmetricMatchersContaining extends WidgetMatchers {}
-    /* eslint-enable @typescript-eslint/consistent-type-definitions */
+    /* eslint-enable @typescript-eslint/consistent-type-definitions, @typescript-eslint/no-unused-vars */
 }
 
 export { matchers, registerMatchers, type ClassExpectation, type TextContentOptions, type TextExpectation };

package/src/queries.ts

@@ -12,6 +12,7 @@ import { multipleFoundError, notFoundError } from "./errors.js";
 import { getDefaultNormalizer } from "./normalize.js";
 import { type Container, findAll, traverse } from "./traversal.js";
 import {
+    buildInaccessibilityCheck,
     getWidgetAccessibleName,
     getWidgetBusyState,
     getWidgetDescription,
@@ -26,7 +27,6 @@ import {
     getWidgetPressedState,
     getWidgetSelectedState,
     getWidgetValueText,
-    isInaccessible,
     isWidgetChecked,
     isWidgetValueMatch,
     namingLabelText,
@@ -39,7 +39,7 @@ type BuiltinQueries = QueryFamilies<[container: Container]>;
 const roleQueries = nameQueryFamily(
     "Role",
     queryAllByRole,
-    buildQueries<[role: Gtk.AccessibleRole, options?: ByRoleOptions]>(
+    buildQueries<[role: Gtk.AccessibleRole, options?: ByRoleOptions<Gtk.Widget>], Gtk.Widget>(
         queryAllByRole,
         (container, matches, role, options) =>
             multipleFoundError(container, { queryType: "role", role, options }, matches),
@@ -50,7 +50,7 @@ const roleQueries = nameQueryFamily(
 const labelTextQueries = nameQueryFamily(
     "LabelText",
     queryAllByLabelText,
-    buildQueries<[text: Matcher, options?: MatcherOptions]>(
+    buildQueries<[text: Matcher, options?: MatcherOptions<Gtk.Widget>], Gtk.Widget>(
         queryAllByLabelText,
         (container, matches, text) => multipleFoundError(container, { queryType: "labelText", text }, matches),
         (container, text) => notFoundError(container, { queryType: "labelText", text }),
@@ -60,7 +60,7 @@ const labelTextQueries = nameQueryFamily(
 const textQueries = nameQueryFamily(
     "Text",
     queryAllByText,
-    buildQueries<[text: Matcher, options?: MatcherOptions]>(
+    buildQueries<[text: Matcher, options?: MatcherOptions<Gtk.Widget>], Gtk.Widget>(
         queryAllByText,
         (container, matches, text) => multipleFoundError(container, { queryType: "text", text }, matches),
         (container, text) => notFoundError(container, { queryType: "text", text }),
@@ -70,7 +70,7 @@ const textQueries = nameQueryFamily(
 const nameQueries = nameQueryFamily(
     "Name",
     queryAllByName,
-    buildQueries<[name: Matcher, options?: MatcherOptions]>(
+    buildQueries<[name: Matcher, options?: MatcherOptions<Gtk.Widget>], Gtk.Widget>(
         queryAllByName,
         (container, matches, name) => multipleFoundError(container, { queryType: "name", name }, matches),
         (container, name) => notFoundError(container, { queryType: "name", name }),
@@ -80,7 +80,7 @@ const nameQueries = nameQueryFamily(
 const placeholderTextQueries = nameQueryFamily(
     "PlaceholderText",
     queryAllByPlaceholderText,
-    buildQueries<[text: Matcher, options?: MatcherOptions]>(
+    buildQueries<[text: Matcher, options?: MatcherOptions<Gtk.Widget>], Gtk.Widget>(
         queryAllByPlaceholderText,
         (container, matches, text) => multipleFoundError(container, { queryType: "placeholderText", text }, matches),
         (container, text) => notFoundError(container, { queryType: "placeholderText", text }),
@@ -90,7 +90,7 @@ const placeholderTextQueries = nameQueryFamily(
 const displayValueQueries = nameQueryFamily(
     "DisplayValue",
     queryAllByDisplayValue,
-    buildQueries<[value: Matcher, options?: MatcherOptions]>(
+    buildQueries<[value: Matcher, options?: MatcherOptions<Gtk.Widget>], Gtk.Widget>(
         queryAllByDisplayValue,
         (container, matches, value) => multipleFoundError(container, { queryType: "displayValue", value }, matches),
         (container, value) => notFoundError(container, { queryType: "displayValue", value }),
@@ -284,25 +284,27 @@ const hasMatchingAccessibleStates = (widget: Gtk.Widget, options: ByRoleOptions)
     hasMatchingDescriptionState(widget, options) &&
     hasMatchingValueState(widget, options);
 
-const isMatchingWidgetType = (widget: Gtk.Widget, options?: MatcherOptions): boolean =>
+const isMatchingWidgetType = <T extends Gtk.Accessible>(
+    widget: Gtk.Widget,
+    options?: MatcherOptions<T>,
+): widget is Gtk.Widget & T =>
     options?.as === undefined || widget instanceof options.as;
 
-const hasMatchingByRoleOptions = (widget: Gtk.Widget, options?: ByRoleOptions): boolean => {
+const hasMatchingAccessibleOptions = (widget: Gtk.Widget, options?: ByRoleOptions): boolean => {
     if (!options) {
         return true;
     }
 
     return (
-        isMatchingWidgetType(widget, options) &&
         hasMatchingAccessibleName(widget, options) &&
         hasMatchingAccessibleStates(widget, options)
     );
 };
 
-function nameQueryFamily<Args extends unknown[]>(
+function nameQueryFamily<Args extends unknown[], Element extends Gtk.Accessible>(
     suffix: string,
-    queryAllBy: QueryAllBy<Args>,
-    built: BuiltQueries<Args>,
+    queryAllBy: QueryAllBy<Args, Element>,
+    built: BuiltQueries<Args, Element>,
 ): Record<string, unknown> {
     const [queryBy, getAllBy, getBy, findAllBy, findBy] = built;
 
@@ -325,22 +327,30 @@ function nameQueryFamily<Args extends unknown[]>(
  * @param options Additional accessible name, state, and value constraints.
  * @returns Every matching widget, or an empty array when none match.
  */
-function queryAllByRole(
+function queryAllByRole<T extends Gtk.Accessible = Gtk.Widget>(
     container: Container,
     role: Gtk.AccessibleRole,
-    options?: ByRoleOptions,
-): Gtk.Widget[] {
-    return findAll(container, (widget) => {
+    options?: ByRoleOptions<T>,
+): T[] {
+    const isInaccessible = buildInaccessibilityCheck();
+
+    const matches = findAll(container, (widget) => {
         if (widget.getAccessibleRole() !== role) {
             return false;
         }
 
+        if (!isMatchingWidgetType(widget, options)) {
+            return false;
+        }
+
         if (!options?.hidden && isInaccessible(widget)) {
             return false;
         }
 
-        return hasMatchingByRoleOptions(widget, options);
+        return hasMatchingAccessibleOptions(widget, options);
     });
+
+    return matches.filter((widget): widget is Gtk.Widget & T => isMatchingWidgetType(widget, options));
 }
 
 const collectMnemonicMatch = (
@@ -394,14 +404,18 @@ const collectLabelMatches = (
  * @param options Text matching options.
  * @returns Every matching widget, or an empty array when none match.
  */
-function queryAllByLabelText(container: Container, text: Matcher, options?: MatcherOptions): Gtk.Widget[] {
+function queryAllByLabelText<T extends Gtk.Accessible = Gtk.Widget>(
+    container: Container,
+    text: Matcher,
+    options?: MatcherOptions<T>,
+): T[] {
     const results: Set<Gtk.Widget> = new Set();
 
     for (const widget of traverse(container)) {
         collectLabelMatches(results, widget, text, options);
     }
 
-    return [...results].filter((widget) => isMatchingWidgetType(widget, options));
+    return [...results].filter((widget): widget is Gtk.Widget & T => isMatchingWidgetType(widget, options));
 }
 
 /**
@@ -411,12 +425,18 @@ function queryAllByLabelText(container: Container, text: Matcher, options?: Matc
  * @param options Text matching options.
  * @returns Every matching widget, or an empty array when none match.
  */
-function queryAllByText(container: Container, text: Matcher, options?: MatcherOptions): Gtk.Widget[] {
-    return findAll(
+function queryAllByText<T extends Gtk.Accessible = Gtk.Widget>(
+    container: Container,
+    text: Matcher,
+    options?: MatcherOptions<T>,
+): T[] {
+    const matches = findAll(
         container,
         (widget) =>
             isMatchingWidgetType(widget, options) && isTextMatch(getWidgetLabelText(widget), text, widget, options),
     );
+
+    return matches.filter((widget): widget is Gtk.Widget & T => isMatchingWidgetType(widget, options));
 }
 
 /**
@@ -426,11 +446,17 @@ function queryAllByText(container: Container, text: Matcher, options?: MatcherOp
  * @param options Text matching options.
  * @returns Every matching widget, or an empty array when none match.
  */
-function queryAllByName(container: Container, name: Matcher, options?: MatcherOptions): Gtk.Widget[] {
-    return findAll(
+function queryAllByName<T extends Gtk.Accessible = Gtk.Widget>(
+    container: Container,
+    name: Matcher,
+    options?: MatcherOptions<T>,
+): T[] {
+    const matches = findAll(
         container,
         (widget) => isMatchingWidgetType(widget, options) && isTextMatch(getWidgetName(widget), name, widget, options),
     );
+
+    return matches.filter((widget): widget is Gtk.Widget & T => isMatchingWidgetType(widget, options));
 }
 
 /**
@@ -440,17 +466,19 @@ function queryAllByName(container: Container, name: Matcher, options?: MatcherOp
  * @param options Text matching options.
  * @returns Every matching widget, or an empty array when none match.
  */
-function queryAllByPlaceholderText(
+function queryAllByPlaceholderText<T extends Gtk.Accessible = Gtk.Widget>(
     container: Container,
     text: Matcher,
-    options?: MatcherOptions,
-): Gtk.Widget[] {
-    return findAll(
+    options?: MatcherOptions<T>,
+): T[] {
+    const matches = findAll(
         container,
         (widget) =>
             isMatchingWidgetType(widget, options) &&
             isTextMatch(getWidgetPlaceholderText(widget), text, widget, options),
     );
+
+    return matches.filter((widget): widget is Gtk.Widget & T => isMatchingWidgetType(widget, options));
 }
 
 /**
@@ -460,13 +488,19 @@ function queryAllByPlaceholderText(
  * @param options Text matching options.
  * @returns Every matching widget, or an empty array when none match.
  */
-function queryAllByDisplayValue(container: Container, value: Matcher, options?: MatcherOptions): Gtk.Widget[] {
-    return findAll(
+function queryAllByDisplayValue<T extends Gtk.Accessible = Gtk.Widget>(
+    container: Container,
+    value: Matcher,
+    options?: MatcherOptions<T>,
+): T[] {
+    const matches = findAll(
         container,
         (widget) =>
             isMatchingWidgetType(widget, options) &&
             isTextMatch(getWidgetDisplayValue(widget), value, widget, options),
     );
+
+    return matches.filter((widget): widget is Gtk.Widget & T => isMatchingWidgetType(widget, options));
 }
 
 export {

package/src/query-helpers.ts

@@ -1,5 +1,5 @@
 import type * as Gtk from "@gtkx/gi/gtk";
-import { camelCase } from "@gtkx/utils";
+import { getProperty } from "@gtkx/gi/gobject";
 import type { Matcher, MatcherOptions } from "./types.js";
 import { buildQueries } from "./build-queries.js";
 import { getElementError } from "./errors.js";
@@ -27,7 +27,13 @@ const queryHelpers: QueryHelpers = {
 };
 
 const readObjectProperty = (widget: Gtk.Widget, property: string): string | null => {
-    const value: unknown = Reflect.get(widget, camelCase(property));
+    let value: unknown;
+
+    try {
+        value = Reflect.apply(getProperty, undefined, [widget, property]);
+    } catch {
+        return null;
+    }
 
     if (typeof value === "string") {
         return value;
@@ -51,18 +57,20 @@ const readObjectProperty = (widget: Gtk.Widget, property: string): string | null
  * @param options Text matching options.
  * @returns Every matching widget, or an empty array when none match.
  */
-function queryAllByObjectProperty(
+function queryAllByObjectProperty<T extends Gtk.Accessible = Gtk.Widget>(
     property: string,
     container: Container,
     text: Matcher,
-    options?: MatcherOptions,
-): Gtk.Widget[] {
-    return findAll(
+    options?: MatcherOptions<T>,
+): T[] {
+    const matches = findAll(
         container,
         (widget) =>
             isMatchingWidgetType(widget, options) &&
             isTextMatch(readObjectProperty(widget, property), text, widget, options),
     );
+
+    return matches.filter((widget): widget is Gtk.Widget & T => isMatchingWidgetType(widget, options));
 }
 
 /**
@@ -76,12 +84,12 @@ function queryAllByObjectProperty(
  * @returns The matching widget, or null when none match.
  * @throws When more than one widget matches.
  */
-function queryByObjectProperty(
+function queryByObjectProperty<T extends Gtk.Accessible = Gtk.Widget>(
     property: string,
     container: Container,
     text: Matcher,
-    options?: MatcherOptions,
-): Gtk.Widget | null {
+    options?: MatcherOptions<T>,
+): T | null {
     const matches = queryAllByObjectProperty(property, container, text, options);
 
     if (matches.length > 1) {

package/src/render.tsx

@@ -1,4 +1,4 @@
-import type { RootElement } from "@gtkx/react";
+import type { CaughtErrorInfo, RootElement } from "@gtkx/react";
 import * as Gtk from "@gtkx/gi/gtk";
 import {
     createReconcilerRoot,
@@ -21,6 +21,7 @@ import { clearScreen, setScreen } from "./screen.js";
 import { captureScreen } from "./screenshot.js";
 import { type Container, roots, TOPLEVELS } from "./traversal.js";
 import { resetClipboard } from "./user-event/index.js";
+import { requireWidget } from "./widget-target.js";
 import { findPresentedWindowFailure, findRenderedWindowFailure, mappedToplevels } from "./window-state.js";
 import { within } from "./within.js";
 
@@ -125,6 +126,10 @@ const resolveContainer = (container: RenderOptions["container"]): ResolvedContai
         return { containerInfo: container, window: null };
     }
 
+    if (container !== undefined) {
+        requireWidget(container);
+    }
+
     const window = createHarnessWindow();
     window.setDecorated(false);
 
@@ -188,7 +193,7 @@ const settleRender = async (
 
 const renderErrorHandlers = <Q extends QueryMap>(options: RenderOptions<Q> | undefined) => ({
     onUncaughtError: handleError,
-    onCaughtError: (error: unknown, errorInfo: ErrorInfo): void => {
+    onCaughtError: (error: unknown, errorInfo: CaughtErrorInfo): void => {
         handleError(error);
         options?.onCaughtError?.(error, errorInfo);
     },