@gtkx/testing 2.0.0-beta.3 → 2.0.0-beta.5

package/src/build-queries.ts

@@ -5,18 +5,28 @@ import { getConfig } from "./config.js";
 import { runWithExpensiveErrorDiagnosticsDisabled, suggestionError } from "./errors.js";
 import { getSuggestedQuery, type Variant } from "./suggestions.js";
 import { waitFor } from "./wait-for.js";
+import { requireWidget } from "./widget-target.js";
 
 /**
  * The `queryAllBy` function a query family is built from, taking the scope to search followed by the
  * family's own matcher arguments. Its name determines the family name, so `queryAllByTestId` builds
  * a `TestId` family.
  */
-type QueryAllBy<Args extends unknown[]> = (container: Container, ...args: Args) => Gtk.Widget[];
+type QueryAllBy<
+    Args extends unknown[],
+    Element extends Gtk.Accessible = Gtk.Accessible,
+> = (
+    container: Container,
+    ...args: Args
+) => Element[];
 
 /** Builds the error thrown when a single-match query finds more than one widget. */
-type MultipleErrorBuilder<Args extends unknown[]> = (
+type MultipleErrorBuilder<
+    Args extends unknown[],
+    Element extends Gtk.Accessible = Gtk.Accessible,
+> = (
     container: Container,
-    matches: Gtk.Widget[],
+    matches: Element[],
     ...args: Args
 ) => Error;
 
@@ -24,16 +34,22 @@ type MultipleErrorBuilder<Args extends unknown[]> = (
 type MissingErrorBuilder<Args extends unknown[]> = (container: Container, ...args: Args) => Error;
 
 /** The variants derived from one `queryAllBy` function, in the order DOM Testing Library returns them. */
-type BuiltQueries<Args extends unknown[]> = [
-    queryBy: (container: Container, ...args: Args) => Gtk.Widget | null,
-    getAllBy: QueryAllBy<Args>,
-    getBy: (container: Container, ...args: Args) => Gtk.Widget,
-    findAllBy: (container: Container, ...args: Args) => Promise<Gtk.Widget[]>,
-    findBy: (container: Container, ...args: Args) => Promise<Gtk.Widget>,
+type BuiltQueries<
+    Args extends unknown[],
+    Element extends Gtk.Accessible = Gtk.Accessible,
+> = [
+    queryBy: (container: Container, ...args: Args) => Element | null,
+    getAllBy: QueryAllBy<Args, Element>,
+    getBy: (container: Container, ...args: Args) => Element,
+    findAllBy: (container: Container, ...args: Args) => Promise<Element[]>,
+    findBy: (container: Container, ...args: Args) => Promise<Element>,
 ];
 
 type FindQuery<Args extends unknown[]> = (container: Container, ...args: Args) => unknown;
-type SingleQuery<Args extends unknown[]> = (container: Container, ...args: Args) => Gtk.Widget | null;
+type SingleQuery<Args extends unknown[], Element extends Gtk.Accessible> = (
+    container: Container,
+    ...args: Args
+) => Element | null;
 
 const getTrailingOptions = (args: unknown[]): MatcherOptions | undefined => {
     const last = args.at(-1);
@@ -50,7 +66,7 @@ const getQueryFamily = (queryAllBy: { name: string }): string => queryAllBy.name
 
 const maybeThrowSuggestion = (options: {
     container: Container;
-    match: Gtk.Widget;
+    match: object;
     queryName: string;
     variant: Variant;
     shouldSuggest: boolean | undefined;
@@ -61,7 +77,7 @@ const maybeThrowSuggestion = (options: {
         return;
     }
 
-    const suggestion = getSuggestedQuery(match, variant);
+    const suggestion = getSuggestedQuery(requireWidget(match), variant);
 
     if (suggestion && suggestion.queryName !== queryName) {
         throw suggestionError(suggestion.toString(), container);
@@ -101,10 +117,10 @@ const findOptions = <Args extends unknown[]>(
 };
 
 const singleFrom =
-    <Args extends unknown[]>(
-        allQuery: QueryAllBy<Args>,
-        getMultipleError: MultipleErrorBuilder<Args>,
-    ): SingleQuery<Args> =>
+    <Args extends unknown[], Element extends Gtk.Accessible>(
+        allQuery: QueryAllBy<Args, Element>,
+        getMultipleError: MultipleErrorBuilder<Args, Element>,
+    ): SingleQuery<Args, Element> =>
         (container, ...args) => {
             const matches = allQuery(container, ...args);
 
@@ -116,10 +132,10 @@ const singleFrom =
         };
 
 const allOrThrow =
-    <Args extends unknown[]>(
-        allQuery: QueryAllBy<Args>,
+    <Args extends unknown[], Element extends Gtk.Accessible>(
+        allQuery: QueryAllBy<Args, Element>,
         getMissingError: MissingErrorBuilder<Args>,
-    ): QueryAllBy<Args> =>
+    ): QueryAllBy<Args, Element> =>
         (container, ...args) => {
             const matches = allQuery(container, ...args);
 
@@ -131,7 +147,11 @@ const allOrThrow =
         };
 
 const wrapSingleWithSuggestion =
-    <Args extends unknown[]>(query: SingleQuery<Args>, queryName: string, variant: Variant): SingleQuery<Args> =>
+    <Args extends unknown[], Element extends Gtk.Accessible>(
+        query: SingleQuery<Args, Element>,
+        queryName: string,
+        variant: Variant,
+    ): SingleQuery<Args, Element> =>
         (container, ...args) => {
             const match = query(container, ...args);
 
@@ -149,7 +169,11 @@ const wrapSingleWithSuggestion =
         };
 
 const wrapAllWithSuggestion =
-    <Args extends unknown[]>(query: QueryAllBy<Args>, queryName: string, variant: Variant): QueryAllBy<Args> =>
+    <Args extends unknown[], Element extends Gtk.Accessible>(
+        query: QueryAllBy<Args, Element>,
+        queryName: string,
+        variant: Variant,
+    ): QueryAllBy<Args, Element> =>
         (container, ...args) => {
             const matches = query(container, ...args);
             const [first] = matches;
@@ -168,8 +192,11 @@ const wrapAllWithSuggestion =
         };
 
 const requireSingle =
-    <Args extends unknown[]>(query: SingleQuery<Args>, getMissingError: MissingErrorBuilder<Args>) =>
-        (container: Container, ...args: Args): Gtk.Widget => {
+    <Args extends unknown[], Element extends Gtk.Accessible>(
+        query: SingleQuery<Args, Element>,
+        getMissingError: MissingErrorBuilder<Args>,
+    ) =>
+        (container: Container, ...args: Args): Element => {
             const match = query(container, ...args);
 
             if (match === null) {
@@ -189,11 +216,14 @@ const requireSingle =
  * @param getMissingError Builds the error thrown when a required match is missing.
  * @returns The variants, in the order `[queryBy, getAllBy, getBy, findAllBy, findBy]`.
  */
-const buildQueries = <Args extends unknown[]>(
-    queryAllBy: QueryAllBy<Args>,
-    getMultipleError: MultipleErrorBuilder<Args>,
+const buildQueries = <
+    Args extends unknown[],
+    Element extends Gtk.Accessible = Gtk.Accessible,
+>(
+    queryAllBy: QueryAllBy<Args, Element>,
+    getMultipleError: MultipleErrorBuilder<Args, Element>,
     getMissingError: MissingErrorBuilder<Args>,
-): BuiltQueries<Args> => {
+): BuiltQueries<Args, Element> => {
     const queryName = getQueryFamily(queryAllBy);
     const getAllBy = allOrThrow(queryAllBy, getMissingError);
     const getBy = requireSingle(singleFrom(getAllBy, getMultipleError), getMissingError);
@@ -206,7 +236,7 @@ const buildQueries = <Args extends unknown[]>(
 
     const getAllByWithSuggestion = wrapAllWithSuggestion(getAllBy, queryName, "getAll");
 
-    const getByWithSuggestion: (container: Container, ...args: Args) => Gtk.Widget = (container, ...args) => {
+    const getByWithSuggestion: (container: Container, ...args: Args) => Element = (container, ...args) => {
         const match = getBy(container, ...args);
 
         maybeThrowSuggestion({
@@ -220,13 +250,13 @@ const buildQueries = <Args extends unknown[]>(
         return match;
     };
 
-    const findAllBy = (container: Container, ...args: Args): Promise<Gtk.Widget[]> =>
+    const findAllBy = (container: Container, ...args: Args): Promise<Element[]> =>
         waitFor(
             () => runWithExpensiveErrorDiagnosticsDisabled(() => getAllByWithSuggestion(container, ...args)),
             findOptions(getAllByWithSuggestion, container, args),
         );
 
-    const findBy = (container: Container, ...args: Args): Promise<Gtk.Widget> =>
+    const findBy = (container: Container, ...args: Args): Promise<Element> =>
         waitFor(
             () => runWithExpensiveErrorDiagnosticsDisabled(() => getByWithSuggestion(container, ...args)),
             findOptions(getByWithSuggestion, container, args),

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(() => {
-        Reflect.apply(GObject.signalEmit, undefined, [event.target, 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

@@ -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. */
@@ -783,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");
 
@@ -922,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)}`,
     };
 }
 
@@ -1037,9 +1038,9 @@ declare module "@vitest/expect" {
         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;
+        toContainElement(descendant: Gtk.Accessible | null): void;
+        toAppearBefore(other: Gtk.Accessible): void;
+        toAppearAfter(other: Gtk.Accessible): void;
         toContainAnyByRole(...args: RoleQueryArgs): void;
         toContainOneByRole(...args: RoleQueryArgs): void;
         toContainAnyByText(...args: TextQueryArgs): void;

package/src/queries.ts

@@ -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,12 +327,12 @@ 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 matches = findAll(container, (widget) => {
         if (widget.getAccessibleRole() !== role) {
             return false;
         }
@@ -339,8 +341,14 @@ function queryAllByRole(
             return false;
         }
 
-        return hasMatchingByRoleOptions(widget, options);
+        if (!isMatchingWidgetType(widget, options)) {
+            return false;
+        }
+
+        return hasMatchingAccessibleOptions(widget, options);
     });
+
+    return matches.filter((widget): widget is Gtk.Widget & T => isMatchingWidgetType(widget, options));
 }
 
 const collectMnemonicMatch = (
@@ -394,14 +402,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 +423,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 +444,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 +464,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 +486,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

@@ -57,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));
 }
 
 /**
@@ -82,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

@@ -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);
 

package/src/role-helpers.ts

@@ -3,6 +3,7 @@ import { sortStringsBy } from "@gtkx/utils";
 import { type Container, traverse } from "./traversal.js";
 import { getWidgetAccessibleName, getWidgetLevel } from "./widget-accessible-properties.js";
 import { getTypeTag } from "./widget-getters.js";
+import { requireWidget } from "./widget-target.js";
 
 const ROLE_NAMES_BY_VALUE = enumNamesByValue(Gtk.AccessibleRole);
 
@@ -125,6 +126,7 @@ const logRoles = (container: Container): void => {
  *
  * @param widget The widget to read the level from.
  */
-const computeHeadingLevel = (widget: Gtk.Widget): number | undefined => getWidgetLevel(widget) ?? undefined;
+const computeHeadingLevel = (widget: Gtk.Accessible): number | undefined =>
+    getWidgetLevel(requireWidget(widget)) ?? undefined;
 
 export { computeHeadingLevel, formatRole, formatRoleList, getRoles, prettyRoles, logRoles };