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

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 };

package/src/screenshot.ts

@@ -9,6 +9,7 @@ import { getConfig } from "./config.js";
 import { now } from "./timers.js";
 import { descendants } from "./traversal.js";
 import { waitFor } from "./wait-for.js";
+import { requireWidget } from "./widget-target.js";
 import { activeToplevel, mappedToplevels } from "./window-state.js";
 
 type FrameProbe = {
@@ -31,6 +32,20 @@ type CaptureOutcome =
     { status: "captured"; result: ScreenshotResult } |
     { status: "stalled"; failure: CaptureFailure };
 
+type BackgroundSnapshot = {
+    renderBackground(...args: [context: object, x: number, y: number, width: number, height: number]): void;
+};
+
+type StyledWidget = {
+    getStyleContext(): object;
+};
+
+type RenderSize = {
+    scale: number;
+    width: number;
+    height: number;
+};
+
 const DEFAULT_SCREENSHOT_INTERVAL = 10;
 const PRESENTATION_PROBE_MS = 250;
 
@@ -179,16 +194,43 @@ const getChildrenNode = (widget: Gtk.Widget, scale: number): Gsk.RenderNode | nu
     return snapshot.toNode();
 };
 
+const addWindowBackground = (
+    widget: Gtk.Widget,
+    node: Gsk.RenderNode,
+    { scale, width, height }: RenderSize,
+): Gsk.RenderNode => {
+    if (!(widget instanceof Gtk.Window)) {
+        return node;
+    }
+
+    const snapshot = new Gtk.Snapshot();
+    const backgroundSnapshot: BackgroundSnapshot = snapshot;
+    const styledWidget: StyledWidget = widget;
+    snapshot.save();
+    snapshot.scale(scale, scale);
+    backgroundSnapshot.renderBackground(styledWidget.getStyleContext(), 0, 0, width, height);
+    snapshot.restore();
+    snapshot.appendNode(node);
+
+    return snapshot.toNode() ?? node;
+};
+
+const getFallbackNode = (widget: Gtk.Widget, size: RenderSize): Gsk.RenderNode | null => {
+    const content = getChildrenNode(widget, size.scale);
+
+    return content === null ? null : addWindowBackground(widget, content, size);
+};
+
 const getRenderNode = (widget: Gtk.Widget, scale: number, width: number, height: number): Gsk.RenderNode | null => {
-    const presented = getPaintableNode(widget, scale, width, height);
+    const content = getPaintableNode(widget, scale, width, height);
 
-    if (presented) {
-        return presented;
+    if (content) {
+        return content;
     }
 
     allocateRoot(widget);
 
-    return getPaintableNode(widget, scale, width, height) ?? getChildrenNode(widget, scale);
+    return getPaintableNode(widget, scale, width, height) ?? getFallbackNode(widget, { scale, width, height });
 };
 
 const renderToPng = (widget: Gtk.Widget, node: Gsk.RenderNode, width: number, height: number): ScreenshotResult => {
@@ -301,7 +343,8 @@ const captureUntilPaintable = (
  * @param options Optional scale, timeout, retry interval, and output path.
  * @returns The base64-encoded PNG data along with its mime type and dimensions.
  */
-const screenshot = async (widget: Gtk.Widget, options?: ScreenshotOptions): Promise<ScreenshotResult> => {
+const screenshot = async (target: Gtk.Accessible, options?: ScreenshotOptions): Promise<ScreenshotResult> => {
+    const widget = requireWidget(target);
     const scale = options?.scale ?? 1;
 
     if (!Number.isFinite(scale) || scale <= 0) {

package/src/suggestions.ts

@@ -9,6 +9,7 @@ import {
     getWidgetOwnLabel,
     getWidgetPlaceholderText,
 } from "./widget-accessible-properties.js";
+import { requireWidget } from "./widget-target.js";
 
 /** The query variant a suggestion targets. */
 type Variant = "get" | "getAll" | "query" | "queryAll" | "find" | "findAll";
@@ -75,10 +76,11 @@ const textSuggestion = (queryName: Method, variant: Variant, value: string | nul
  * @returns The best available suggestion, or undefined when no query applies.
  */
 const getSuggestedQuery = (
-    widget: Gtk.Widget,
+    target: Gtk.Accessible,
     variant: Variant = "get",
     method?: Method,
 ): Suggestion | undefined => {
+    const widget = requireWidget(target);
     const builders: Record<Method, () => Suggestion | undefined> = {
         Role: () => roleSuggestion(widget, variant),
         LabelText: () =>

package/src/traversal.ts

@@ -1,25 +1,41 @@
 import * as Gtk from "@gtkx/gi/gtk";
+import { getClassType, getInstanceType, typeIsA } from "@gtkx/runtime";
 
 /**
  * A scope that resolves to a single root widget: the widget itself, the widget a controller or
  * layout manager is attached to, or a list item's or header's child.
  */
-type QueryContainer = Gtk.Widget | Gtk.EventController | Gtk.LayoutManager | Gtk.ListItem | Gtk.ListHeader;
+type QueryContainer = Gtk.Accessible | Gtk.EventController | Gtk.LayoutManager | Gtk.ListItem | Gtk.ListHeader;
 /**
  * A scope that queries and traversal can run against: a widget, an event
  * controller, a layout manager, a list item or header, an application, or the
  * sentinel representing all current toplevel windows.
  */
 type Container = QueryContainer | Gtk.Application | typeof TOPLEVELS;
-type WidgetClass<T extends Gtk.Widget> = abstract new (...args: never[]) => T;
+type WidgetClass<T extends object> = abstract new (...args: never[]) => T;
 
 /** Container sentinel that widens a query to every toplevel window currently open. */
 const TOPLEVELS: unique symbol = Symbol("gtkx.toplevels");
+const nativeWidgetTypes: Map<bigint, boolean> = new Map();
 
 const isApplication = (container: Container): container is Gtk.Application => container instanceof Gtk.Application;
 const isAnyWidget = (): boolean => true;
 const isOnScreen = (widget: Gtk.Widget): boolean => widget.getMapped();
 
+const isNativeWidget = (widget: Gtk.Widget): boolean => {
+    const type = getInstanceType(widget);
+    const cached = nativeWidgetTypes.get(type);
+
+    if (cached !== undefined) {
+        return cached;
+    }
+
+    const isNative = typeIsA(type, getClassType(Gtk.Native));
+    nativeWidgetTypes.set(type, isNative);
+
+    return isNative;
+};
+
 const traverseWidgetTree = function* (
     root: Gtk.Widget,
     isIncluded: (widget: Gtk.Widget) => boolean,
@@ -60,7 +76,7 @@ const ancestors = function* (widget: Gtk.Widget): Generator<Gtk.Widget> {
     }
 };
 
-const ancestorFor = <T extends Gtk.Widget>(widget: Gtk.Widget, type: WidgetClass<T>): T | null => {
+const ancestorFor = <T extends object>(widget: Gtk.Widget, type: WidgetClass<T>): T | null => {
     for (const ancestor of ancestors(widget)) {
         if (ancestor instanceof type) {
             return ancestor;
@@ -70,15 +86,23 @@ const ancestorFor = <T extends Gtk.Widget>(widget: Gtk.Widget, type: WidgetClass
     return null;
 };
 
-const relationCandidates = (widget: Gtk.Widget): Gtk.Accessible[] => {
-    const pool: Gtk.Accessible[] = [...widget.listMnemonicLabels(), ...descendants(widget)];
-    const root = widget.getRoot();
+const mappedWidgets = function* (widget: Gtk.Widget, isParentMapped: boolean): Generator<Gtk.Widget> {
+    const isMapped = (isParentMapped || isNativeWidget(widget)) && isOnScreen(widget);
 
-    if (root instanceof Gtk.Widget) {
-        pool.push(...traverseWidgetTree(root, isAnyWidget));
+    if (isMapped) {
+        yield widget;
     }
 
-    return [...new Set(pool)];
+    for (const child of children(widget)) {
+        yield* mappedWidgets(child, isMapped);
+    }
+};
+
+const relationCandidates = (widget: Gtk.Widget): Iterable<Gtk.Accessible>[] => {
+    const root = widget.getRoot();
+    const tree: Iterable<Gtk.Accessible> = root instanceof Gtk.Widget ? traverseWidgetTree(root, isAnyWidget) : [];
+
+    return [widget.listMnemonicLabels(), descendants(widget), tree];
 };
 
 const resolveRoot = (container: QueryContainer): Gtk.Widget | null => {
@@ -98,7 +122,7 @@ const resolveRoot = (container: QueryContainer): Gtk.Widget | null => {
         return container.getChild();
     }
 
-    return null;
+    throw new TypeError("Query container must resolve to a Gtk.Widget");
 };
 
 const roots = function* (container: Container): Generator<Gtk.Widget> {
@@ -117,7 +141,7 @@ const roots = function* (container: Container): Generator<Gtk.Widget> {
 
 const traverse = function* (container: Container): Generator<Gtk.Widget> {
     for (const root of roots(container)) {
-        yield* traverseWidgetTree(root, isOnScreen);
+        yield* mappedWidgets(root, true);
     }
 };
 

package/src/types.ts

@@ -1,5 +1,5 @@
 import type * as Gtk from "@gtkx/gi/gtk";
-import type { RootElement } from "@gtkx/react";
+import type { CaughtErrorInfo, RootElement } from "@gtkx/react";
 import type { ComponentType, ErrorInfo, ReactNode } from "react";
 import type { PrettyWidgetOptions } from "./pretty-widget.js";
 import type { Container } from "./traversal.js";
@@ -15,9 +15,11 @@ type Matcher = string | number | RegExp | MatcherFunction;
 type NormalizerFn = (text: string) => string;
 /**
  * A widget class usable as a query's `as` constraint, such as `Gtk.Button`. Abstract classes and
- * generated GInterface pseudo-classes are accepted.
+ * generated GInterface pseudo-classes that extend `Gtk.Accessible` are accepted.
  */
-type WidgetType<T extends Gtk.Widget = Gtk.Widget> = abstract new (...args: never[]) => T;
+type WidgetType<T extends Gtk.Accessible = Gtk.Accessible> = abstract new (
+    ...args: never[]
+) => T;
 
 /** Options controlling the default text normalizer. */
 type NormalizerOptions = {
@@ -40,7 +42,7 @@ type WaitForOptions = {
 };
 
 /** Options controlling text matching and, for asynchronous queries, polling behavior. */
-type MatcherOptions<T extends Gtk.Widget = Gtk.Widget> = {
+type MatcherOptions<T extends Gtk.Accessible = Gtk.Accessible> = {
     /** When true (the default), require an exact match; when false, match case-insensitively as a substring. */
     exact?: boolean | undefined;
     /** Custom normalizer replacing the default; cannot be combined with `trim` or `collapseWhitespace`. */
@@ -74,7 +76,7 @@ type ByRoleValue = {
 };
 
 /** Options for role queries: an accessible name matcher plus accessible state and value constraints. */
-type ByRoleOptions<T extends Gtk.Widget = Gtk.Widget> = MatcherOptions<T> & {
+type ByRoleOptions<T extends Gtk.Accessible = Gtk.Accessible> = MatcherOptions<T> & {
     /** Matcher for the widget's accessible name. */
     name?: Matcher | undefined;
     /** Required checked state; a mixed check button reads as neither, so it matches neither value. */
@@ -116,7 +118,7 @@ type BoundQuery<Q extends Query> = Q extends (container: Container, ...args: inf
 type BoundCustomQueries<Q extends QueryMap> = { [K in keyof Q]: BoundQuery<Q[K]> };
 
 /** What each variant of a query family yields for the widget type it matched. */
-type QueryFamilyReturns<T extends Gtk.Widget> = {
+type QueryFamilyReturns<T extends Gtk.Accessible> = {
     /** The single match, or null when nothing matched; throws when more than one matched. */
     queryBy: T | null;
     /** Every match, empty when nothing matched. */
@@ -135,7 +137,7 @@ type QueryFamilyReturns<T extends Gtk.Widget> = {
 type QueryKind = "role" | "text" | "name" | "value";
 
 /** The arguments a query of the given kind takes after the family's leading ones. */
-type QueryArgs<Kind extends QueryKind, T extends Gtk.Widget> = Kind extends "role"
+type QueryArgs<Kind extends QueryKind, T extends Gtk.Accessible> = Kind extends "role"
     ? [role: Gtk.AccessibleRole, options?: ByRoleOptions<T>]
     : Kind extends "name"
         ? [name: Matcher, options?: MatcherOptions<T>]
@@ -148,7 +150,9 @@ type QueryArgs<Kind extends QueryKind, T extends Gtk.Widget> = Kind extends "rol
  * ahead of the family's own arguments.
  */
 type QueryFamily<Suffix extends string, Kind extends QueryKind, Head extends unknown[]> = {
-    [K in keyof QueryFamilyReturns<Gtk.Widget> as `${K & string}${Suffix}`]: <T extends Gtk.Widget = Gtk.Widget>(
+    [K in keyof QueryFamilyReturns<Gtk.Widget> as `${K & string}${Suffix}`]: <
+        T extends Gtk.Accessible = Gtk.Widget,
+    >(
         ...args: [...Head, ...QueryArgs<Kind, T>]
     ) => QueryFamilyReturns<T>[K];
 };
@@ -175,7 +179,7 @@ type RenderOptions<Q extends QueryMap = Record<never, never>> = {
      * out of reach of a pointer and a keyboard, so every `userEvent` helper aimed at it rejects
      * after `actionabilityTimeout`; `fireEvent` drives such a tree instead.
      */
-    container?: Gtk.Widget | RootElement | undefined;
+    container?: Gtk.Accessible | RootElement | undefined;
     /** Root of the subtree that bound queries search. */
     baseElement?: Container | undefined;
     /** Component wrapped around the rendered element, such as a context provider. */
@@ -185,7 +189,7 @@ type RenderOptions<Q extends QueryMap = Record<never, never>> = {
     /** Enable widget animations during the test. */
     areAnimationsEnabled?: boolean | undefined;
     /** Called for errors caught by React error boundaries. */
-    onCaughtError?: ((error: unknown, errorInfo: ErrorInfo) => void) | undefined;
+    onCaughtError?: ((error: unknown, errorInfo: CaughtErrorInfo) => void) | undefined;
     /** Called for errors React recovered from automatically. */
     onRecoverableError?: ((error: unknown, errorInfo: ErrorInfo) => void) | undefined;
     /** Custom queries to bind to the rendered result. */

package/src/user-event/click.ts

@@ -11,6 +11,7 @@ type PressPoint = { x: number; y: number };
 type ClickPhase = "pressed" | "released";
 type ClickSite = { gestures: Gtk.GestureClick[]; point: PressPoint };
 type ClickScope = { isClicked: boolean; isInternalAllowed: boolean };
+type DirectClick = { sites: ClickSite[]; outcome: NativeClick | null };
 
 type ClickTarget = {
     widget: Gtk.Widget;
@@ -59,15 +60,6 @@ const emitGesture = (
     }
 };
 
-const emitClickPhase = (
-    widget: Gtk.Widget,
-    controllers: Gtk.GestureClick[],
-    nPress: number,
-    phase: ClickPhase,
-): void => {
-    emitGesture(getCenterPoint(widget), controllers, nPress, phase);
-};
-
 const emitSitePhase = (sites: ClickSite[], nPress: number, phase: ClickPhase): void => {
     for (const site of sites) {
         emitGesture(site.point, site.gestures, nPress, phase);
@@ -97,14 +89,23 @@ const clickGestures = (widget: Gtk.Widget): Gtk.GestureClick[] =>
 const getAuthoredClickGestures = (widget: Gtk.Widget): Gtk.GestureClick[] =>
     clickGestures(widget).filter((gesture) => hasClickHandlers(gesture));
 
-const isClaimingTarget = (widget: Gtk.Widget): boolean =>
-    widget instanceof Gtk.Button || containerFor(widget) !== null;
-
 const gestureTargetFor = (widget: Gtk.Widget, isInternalAllowed: boolean): ClickTarget | null => {
     const gestures = clickGestures(widget);
 
-    if (isClaimingTarget(widget)) {
-        return { widget, container: containerFor(widget), gestures, isClaiming: true, native: null };
+    if (widget instanceof Gtk.Button) {
+        return { widget, container: null, gestures, isClaiming: true, native: null };
+    }
+
+    const container = containerFor(widget);
+
+    if (container !== null) {
+        return {
+            widget,
+            container,
+            gestures: gestures.filter((gesture) => hasClickHandlers(gesture)),
+            isClaiming: true,
+            native: null,
+        };
     }
 
     const authored = gestures.filter((gesture) => hasClickHandlers(gesture));
@@ -205,7 +206,7 @@ const applyContainerOutcome = (target: ClickTarget, nPress: number): void => {
     }
 
     if (isActivatedByClick(container, nPress)) {
-        widget.activate();
+        Gtk.Widget.prototype.activate.call(widget);
     }
 
     if (isSelectionReplacedByClick(container, nPress)) {
@@ -223,6 +224,24 @@ const applyClickOutcome = (target: ClickTarget, nPress: number): void => {
     target.native(target.widget, nPress);
 };
 
+const applyContainerClick: NativeClick = (widget, nPress) => {
+    const container = containerFor(widget);
+
+    if (container !== null) {
+        applyContainerOutcome({ widget, container, gestures: [], isClaiming: true, native: null }, nPress);
+    }
+};
+
+const directClickFor = (widget: Gtk.Widget): DirectClick => {
+    const native = nativeClickFor(widget, true);
+    const container = native === null ? containerFor(widget) : null;
+    const gestures =
+        native !== null || container !== null ? getAuthoredClickGestures(widget) : clickGestures(widget);
+    const target: ClickTarget = { widget, container, gestures, isClaiming: true, native };
+
+    return { sites: targetSites(widget, target), outcome: native ?? (container === null ? null : applyContainerClick) };
+};
+
 const applyClickOutcomes = (targets: ClickTarget[], nPress: number): void => {
     for (const target of targets) {
         applyClickOutcome(target, nPress);
@@ -246,7 +265,7 @@ const tryActivate = async (widget: Gtk.Widget): Promise<boolean> => {
     let isActivated = false;
 
     await wrapEvent(widget, () => {
-        isActivated = widget.activate();
+        isActivated = Gtk.Widget.prototype.activate.call(widget);
     });
 
     return isActivated;
@@ -266,4 +285,5 @@ const dblClick = (widget: Gtk.Widget): Promise<void> => deliverClick(widget, 2);
 /** Delivers a triple-click gesture. */
 const tripleClick = (widget: Gtk.Widget): Promise<void> => deliverClick(widget, 3);
 
-export { clickGestures, emitClickPhase, getAuthoredClickGestures, click, dblClick, tripleClick };
+export { directClickFor, emitSitePhase, click, dblClick, tripleClick };
+export type { DirectClick };

package/src/user-event/controller.ts

@@ -1,4 +1,5 @@
 import type * as Gtk from "@gtkx/gi/gtk";
+import { requireWidget } from "../widget-target.js";
 
 /** An event controller class that can be constructed without arguments, such as `Gtk.GestureClick`. */
 type ControllerConstructor<T extends Gtk.EventController> = new () => T;
@@ -11,9 +12,10 @@ type ControllerConstructor<T extends Gtk.EventController> = new () => T;
  * @returns The matching controllers, or an empty array when the widget has none.
  */
 const queryAllControllers = <T extends Gtk.EventController>(
-    widget: Gtk.Widget,
+    target: Gtk.Accessible,
     controllerType: ControllerConstructor<T>,
 ): T[] => {
+    const widget = requireWidget(target);
     const controllers = widget.observeControllers();
     const nItems = controllers.getNItems();
     const matches: T[] = [];
@@ -37,7 +39,7 @@ const queryAllControllers = <T extends Gtk.EventController>(
  * @returns The first matching controller, or null when the widget has none.
  */
 const queryController = <T extends Gtk.EventController>(
-    widget: Gtk.Widget,
+    widget: Gtk.Accessible,
     controllerType: ControllerConstructor<T>,
 ): T | null => queryAllControllers(widget, controllerType)[0] ?? null;
 
@@ -49,7 +51,7 @@ const queryController = <T extends Gtk.EventController>(
  * @throws When the widget has no controller of that type.
  */
 const getAllControllers = <T extends Gtk.EventController>(
-    widget: Gtk.Widget,
+    widget: Gtk.Accessible,
     controllerType: ControllerConstructor<T>,
 ): T[] => {
     const controllers = queryAllControllers(widget, controllerType);
@@ -69,7 +71,7 @@ const getAllControllers = <T extends Gtk.EventController>(
  * @throws When the widget has no controller of that type.
  */
 const getController = <T extends Gtk.EventController>(
-    widget: Gtk.Widget,
+    widget: Gtk.Accessible,
     controllerType: ControllerConstructor<T>,
 ): T => {
     const [controller] = getAllControllers(widget, controllerType);
@@ -82,9 +84,10 @@ const getController = <T extends Gtk.EventController>(
 };
 
 const getOrCreateControllers = <T extends Gtk.EventController>(
-    widget: Gtk.Widget,
+    target: Gtk.Accessible,
     controllerType: ControllerConstructor<T>,
 ): T[] => {
+    const widget = requireWidget(target);
     const existing = queryAllControllers(widget, controllerType);
 
     if (existing.length > 0) {