@gtkx/testing 1.0.0-rc.4 → 1.1.0

package/src/screenshot.ts

@@ -1,12 +1,51 @@
+import * as Gdk from "@gtkx/gi/gdk";
+import * as Graphene from "@gtkx/gi/graphene";
 import * as Gsk from "@gtkx/gi/gsk";
 import * as Gtk from "@gtkx/gi/gtk";
-import { mkdtempSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import type { ScreenshotOptions, ScreenshotResult, WindowSelector } from "./types.js";
+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;
+    startedAt: number;
+};
+
+type CaptureFailure = "no-size" | "no-content";
+
+type CaptureState = {
+    probe: FrameProbe;
+    failure: CaptureFailure | null;
+};
+
+type CaptureResult =
+    { status: "captured"; result: ScreenshotResult } |
+    { status: "failed"; failure: CaptureFailure };
+
+type CaptureOutcome =
+    { status: "captured"; result: ScreenshotResult } |
+    { status: "stalled"; failure: CaptureFailure };
 
 const DEFAULT_SCREENSHOT_INTERVAL = 10;
+const PRESENTATION_PROBE_MS = 250;
+
+const NOT_PRESENTING_MESSAGE =
+    "Screenshot failed: the display is not presenting frames to this window, so GTK has no rendered " +
+    "content to capture. The window is hidden, minimized, or its compositor is not presenting it; this " +
+    "is a display problem, not a widget problem.";
+
+const EMPTY_WIDGET_HINT =
+    "The display is presenting frames to this window, so the widget itself is empty: it painted nothing.";
+
+const OTHER_FAILURE_HINT =
+    "The display is presenting frames to this window, so the capture failed for another reason.";
+
+const NOTHING_ON_SCREEN_MESSAGE = "Nothing is on screen to capture: no toplevel window is mapped";
 
 const bytesToBase64 = (bytes: number[]): string => {
     return Buffer.from(bytes).toString("base64");
@@ -16,162 +55,285 @@ const describeWidgetState = (widget: Gtk.Widget): string =>
     `realized=${String(widget.getRealized())} mapped=${String(widget.getMapped())} ` +
     `visible=${String(widget.getVisible())}`;
 
-const captureSnapshot = (widget: Gtk.Widget, scale: number): ScreenshotResult => {
-    const paintable = new Gtk.WidgetPaintable({ widget });
+const getMappedPopovers = (widget: Gtk.Widget): Gtk.Popover[] => {
+    const popovers: Gtk.Popover[] = [];
+
+    for (const descendant of descendants(widget)) {
+        if (descendant instanceof Gtk.Popover && descendant.getMapped()) {
+            popovers.push(descendant);
+        }
+    }
+
+    return popovers;
+};
+
+const appendPopover = (snapshot: Gtk.Snapshot, target: Gtk.Widget, popover: Gtk.Popover): void => {
+    const [hasBounds, bounds] = popover.computeBounds(target);
+    const paintable = new Gtk.WidgetPaintable({ widget: popover });
     const width = paintable.getIntrinsicWidth();
     const height = paintable.getIntrinsicHeight();
 
-    if (width <= 0 || height <= 0) {
-        throw new Error(`Widget has no size: ensure it is realized and visible (${describeWidgetState(widget)})`);
+    if (!hasBounds || width <= 0 || height <= 0) {
+        return;
     }
 
-    const snapshot = new Gtk.Snapshot();
-    snapshot.scale(scale, scale);
+    snapshot.save();
+    snapshot.translate(new Graphene.Point({ x: bounds.origin.x, y: bounds.origin.y }));
     paintable.snapshot(snapshot, width, height);
-    const renderNode = snapshot.toNode();
+    snapshot.restore();
+};
 
-    if (!renderNode) {
-        throw new Error(`Widget produced no render content (${describeWidgetState(widget)})`);
+const appendPopovers = (snapshot: Gtk.Snapshot, target: Gtk.Widget): void => {
+    for (const popover of getMappedPopovers(target)) {
+        appendPopover(snapshot, target, popover);
     }
+};
 
-    const display = widget.getDisplay();
-    const renderer = new Gsk.CairoRenderer();
-    renderer.realizeForDisplay(display);
+const getSurface = (widget: Gtk.Widget): Gdk.Surface | null => widget.getNative()?.getSurface() ?? null;
+const isSurfaceOnScreen = (widget: Gtk.Widget): boolean => getSurface(widget)?.getMapped() ?? false;
 
-    try {
-        const texture = renderer.renderTexture(renderNode, null);
-        const pngBytes = texture.saveToPngBytes();
-        const data = pngBytes.getData();
+const getFrameClock = (widget: Gtk.Widget): Gdk.FrameClock | null =>
+    widget.getRoot()?.getFrameClock() ?? widget.getFrameClock();
 
-        if (!data) {
-            throw new Error("Failed to serialize screenshot to PNG");
-        }
+const getFrameCounter = (widget: Gtk.Widget): bigint | null => getFrameClock(widget)?.getFrameCounter() ?? null;
 
-        return {
-            data: bytesToBase64(data),
-            mimeType: "image/png",
-            width: Math.round(width * scale),
-            height: Math.round(height * scale),
-        };
-    } finally {
-        renderer.unrealize();
+const describePresentation = (widget: Gtk.Widget): string =>
+    `${describeWidgetState(widget)} surfaceMapped=${String(isSurfaceOnScreen(widget))} ` +
+    `frameCounter=${String(getFrameCounter(widget))}`;
+
+const requestFrame = (widget: Gtk.Widget): void => {
+    getFrameClock(widget)?.requestPhase(Gdk.FrameClockPhase.UPDATE);
+};
+
+const startFrameProbe = (widget: Gtk.Widget): FrameProbe => {
+    requestFrame(widget);
+
+    return { counter: getFrameCounter(widget), startedAt: now() };
+};
+
+const updateFrameProbe = (widget: Gtk.Widget, probe: FrameProbe): void => {
+    requestFrame(widget);
+
+    if (probe.counter !== null) {
+        return;
+    }
+
+    const counter = getFrameCounter(widget);
+
+    if (counter !== null) {
+        probe.counter = counter;
+        probe.startedAt = now();
     }
 };
 
-/**
- * Captures a PNG snapshot of a widget, retrying until it has a paintable size.
- *
- * @param widget The widget to render to an image.
- * @param options Optional scale, timeout, and retry interval.
- * @returns The base64-encoded PNG data along with its mime type and dimensions.
- */
-const screenshot = async (widget: Gtk.Widget, options?: ScreenshotOptions): Promise<ScreenshotResult> => {
-    const scale = options?.scale ?? 1;
+const hasFrameAdvanced = (widget: Gtk.Widget, probe: FrameProbe): boolean => {
+    const counter = getFrameCounter(widget);
 
-    if (!Number.isFinite(scale) || scale <= 0) {
-        throw new Error(`Screenshot scale must be a positive number, got ${String(scale)}`);
+    return counter !== null && probe.counter !== null && counter > probe.counter;
+};
+
+const isPresenting = (widget: Gtk.Widget, probe: FrameProbe): boolean =>
+    isSurfaceOnScreen(widget) && hasFrameAdvanced(widget, probe);
+
+const isPresentationStalled = (widget: Gtk.Widget, probe: FrameProbe): boolean =>
+    now() - probe.startedAt >= PRESENTATION_PROBE_MS && !isPresenting(widget, probe);
+
+const allocateRoot = (widget: Gtk.Widget): void => {
+    const root = widget.getRoot();
+
+    if (!root) {
+        return;
     }
 
-    return waitFor(() => captureSnapshot(widget, scale), {
-        timeout: options?.timeout,
-        interval: options?.interval ?? DEFAULT_SCREENSHOT_INTERVAL,
-    });
+    const width = root.getWidth();
+    const height = root.getHeight();
+
+    if (width > 0 && height > 0) {
+        root.allocate(width, height, -1, null);
+    }
 };
 
-const firstToplevelWindow = (windows: Gtk.Widget[]): Gtk.Window => {
-    const [first] = windows;
+const isDirectlyPaintable = (child: Gtk.Widget): boolean =>
+    child.getMapped() && child.getWidth() > 0 && !(child instanceof Gtk.Popover);
 
-    if (!(first instanceof Gtk.Window)) {
-        throw new TypeError("First toplevel is not a Window");
+const getPaintableNode = (widget: Gtk.Widget, scale: number, width: number, height: number): Gsk.RenderNode | null => {
+    const paintable = new Gtk.WidgetPaintable({ widget });
+    const snapshot = new Gtk.Snapshot();
+    snapshot.scale(scale, scale);
+    paintable.snapshot(snapshot, width, height);
+    appendPopovers(snapshot, widget);
+
+    return snapshot.toNode();
+};
+
+const getChildrenNode = (widget: Gtk.Widget, scale: number): Gsk.RenderNode | null => {
+    const snapshot = new Gtk.Snapshot();
+    snapshot.scale(scale, scale);
+
+    for (let child = widget.getFirstChild(); child !== null; child = child.getNextSibling()) {
+        if (isDirectlyPaintable(child)) {
+            widget.snapshotChild(child, snapshot);
+        }
     }
 
-    return first;
+    appendPopovers(snapshot, widget);
+
+    return snapshot.toNode();
 };
 
-const windowAtIndex = (windows: Gtk.Widget[], index: number): Gtk.Window => {
-    const indexed = windows[index];
+const getRenderNode = (widget: Gtk.Widget, scale: number, width: number, height: number): Gsk.RenderNode | null => {
+    const presented = getPaintableNode(widget, scale, width, height);
 
-    if (!(indexed instanceof Gtk.Window)) {
-        throw new TypeError(`Window at index ${String(index)} not found`);
+    if (presented) {
+        return presented;
     }
 
-    return indexed;
+    allocateRoot(widget);
+
+    return getPaintableNode(widget, scale, width, height) ?? getChildrenNode(widget, scale);
 };
 
-const isWindow = (widget: Gtk.Widget): widget is Gtk.Window => widget instanceof Gtk.Window;
+const renderToPng = (widget: Gtk.Widget, node: Gsk.RenderNode, width: number, height: number): ScreenshotResult => {
+    const renderer = new Gsk.CairoRenderer();
+    renderer.realizeForDisplay(widget.getDisplay());
 
-const hasMatchingTitle = (window: Gtk.Window, selector: string | RegExp): boolean => {
-    const title = window.getTitle() ?? "";
+    try {
+        const viewport = Graphene.Rect.alloc().init(0, 0, width, height);
+        const texture = renderer.renderTexture(node, viewport);
+        const data = texture.saveToPngBytes().getData();
 
-    return selector instanceof RegExp ? selector.test(title) : title.includes(selector);
+        if (!data) {
+            throw new Error("Failed to serialize screenshot to PNG");
+        }
+
+        return { data: bytesToBase64(data), mimeType: "image/png", width, height };
+    } finally {
+        renderer.unrealize();
+    }
 };
 
-const describeTitleSelector = (selector: string | RegExp): string =>
-    selector instanceof RegExp ? selector.toString() : `"${selector}"`;
+const captureSnapshot = (widget: Gtk.Widget, scale: number): CaptureResult => {
+    const paintable = new Gtk.WidgetPaintable({ widget });
+    const width = paintable.getIntrinsicWidth();
+    const height = paintable.getIntrinsicHeight();
 
-const windowByTitle = (windows: Gtk.Widget[], selector: string | RegExp): Gtk.Window => {
-    const found = windows.filter(isWindow).find((window) => hasMatchingTitle(window, selector));
+    if (width <= 0 || height <= 0) {
+        return { status: "failed", failure: "no-size" };
+    }
+
+    const renderNode = getRenderNode(widget, scale, width, height);
 
-    if (!found) {
-        throw new Error(`No window found with title matching ${describeTitleSelector(selector)}`);
+    if (!renderNode) {
+        return { status: "failed", failure: "no-content" };
     }
 
-    return found;
+    const scaledWidth = Math.round(width * scale);
+    const scaledHeight = Math.round(height * scale);
+
+    return { status: "captured", result: renderToPng(widget, renderNode, scaledWidth, scaledHeight) };
 };
 
-const resolveWindow = (selector?: WindowSelector): Gtk.Window => {
-    const windows = Gtk.Window.listToplevels();
+const failureMessage = (widget: Gtk.Widget, failure: CaptureFailure): string =>
+    failure === "no-size"
+        ? `Widget has no size: ensure it is realized and visible (${describeWidgetState(widget)})`
+        : `Widget produced no render content (${describeWidgetState(widget)})`;
 
-    if (windows.length === 0) {
-        throw new Error("No windows available for screenshot");
-    }
+const notPresentingMessage = (widget: Gtk.Widget): string =>
+    `${NOT_PRESENTING_MESSAGE} (${describePresentation(widget)})`;
+
+const stalledMessage = (widget: Gtk.Widget, failure: CaptureFailure): string =>
+    `${notPresentingMessage(widget)}\n\n${failureMessage(widget, failure)}`;
+
+const presentingHint = (failure: CaptureFailure | null): string =>
+    failure === "no-content" ? EMPTY_WIDGET_HINT : OTHER_FAILURE_HINT;
 
-    if (selector === undefined) {
-        return firstToplevelWindow(windows);
+const timeoutHint = (widget: Gtk.Widget, state: CaptureState): string =>
+    isPresenting(widget, state.probe) ? presentingHint(state.failure) : notPresentingMessage(widget);
+
+const explainTimeout = (error: Error, widget: Gtk.Widget, state: CaptureState): Error =>
+    getConfig().getElementError(`${error.message}\n\n${timeoutHint(widget, state)}`);
+
+const attemptCapture = (widget: Gtk.Widget, scale: number, state: CaptureState): CaptureOutcome => {
+    const attempt = captureSnapshot(widget, scale);
+
+    if (attempt.status === "captured") {
+        return attempt;
     }
 
-    if (typeof selector === "number") {
-        return windowAtIndex(windows, selector);
+    state.failure = attempt.failure;
+    updateFrameProbe(widget, state.probe);
+
+    if (isPresentationStalled(widget, state.probe)) {
+        return { status: "stalled", failure: attempt.failure };
     }
 
-    return windowByTitle(windows, selector);
+    throw new Error(failureMessage(widget, attempt.failure));
 };
 
-const saveScreenshotToTempFile = (result: ScreenshotResult): string => {
-    const dir = mkdtempSync(join(tmpdir(), "gtkx-screenshots-"));
-    const filepath = join(dir, "screenshot.png");
-    writeFileSync(filepath, Buffer.from(result.data, "base64"));
-
-    return filepath;
+const writeScreenshot = (result: ScreenshotResult, path: string): void => {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, Buffer.from(result.data, "base64"));
 };
 
-/**
- * Prints a clickable file URL for a saved screenshot to the console.
- *
- * @param filepath Absolute path of the saved screenshot file.
- */
-const logScreenshotPath = (filepath: string): void => {
-    console.log(`Screenshot saved: file://${filepath}`);
+const captureUntilPaintable = (
+    widget: Gtk.Widget,
+    scale: number,
+    options: ScreenshotOptions | undefined,
+): Promise<CaptureOutcome> => {
+    const state: CaptureState = { probe: startFrameProbe(widget), failure: null };
+
+    return waitFor(() => attemptCapture(widget, scale, state), {
+        timeout: options?.timeout,
+        interval: options?.interval ?? DEFAULT_SCREENSHOT_INTERVAL,
+        onTimeout: (error) => explainTimeout(error, widget, state),
+    });
 };
 
 /**
- * Captures a screenshot of a toplevel window, writes it to a temporary file,
- * logs its path, and returns the image data.
+ * Captures a PNG snapshot of a widget, retrying until it has a paintable size,
+ * and writes the image to `options.path` when one is given, creating any
+ * missing parent directories. Popovers open inside the widget render on their
+ * own surfaces, so they are composited into the image at their on-screen
+ * positions. A display that never presents a frame leaves GTK without a cached
+ * render node, so the widget's contents are then snapshotted directly; when
+ * even that yields nothing, the failure names the display instead of blaming
+ * the widget.
  *
- * @param selector Chooses the window by index, title substring, or regular
- * expression; defaults to the first toplevel.
- * @param options Optional scale, timeout, and retry interval.
+ * @param widget The widget to render to an image.
+ * @param options Optional scale, timeout, retry interval, and output path.
  * @returns The base64-encoded PNG data along with its mime type and dimensions.
  */
-const captureAndSaveScreenshot = async (
-    selector?: WindowSelector,
-    options?: ScreenshotOptions,
-): Promise<ScreenshotResult> => {
-    const target = resolveWindow(selector);
-    const result = await screenshot(target, options);
-    logScreenshotPath(saveScreenshotToTempFile(result));
+const screenshot = async (widget: Gtk.Widget, options?: ScreenshotOptions): Promise<ScreenshotResult> => {
+    const scale = options?.scale ?? 1;
 
-    return result;
+    if (!Number.isFinite(scale) || scale <= 0) {
+        throw new Error(`Screenshot scale must be a positive number, got ${String(scale)}`);
+    }
+
+    const outcome = await captureUntilPaintable(widget, scale, options);
+
+    if (outcome.status === "stalled") {
+        throw new Error(stalledMessage(widget, outcome.failure));
+    }
+
+    if (options?.path) {
+        writeScreenshot(outcome.result, options.path);
+    }
+
+    return outcome.result;
 };
 
-export { screenshot, logScreenshotPath, captureAndSaveScreenshot };
+const screenTarget = (): Gtk.Window => {
+    const target = activeToplevel() ?? mappedToplevels()[0];
+
+    if (!target) {
+        throw new Error(NOTHING_ON_SCREEN_MESSAGE);
+    }
+
+    return target;
+};
+
+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,28 +11,76 @@ 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");
 
 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 traverseWidgetTree = function* (
+    root: Gtk.Widget,
+    isIncluded: (widget: Gtk.Widget) => boolean,
+): Generator<Gtk.Widget> {
+    if (isIncluded(root)) {
+        yield root;
+    }
 
-const traverseWidgetTree = function* (root: Gtk.Widget): Generator<Gtk.Widget> {
-    yield root;
     let child = root.getFirstChild();
 
     while (child) {
-        yield* traverseWidgetTree(child);
+        yield* traverseWidgetTree(child, isIncluded);
+        child = child.getNextSibling();
+    }
+};
+
+const children = function* (widget: Gtk.Widget): Generator<Gtk.Widget> {
+    let child = widget.getFirstChild();
+
+    while (child) {
+        yield child;
         child = child.getNextSibling();
     }
 };
 
 const descendants = function* (widget: Gtk.Widget): Generator<Gtk.Widget> {
-    const tree = traverseWidgetTree(widget);
+    const tree = traverseWidgetTree(widget, isAnyWidget);
     tree.next();
     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();
+
+    if (root instanceof Gtk.Widget) {
+        pool.push(...traverseWidgetTree(root, isAnyWidget));
+    }
+
+    return [...new Set(pool)];
+};
+
 const resolveRoot = (container: QueryContainer): Gtk.Widget | null => {
     if (container instanceof Gtk.Widget) {
         return container;
@@ -69,7 +117,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);
+        yield* traverseWidgetTree(root, isOnScreen);
     }
 };
 
@@ -85,4 +133,16 @@ const findAll = (container: Container, isMatch: (node: Gtk.Widget) => boolean):
     return results;
 };
 
-export { TOPLEVELS, descendants, roots, traverse, findAll, type Container };
+export {
+    TOPLEVELS,
+    ancestorFor,
+    ancestors,
+    children,
+    descendants,
+    findAll,
+    isOnScreen,
+    relationCandidates,
+    roots,
+    traverse,
+    type Container,
+};