@gtkx/testing 1.0.0 → 1.2.0

package/src/frame-sync.ts

@@ -1,5 +1,6 @@
 import type * as Gtk from "@gtkx/gi/gtk";
 import * as GLib from "@gtkx/gi/glib";
+import { cancelTimeout, scheduleTimeout } from "./timers.js";
 
 const CLOCK_STALL_FALLBACK_MS = 500;
 
@@ -17,22 +18,21 @@ const once = (callback: () => void): (() => void) => {
 };
 
 const hasFrameClock = (widget: Gtk.Widget | null): widget is Gtk.Widget => widget?.getFrameClock() != null;
-const isSized = (widget: Gtk.Widget): boolean => widget.getWidth() > 0;
 
-const runUntilReady = (widget: Gtk.Widget, isReady: () => boolean, finish: () => void): void => {
+const runUntilReady = (widget: Gtk.Widget, isReady: () => boolean, timeout: number, finish: () => void): void => {
     let tickId = 0;
 
-    const fallback = setTimeout(() => {
+    const fallback = scheduleTimeout(() => {
         widget.removeTickCallback(tickId);
         finish();
-    }, CLOCK_STALL_FALLBACK_MS);
+    }, timeout);
 
     tickId = widget.addTickCallback(() => {
         if (!isReady()) {
             return GLib.SOURCE_CONTINUE;
         }
 
-        clearTimeout(fallback);
+        cancelTimeout(fallback);
         finish();
 
         return GLib.SOURCE_REMOVE;
@@ -49,19 +49,24 @@ const scheduleNextFrame = (widget: Gtk.Widget): Promise<void> =>
             return;
         }
 
-        runUntilReady(widget, () => true, finish);
+        runUntilReady(widget, () => true, CLOCK_STALL_FALLBACK_MS, finish);
     });
 
-const scheduleAfterLayout = (widget: Gtk.Widget | null, callback: () => void): void => {
+const scheduleWhenWindowReady = (
+    window: Gtk.Window | null,
+    isReady: (window: Gtk.Window) => boolean,
+    timeout: number,
+    callback: () => void,
+): void => {
     const finish = once(callback);
 
-    if (!hasFrameClock(widget) || isSized(widget)) {
+    if (!hasFrameClock(window) || isReady(window)) {
         queueMicrotask(finish);
 
         return;
     }
 
-    runUntilReady(widget, () => isSized(widget), finish);
+    runUntilReady(window, () => isReady(window), timeout, finish);
 };
 
-export { scheduleAfterLayout, scheduleNextFrame };
+export { scheduleNextFrame, scheduleWhenWindowReady };

package/src/harness-window.ts

@@ -2,8 +2,22 @@ import * as Gtk from "@gtkx/gi/gtk";
 
 const HARNESS_WINDOW_WIDTH = 800;
 const HARNESS_WINDOW_HEIGHT = 600;
+const TEXT_END_POSITION = -1;
 
 const createHarnessWindow = (): Gtk.Window =>
     new Gtk.Window({ defaultWidth: HARNESS_WINDOW_WIDTH, defaultHeight: HARNESS_WINDOW_HEIGHT });
 
-export { createHarnessWindow };
+const presentHarnessWindow = (window: Gtk.Window | null): void => {
+    if (!window) {
+        return;
+    }
+
+    window.present();
+    const focus = window.getFocus();
+
+    if (focus instanceof Gtk.Text) {
+        focus.setPosition(TEXT_END_POSITION);
+    }
+};
+
+export { createHarnessWindow, presentHarnessWindow };

package/src/internal.ts

@@ -9,3 +9,4 @@ export {
 } from "./accessible-native.js";
 export { cleanup, render } from "./production.js";
 export { renderChildren, type ChildrenBuilder } from "./render-children.js";
+export { getTypeTag } from "./widget-getters.js";

package/src/matchers.ts

@@ -39,6 +39,8 @@ import {
     isWidgetValueMatch,
     isWidgetVisible,
 } from "./widget-accessible-properties.js";
+import { getTypeTag } from "./widget-getters.js";
+import { isWindowActivated } from "./window-state.js";
 
 /** The expected value for a text matcher: an exact string or a regular expression. */
 type TextExpectation = string | RegExp;
@@ -389,7 +391,7 @@ const describeWidget = (widget: Gtk.Widget): string => {
 };
 
 const describeObject = (object: GObject.Object): string =>
-    object instanceof Gtk.Widget ? describeWidget(object) : `<${object.constructor.name}>`;
+    object instanceof Gtk.Widget ? describeWidget(object) : `<${getTypeTag(object)}>`;
 
 const isTextMatch = (actual: string, expected: TextExpectation, mode: "exact" | "substring"): boolean => {
     if (expected instanceof RegExp) {
@@ -429,6 +431,31 @@ const stateResult = (widget: Gtk.Widget, stateName: string, isPass: boolean): Ma
     message: () => `expected widget ${negationPrefix(isPass)}to be ${stateName}\n${describeWidget(widget)}`,
 });
 
+const isHoldingFocus = (widget: Gtk.Widget, root: Gtk.Window): boolean => {
+    const focus = root.getFocus();
+
+    return focus !== null && (focus === widget || focus.isAncestor(widget));
+};
+
+const isFocusHeldByInactiveWindow = (widget: Gtk.Widget): boolean => {
+    const root = widget.getRoot();
+
+    return root instanceof Gtk.Window && !isWindowActivated(root) && isHoldingFocus(widget, root);
+};
+
+const focusResult = (widget: Gtk.Widget, isPass: boolean): MatcherResult => {
+    if (isPass || !isFocusHeldByInactiveWindow(widget)) {
+        return stateResult(widget, "focused", isPass);
+    }
+
+    return {
+        pass: false,
+        message: () =>
+            "expected widget to be focused: its window has given it the focus, " +
+            `but that window is not active\n${describeWidget(widget)}`,
+    };
+};
+
 const describeAttributeValue = (value: AccessibleAttributeValue | null): string =>
     value === null ? "unset" : JSON.stringify(value);
 
@@ -900,7 +927,7 @@ function toBeValid(received: unknown): MatcherResult {
 function toHaveFocus(received: unknown): MatcherResult {
     const widget = asWidget(received, "toHaveFocus");
 
-    return stateResult(widget, "focused", widget.getPlatformState(Gtk.AccessiblePlatformState.FOCUSED));
+    return focusResult(widget, widget.getPlatformState(Gtk.AccessiblePlatformState.FOCUSED));
 }
 
 function toHaveRole(received: unknown, expected: Gtk.AccessibleRole): MatcherResult {

package/src/pretty-widget.ts

@@ -4,6 +4,7 @@ import { type Config, format, type NewPlugin, type PrettyFormatOptions } from "@
 import { formatRole } from "./role-helpers.js";
 import { type Container, descendants, isOnScreen, roots } from "./traversal.js";
 import { getWidgetText } from "./widget-accessible-properties.js";
+import { getTypeTag } from "./widget-getters.js";
 
 /** Produces the value of the `id` attribute printed first on a widget's opening tag. */
 type WidgetIdResolver = (widget: Gtk.Widget) => string;
@@ -181,7 +182,7 @@ const formatBody = (widget: Gtk.Widget, indentation: string, depth: number, ctx:
 
 const formatWidget = (widget: Gtk.Widget, indentation: string, depth: number, ctx: FormatContext): string => {
     const { config } = ctx;
-    const tag = widget.constructor.name;
+    const tag = getTypeTag(widget);
     const attrs = formatAttrs(buildAttrs(widget, ctx.getId), config.colors);
     const openTag = `${paint(config.colors.tag, "<" + tag)}${attrs}${paint(config.colors.tag, ">")}`;
     const closeTag = paint(config.colors.tag, `</${tag}>`);

package/src/production.ts

@@ -2,6 +2,7 @@ import type * as Gtk from "@gtkx/gi/gtk";
 import type { ReactNode } from "react";
 import { createRoot, type Root } from "@gtkx/react";
 import { createHarnessWindow } from "./harness-window.js";
+import { delay } from "./timers.js";
 
 type ProductionRenderResult = {
     rerender: (element: ReactNode) => Promise<void>;
@@ -15,11 +16,9 @@ type ActiveRender = {
 const SETTLE_TURNS = 3;
 const activeRenders: Set<ActiveRender> = new Set();
 
-const turn = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 0));
-
 const settle = async (): Promise<void> => {
     for (let index = 0; index < SETTLE_TURNS; index++) {
-        await turn();
+        await delay(0);
     }
 };
 

package/src/render.tsx

@@ -12,14 +12,16 @@ import type { RenderResult } from "./bound-queries.js";
 import type { QueryMap, RenderOptions, ScreenshotOptions } from "./types.js";
 import { runInAct } from "./act.js";
 import { addToCleanupQueue, runCleanup } from "./cleanup-registry.js";
-import { scheduleAfterLayout } from "./frame-sync.js";
-import { createHarnessWindow } from "./harness-window.js";
+import { getConfig } from "./config.js";
+import { scheduleWhenWindowReady } from "./frame-sync.js";
+import { createHarnessWindow, presentHarnessWindow } from "./harness-window.js";
 import { logWidget, type PrettyWidgetOptions } from "./pretty-widget.js";
 import { logRoles } from "./role-helpers.js";
 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 { findPresentedWindowFailure, findRenderedWindowFailure, mappedToplevels } from "./window-state.js";
 import { within } from "./within.js";
 
 /** A mounted render tracked so cleanup can unmount it. */
@@ -40,17 +42,34 @@ type ReconcilerErrorState = {
     isHandlerInstalled: boolean;
 };
 
+type WindowFailureReporter = (window: Gtk.Window) => string | null;
+type SettleAction = "render" | "rerender";
+
 const reconcilerErrors: ReconcilerErrorState = { lastError: null, isHandlerInstalled: false };
 const activeRenders: Set<ActiveRender> = new Set();
 
-const flushLayout = (window: Gtk.Window | null): Promise<void> =>
-    new Promise<void>((resolve) => {
-        scheduleAfterLayout(window, () => {
-            settleAccessible();
-            resolve();
-        });
+const settleWindow = async (
+    window: Gtk.Window | null,
+    findFailure: WindowFailureReporter,
+    action: SettleAction,
+): Promise<void> => {
+    const timeout = getConfig().windowActivationTimeout;
+
+    await new Promise<void>((resolve) => {
+        scheduleWhenWindowReady(window, (target) => findFailure(target) === null, timeout, resolve);
     });
 
+    settleAccessible();
+    const failure = window === null ? null : findFailure(window);
+
+    if (failure !== null) {
+        throw new Error(
+            `${action} timed out after ${String(timeout)}ms waiting for the window it rendered into: ${failure}. ` +
+            "Platform state such as focus is only readable once that window is allocated and active.",
+        );
+    }
+};
+
 const update = async (element: ReactNode, root: ReconcilerRoot): Promise<void> => {
     await runInAct(() => {
         root.update(element);
@@ -138,6 +157,31 @@ const resolveResultContainer = (
     return firstToplevelWidget(baseElement);
 };
 
+const realizedWindow = (root: Gtk.Root | null): Gtk.Window | null =>
+    root instanceof Gtk.Window && root.getFrameClock() !== null ? root : null;
+
+const settleTarget = (resolved: ResolvedContainer, container: RenderOptions["container"]): Gtk.Window | null => {
+    if (resolved.window) {
+        return realizedWindow(resolved.window);
+    }
+
+    if (container instanceof Gtk.Widget) {
+        return realizedWindow(container.getRoot());
+    }
+
+    return realizedWindow(mappedToplevels()[0] ?? null);
+};
+
+const settleRender = async (
+    resolved: ResolvedContainer,
+    container: RenderOptions["container"],
+    action: SettleAction,
+): Promise<void> => {
+    const isPresentedNow = action === "render" && resolved.window !== null;
+    const findFailure = isPresentedNow ? findPresentedWindowFailure : findRenderedWindowFailure;
+    await settleWindow(settleTarget(resolved, container), findFailure, action);
+};
+
 const renderErrorHandlers = <Q extends QueryMap>(options: RenderOptions<Q> | undefined) => ({
     onUncaughtError: handleError,
     onCaughtError: (error: unknown, errorInfo: ErrorInfo): void => {
@@ -160,11 +204,22 @@ const applyEnableAnimations = (areAnimationsEnabled: boolean): void => {
 /**
  * Renders a React element into a GTK4 widget tree and returns queries
  * scoped to it along with controls for rerendering and unmounting. When no
- * container is supplied, a harness window is created and presented.
+ * container is supplied, a harness window is created and presented, and the editable it hands the
+ * focus to keeps its text unselected, with its caret at the end. The returned promise settles once
+ * the window the tree is shown in has been laid out and activation has arrived, so platform state
+ * such as focus is already readable when it resolves. A presented harness window is waited on until
+ * it is itself active; a window the caller or the tree owns is waited on until the application holds
+ * activation, since only a present can claim it. Rendering into a container that is not shown waits
+ * for nothing, and a window that never becomes readable within `windowActivationTimeout` throws an
+ * error naming the condition that failed rather than resolving with unreadable platform state. A
+ * tree mounted into a container that sits outside every toplevel, or inside a window that is not
+ * visible, is out of reach of a pointer and a keyboard, so every `userEvent` helper aimed at it
+ * rejects after `actionabilityTimeout` naming that condition, and `fireEvent` drives it instead.
  *
  * @param element The React element to render.
  * @param options Optional container, wrapper, custom queries, and other render settings.
  * @returns A render result with bound queries, debug helpers, and lifecycle controls.
+ * @throws When the window the tree is shown in is not laid out and activated in time.
  */
 const render = async <Q extends QueryMap = Record<never, never>>(
     element: ReactNode,
@@ -194,8 +249,8 @@ const render = async <Q extends QueryMap = Record<never, never>>(
     };
 
     await update(wrap(element), root);
-    resolved.window?.present();
-    await flushLayout(resolved.window);
+    presentHarnessWindow(resolved.window);
+    await settleRender(resolved, options?.container, "render");
     const container = resolveResultContainer(resolved, options?.container, baseElement);
 
     const result: RenderResult<Q> = {
@@ -207,7 +262,7 @@ const render = async <Q extends QueryMap = Record<never, never>>(
         },
         rerender: async (newElement: ReactNode) => {
             await update(wrap(newElement), root);
-            await flushLayout(resolved.window);
+            await settleRender(resolved, options?.container, "rerender");
         },
         debug: (element: Container | Container[] = baseElement, debugOptions?: PrettyWidgetOptions) => {
             logWidget(element, debugOptions);

package/src/role-helpers.ts

@@ -2,6 +2,7 @@ import * as Gtk from "@gtkx/gi/gtk";
 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";
 
 const ROLE_NAMES_BY_VALUE = enumNamesByValue(Gtk.AccessibleRole);
 
@@ -71,7 +72,7 @@ const getRoles = (container: Container): Map<string, Gtk.Widget[]> => {
 };
 
 const formatWidgetPreview = (widget: Gtk.Widget, name: string | null): string => {
-    const tagName = widget.constructor.name;
+    const tagName = getTypeTag(widget);
     const roleAttr = formatRole(widget.getAccessibleRole());
     const nameDisplay = name ? `Name "${name}"` : 'Name ""';
 

package/src/screenshot.ts

@@ -6,8 +6,10 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import type { ScreenshotOptions, ScreenshotResult } from "./types.js";
 import { getConfig } from "./config.js";
+import { now } from "./timers.js";
 import { descendants } from "./traversal.js";
 import { waitFor } from "./wait-for.js";
+import { activeToplevel, mappedToplevels } from "./window-state.js";
 
 type FrameProbe = {
     counter: bigint | null;
@@ -45,7 +47,7 @@ const OTHER_FAILURE_HINT =
 
 const NOTHING_ON_SCREEN_MESSAGE = "Nothing is on screen to capture: no toplevel window is mapped";
 
-const bytesToBase64 = (bytes: number[]): string => {
+const bytesToBase64 = (bytes: Uint8Array | number[]): string => {
     return Buffer.from(bytes).toString("base64");
 };
 
@@ -106,7 +108,7 @@ const requestFrame = (widget: Gtk.Widget): void => {
 const startFrameProbe = (widget: Gtk.Widget): FrameProbe => {
     requestFrame(widget);
 
-    return { counter: getFrameCounter(widget), startedAt: Date.now() };
+    return { counter: getFrameCounter(widget), startedAt: now() };
 };
 
 const updateFrameProbe = (widget: Gtk.Widget, probe: FrameProbe): void => {
@@ -120,7 +122,7 @@ const updateFrameProbe = (widget: Gtk.Widget, probe: FrameProbe): void => {
 
     if (counter !== null) {
         probe.counter = counter;
-        probe.startedAt = Date.now();
+        probe.startedAt = now();
     }
 };
 
@@ -134,7 +136,7 @@ const isPresenting = (widget: Gtk.Widget, probe: FrameProbe): boolean =>
     isSurfaceOnScreen(widget) && hasFrameAdvanced(widget, probe);
 
 const isPresentationStalled = (widget: Gtk.Widget, probe: FrameProbe): boolean =>
-    Date.now() - probe.startedAt >= PRESENTATION_PROBE_MS && !isPresenting(widget, probe);
+    now() - probe.startedAt >= PRESENTATION_PROBE_MS && !isPresenting(widget, probe);
 
 const allocateRoot = (widget: Gtk.Widget): void => {
     const root = widget.getRoot();
@@ -321,14 +323,8 @@ const screenshot = async (widget: Gtk.Widget, options?: ScreenshotOptions): Prom
     return outcome.result;
 };
 
-const isWindow = (widget: Gtk.Widget): widget is Gtk.Window => widget instanceof Gtk.Window;
-const isOnScreen = (window: Gtk.Window): boolean => window.getMapped();
-const isActiveWindow = (window: Gtk.Window): boolean => window.isActive();
-
-const activeToplevel = (): Gtk.Window => {
-    const toplevels = Gtk.Window.listToplevels().filter((widget) => isWindow(widget));
-    const onScreen = toplevels.filter((window) => isOnScreen(window));
-    const target = onScreen.find((window) => isActiveWindow(window)) ?? onScreen[0];
+const screenTarget = (): Gtk.Window => {
+    const target = activeToplevel() ?? mappedToplevels()[0];
 
     if (!target) {
         throw new Error(NOTHING_ON_SCREEN_MESSAGE);
@@ -337,10 +333,7 @@ const activeToplevel = (): Gtk.Window => {
     return target;
 };
 
-const captureScreen = async (options?: ScreenshotOptions): Promise<ScreenshotResult> => {
-    const target = activeToplevel();
-
-    return screenshot(target, options);
-};
+const captureScreen = async (options?: ScreenshotOptions): Promise<ScreenshotResult> =>
+    screenshot(screenTarget(), options);
 
 export { captureScreen, screenshot };

package/src/timers.ts

@@ -0,0 +1,31 @@
+import { performance } from "node:perf_hooks";
+import { clearTimeout, setTimeout } from "node:timers";
+
+type FakeClock = { tickAsync: (ms: number) => Promise<unknown> };
+type TimeoutHandle = ReturnType<typeof setTimeout>;
+
+const now = (): number => performance.now();
+const scheduleTimeout = (callback: () => void, ms: number): TimeoutHandle => setTimeout(callback, ms);
+
+const cancelTimeout = (handle: TimeoutHandle): void => {
+    clearTimeout(handle);
+};
+
+const delay = (ms: number): Promise<void> =>
+    new Promise((resolve) => {
+        scheduleTimeout(() => {
+            resolve();
+        }, ms);
+    });
+
+const getFakeClock = (): FakeClock | null => {
+    const { clock } = globalThis.setTimeout as typeof globalThis.setTimeout & { clock?: FakeClock };
+
+    return clock ?? null;
+};
+
+const advanceFakeClock = async (ms: number): Promise<void> => {
+    await getFakeClock()?.tickAsync(ms);
+};
+
+export { advanceFakeClock, cancelTimeout, delay, now, scheduleTimeout };

package/src/traversal.ts

@@ -11,6 +11,7 @@ type QueryContainer = Gtk.Widget | Gtk.EventController | Gtk.LayoutManager | Gtk
  * sentinel representing all current toplevel windows.
  */
 type Container = QueryContainer | Gtk.Application | typeof TOPLEVELS;
+type WidgetClass<T extends Gtk.Widget> = abstract new (...args: never[]) => T;
 
 /** Container sentinel that widens a query to every toplevel window currently open. */
 const TOPLEVELS: unique symbol = Symbol("gtkx.toplevels");
@@ -50,6 +51,25 @@ const descendants = function* (widget: Gtk.Widget): Generator<Gtk.Widget> {
     yield* tree;
 };
 
+const ancestors = function* (widget: Gtk.Widget): Generator<Gtk.Widget> {
+    let parent = widget.getParent();
+
+    while (parent) {
+        yield parent;
+        parent = parent.getParent();
+    }
+};
+
+const ancestorFor = <T extends Gtk.Widget>(widget: Gtk.Widget, type: WidgetClass<T>): T | null => {
+    for (const ancestor of ancestors(widget)) {
+        if (ancestor instanceof type) {
+            return ancestor;
+        }
+    }
+
+    return null;
+};
+
 const relationCandidates = (widget: Gtk.Widget): Gtk.Accessible[] => {
     const pool: Gtk.Accessible[] = [...widget.listMnemonicLabels(), ...descendants(widget)];
     const root = widget.getRoot();
@@ -115,6 +135,8 @@ const findAll = (container: Container, isMatch: (node: Gtk.Widget) => boolean):
 
 export {
     TOPLEVELS,
+    ancestorFor,
+    ancestors,
     children,
     descendants,
     findAll,

package/src/types.ts

@@ -169,7 +169,12 @@ type QueryFamilies<Head extends unknown[]> = QueryFamily<"Role", "role", Head> &
  * React behavior toggles, error callbacks, and custom queries to bind.
  */
 type RenderOptions<Q extends QueryMap = Record<never, never>> = {
-    /** Widget or root element to mount into; an undecorated harness window is created when omitted. */
+    /**
+     * Widget or root element to mount into; an undecorated harness window is created when omitted.
+     * A widget container that sits outside every toplevel, such as a bare `Gtk.Box`, keeps the tree
+     * 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;
     /** Root of the subtree that bound queries search. */
     baseElement?: Container | undefined;

package/src/user-event/adjustment.ts

@@ -1,5 +1,6 @@
 import * as Gtk from "@gtkx/gi/gtk";
 import { scheduleNextFrame } from "../frame-sync.js";
+import { getTypeTag } from "../widget-getters.js";
 import { wrapEvent } from "./event-wrapper.js";
 
 /** A scroll distance in pixels along each axis. */
@@ -24,7 +25,7 @@ const slide = (widget: Gtk.Widget, value: number): Promise<void> =>
     wrapEvent(widget, () => {
         if (!(widget instanceof Gtk.Range)) {
             throw new TypeError(
-                `userEvent.slide requires a Gtk.Range (e.g. Gtk.Scale), got ${widget.constructor.name}`,
+                `userEvent.slide requires a Gtk.Range (e.g. Gtk.Scale), got ${getTypeTag(widget)}`,
             );
         }
 

package/src/user-event/click.ts

@@ -267,7 +267,8 @@ const tryActivate = async (widget: Gtk.Widget): Promise<boolean> => {
  * handler invokes: a list, grid, or column-view row is focused and selected, and activated as well
  * on a second press or when its view activates on a single click; an expandable tree expander
  * toggles its expansion, once per press, and only when it is the widget clicked, so a click on its
- * child falls through to the enclosing row; a column header sorts by its column. Sorting goes
+ * child falls through to the enclosing row; a notebook tab, clicked directly or through its label,
+ * focuses its notebook and switches to its page; a column header sorts by its column. Sorting goes
  * through Gtk.ColumnView.sortByColumn, so the primary sort column and order match what a pointer
  * produces while previously sorted columns are dropped rather than kept as secondary keys. A
  * column-view cell and the row that carries the column headers stand in the way of the click rather
@@ -287,14 +288,14 @@ const click = async (widget: Gtk.Widget): Promise<void> => {
  * a descendant, is activated and exclusively selected, as GTK's double-click path does whether or
  * not the container activates on a single click. A widget whose click GTK4 implements itself
  * receives that outcome once per press, so a list, grid, or column-view row is selected and then
- * activated by the second press, a tree expander ends back where it started, and a column header
- * sorts and then inverts its order.
+ * activated by the second press, a tree expander ends back where it started, a notebook tab stays on
+ * the page the first press opened, and a column header sorts and then inverts its order.
  */
 const dblClick = (widget: Gtk.Widget): Promise<void> => deliverClick(widget, 2);
 /**
  * Delivers a three-press click gesture the same way a double click is delivered, applying the same
  * outcome to a list box row or flow box child the presses reach, and applying the outcome GTK4
- * implements itself once per press to a row, tree expander, or column header.
+ * implements itself once per press to a row, tree expander, notebook tab, or column header.
  */
 const tripleClick = (widget: Gtk.Widget): Promise<void> => deliverClick(widget, 3);
 

package/src/user-event/column-header-click.ts

@@ -1,21 +1,7 @@
 import * as Gtk from "@gtkx/gi/gtk";
-import { children } from "../traversal.js";
+import { ancestorFor, children } from "../traversal.js";
 import { getWidgetTextContent } from "../widget-accessible-properties.js";
 
-const columnViewFor = (header: Gtk.Widget): Gtk.ColumnView | null => {
-    let current: Gtk.Widget | null = header.getParent();
-
-    while (current !== null) {
-        if (current instanceof Gtk.ColumnView) {
-            return current;
-        }
-
-        current = current.getParent();
-    }
-
-    return null;
-};
-
 const columnsFor = (view: Gtk.ColumnView): Gtk.ColumnViewColumn[] => {
     const model = view.getColumns();
     const columns: Gtk.ColumnViewColumn[] = [];
@@ -75,7 +61,7 @@ const nextSortDirection = (view: Gtk.ColumnView, column: Gtk.ColumnViewColumn):
 };
 
 const applyHeaderClick = (header: Gtk.Widget, nPress: number): void => {
-    const view = columnViewFor(header);
+    const view = ancestorFor(header, Gtk.ColumnView);
     const column = view === null ? null : sortableColumnFor(header, view);
 
     if (view === null || column === null) {