@gtkx/testing 1.0.0-rc.1 → 1.0.0-rc.2

package/src/frame-sync.ts

@@ -1,34 +1,51 @@
 import type * as Gtk from "@gtkx/gi/gtk";
+import * as GLib from "@gtkx/gi/glib";
 
 const CLOCK_STALL_FALLBACK_MS = 500;
 
-export const scheduleAfterLayout = (widget: Gtk.Widget | null, callback: () => void): void => {
-    let done = false;
-    let removeTick: (() => void) | null = null;
-    let fallback: ReturnType<typeof setTimeout> | null = null;
-
-    const finish = (): void => {
-        if (done) return;
-        done = true;
-        if (fallback !== null) clearTimeout(fallback);
-        removeTick?.();
-        removeTick = null;
-        fallback = null;
+const once = (callback: () => void): (() => void) => {
+    let isCalled = false;
+
+    return () => {
+        if (isCalled) {
+            return;
+        }
+
+        isCalled = true;
         callback();
     };
+};
 
-    if (widget === null || widget.getFrameClock() === null || widget.getWidth() > 0) {
-        queueMicrotask(finish);
-        return;
-    }
+const runWhenSized = (widget: Gtk.Widget, finish: () => void): void => {
+    let tickId = 0;
+
+    const fallback = setTimeout(() => {
+        widget.removeTickCallback(tickId);
+        finish();
+    }, CLOCK_STALL_FALLBACK_MS);
 
-    fallback = setTimeout(finish, CLOCK_STALL_FALLBACK_MS);
+    tickId = widget.addTickCallback(() => {
+        if (widget.getWidth() === 0) {
+            return GLib.SOURCE_CONTINUE;
+        }
 
-    const tickId = widget.addTickCallback(() => {
-        if (widget.getWidth() === 0) return true;
+        clearTimeout(fallback);
         finish();
-        return false;
+
+        return GLib.SOURCE_REMOVE;
     });
+};
+
+const scheduleAfterLayout = (widget: Gtk.Widget | null, callback: () => void): void => {
+    const finish = once(callback);
+
+    if (widget?.getFrameClock() == null || widget.getWidth() > 0) {
+        queueMicrotask(finish);
 
-    removeTick = () => widget.removeTickCallback(tickId);
+        return;
+    }
+
+    runWhenSized(widget, finish);
 };
+
+export { scheduleAfterLayout };

package/src/index.ts

@@ -48,8 +48,8 @@ export {
     queryByRole,
     queryByText,
 } from "./queries.js";
-export { cleanup, render } from "./render.js";
 export { renderHook } from "./render-hook.js";
+export { cleanup, render } from "./render.js";
 export { formatRole, getRoles, logRoles, prettyRoles } from "./role-helpers.js";
 export { screen } from "./screen.js";
 export { captureAndSaveScreenshot, logScreenshotPath, screenshot } from "./screenshot.js";
@@ -79,6 +79,7 @@ export type {
     DropContent,
     DropOptions,
     PointerInput,
+    ScrollDelta,
     TabOptions,
     TypeOptions,
     UserEvent,

package/src/matchers.ts

@@ -13,188 +13,239 @@ import {
 } from "./widget-accessible-properties.js";
 
 /** The expected value for a text matcher: an exact string or a regular expression. */
-export type TextExpectation = string | RegExp;
-
+type TextExpectation = string | RegExp;
 type MatcherResult = { pass: boolean; message: () => string };
+type TextMatcher = (received: unknown, expected?: TextExpectation) => MatcherResult;
+type StateMatcher = (received: unknown) => MatcherResult;
+type ValueMatcher = (received: unknown, expected: number) => MatcherResult;
+type TextMatcherContext = { matcherName: string; widget: Gtk.Widget; actual: string | null };
 
-interface MatcherContext {
-    isNot: boolean;
-}
+type MatcherImplementations = {
+    toHaveDisplayValue: TextMatcher;
+    toHaveTextContent: TextMatcher;
+    toHaveAccessibleName: TextMatcher;
+    toHavePlaceholderText: TextMatcher;
+    toBeChecked: StateMatcher;
+    toBePressed: StateMatcher;
+    toBeExpanded: StateMatcher;
+    toBeSelected: StateMatcher;
+    toHaveValue: ValueMatcher;
+};
+
+type ExpectExtend = { extend: (m: MatcherImplementations) => void };
+
+const toHaveDisplayValue: TextMatcher = textMatcher("toHaveDisplayValue", getWidgetDisplayValue, "exact");
+
+const toHaveTextContent: TextMatcher = textMatcher(
+    "toHaveTextContent",
+    (widget) => getWidgetNodeText(widget) ?? getWidgetAccessibleName(widget),
+    "substring",
+);
+
+const toHaveAccessibleName: TextMatcher = textMatcher("toHaveAccessibleName", getWidgetAccessibleName, "exact");
+
+const toHavePlaceholderText: TextMatcher = textMatcher(
+    "toHavePlaceholderText",
+    getWidgetPlaceholderText,
+    "exact",
+);
+
+const toBeChecked: StateMatcher = booleanStateMatcher("toBeChecked", "checked", getWidgetCheckedState);
+const toBePressed: StateMatcher = booleanStateMatcher("toBePressed", "pressed", getWidgetPressedState);
+const toBeExpanded: StateMatcher = booleanStateMatcher("toBeExpanded", "expanded", getWidgetExpandedState);
+const toBeSelected: StateMatcher = booleanStateMatcher("toBeSelected", "selected", getWidgetSelectedState);
+
+/** The widget assertion matchers keyed by name, suitable for passing to `expect.extend`. */
+const matchers: MatcherImplementations = {
+    toHaveDisplayValue,
+    toHaveTextContent,
+    toHaveAccessibleName,
+    toHavePlaceholderText,
+    toBeChecked,
+    toBePressed,
+    toBeExpanded,
+    toBeSelected,
+    toHaveValue,
+};
 
-type TextMatcher = (this: MatcherContext, received: unknown, expected?: TextExpectation) => MatcherResult;
-type StateMatcher = (this: MatcherContext, received: unknown) => MatcherResult;
-type ValueMatcher = (this: MatcherContext, received: unknown, expected: number) => MatcherResult;
+const registration = { isRegistered: false };
 
 const asWidget = (received: unknown, matcherName: string): Gtk.Widget => {
     if (!(received instanceof Gtk.Widget)) {
         throw new TypeError(`${matcherName}: received value must be a Gtk.Widget, got ${typeof received}`);
     }
+
     return received;
 };
 
 const describeWidget = (widget: Gtk.Widget): string => {
     const role = Gtk.AccessibleRole[widget.getAccessibleRole()];
     const name = getWidgetAccessibleName(widget);
-    return name !== null ? `<${role} name=${JSON.stringify(name)}>` : `<${role}>`;
+
+    return name === null ? `<${role}>` : `<${role} name=${JSON.stringify(name)}>`;
 };
 
-const matchesText = (actual: string, expected: TextExpectation, mode: "exact" | "substring"): boolean => {
+const isTextMatch = (actual: string, expected: TextExpectation, mode: "exact" | "substring"): boolean => {
     if (expected instanceof RegExp) {
         expected.lastIndex = 0;
+
         return expected.test(actual);
     }
+
     return mode === "exact" ? actual === expected : actual.includes(expected);
 };
 
 const describeExpected = (expected: TextExpectation): string =>
     expected instanceof RegExp ? String(expected) : JSON.stringify(expected);
 
-const textMatcher = (
+const negationPrefix = (isPass: boolean): string => (isPass ? "not " : "");
+
+const nonEmptyResult = ({ matcherName, widget, actual }: TextMatcherContext): MatcherResult => {
+    const isPass = actual !== null && actual !== "";
+
+    return {
+        pass: isPass,
+        message: () =>
+            `expected widget ${negationPrefix(isPass)}to have a non-empty value for ${matcherName}, ` +
+            `but got ${JSON.stringify(actual)}\n${describeWidget(widget)}`,
+    };
+};
+
+const matchedResult = (context: TextMatcherContext, expected: TextExpectation, isPass: boolean): MatcherResult => ({
+    pass: isPass,
+    message: () =>
+        `expected widget ${negationPrefix(isPass)}${context.matcherName} ${describeExpected(expected)}, ` +
+        `but received ${JSON.stringify(context.actual)}\n${describeWidget(context.widget)}`,
+});
+
+function textMatcher(
     matcherName: string,
     read: (widget: Gtk.Widget) => string | null,
     mode: "exact" | "substring",
-): TextMatcher =>
-    function (this: MatcherContext, received: unknown, expected?: TextExpectation): MatcherResult {
+): TextMatcher {
+    return (received: unknown, expected?: TextExpectation): MatcherResult => {
         const widget = asWidget(received, matcherName);
         const actual = read(widget);
+        const context: TextMatcherContext = { matcherName, widget, actual };
 
         if (expected === undefined) {
-            const pass = actual !== null && actual !== "";
-            return {
-                pass,
-                message: () =>
-                    `expected widget ${this.isNot ? "not " : ""}to have a non-empty value for ${matcherName}, ` +
-                    `but got ${JSON.stringify(actual)}\n${describeWidget(widget)}`,
-            };
+            return nonEmptyResult(context);
         }
 
-        const pass = actual !== null && matchesText(actual, expected, mode);
-        return {
-            pass,
-            message: () =>
-                `expected widget ${this.isNot ? "not " : ""}${matcherName} ${describeExpected(expected)}, ` +
-                `but received ${JSON.stringify(actual)}\n${describeWidget(widget)}`,
-        };
+        return matchedResult(context, expected, actual !== null && isTextMatch(actual, expected, mode));
     };
+}
 
-const booleanStateMatcher = (
+function booleanStateMatcher(
     matcherName: string,
     stateName: string,
     read: (widget: Gtk.Widget) => boolean | null,
-): StateMatcher =>
-    function (this: MatcherContext, received: unknown): MatcherResult {
+): StateMatcher {
+    return (received: unknown): MatcherResult => {
         const widget = asWidget(received, matcherName);
         const state = read(widget);
+
         if (state === null) {
             throw new Error(
                 `${matcherName}: widget does not expose a ${stateName} state ` +
-                    `(role ${Gtk.AccessibleRole[widget.getAccessibleRole()]})\n${describeWidget(widget)}`,
+                `(role ${Gtk.AccessibleRole[widget.getAccessibleRole()]})\n${describeWidget(widget)}`,
             );
         }
+
         return {
             pass: state,
-            message: () => `expected widget ${this.isNot ? "not " : ""}to be ${stateName}\n${describeWidget(widget)}`,
+            message: () =>
+                `expected widget ${negationPrefix(state)}to be ${stateName}\n${describeWidget(widget)}`,
         };
     };
+}
 
-export const toHaveDisplayValue: TextMatcher = textMatcher("toHaveDisplayValue", getWidgetDisplayValue, "exact");
-export const toHaveTextContent: TextMatcher = textMatcher(
-    "toHaveTextContent",
-    (widget) => getWidgetNodeText(widget) ?? getWidgetAccessibleName(widget),
-    "substring",
-);
-export const toHaveAccessibleName: TextMatcher = textMatcher("toHaveAccessibleName", getWidgetAccessibleName, "exact");
-export const toHavePlaceholderText: TextMatcher = textMatcher(
-    "toHavePlaceholderText",
-    getWidgetPlaceholderText,
-    "exact",
-);
-
-export const toBeChecked: StateMatcher = booleanStateMatcher("toBeChecked", "checked", getWidgetCheckedState);
-export const toBePressed: StateMatcher = booleanStateMatcher("toBePressed", "pressed", getWidgetPressedState);
-export const toBeExpanded: StateMatcher = booleanStateMatcher("toBeExpanded", "expanded", getWidgetExpandedState);
-export const toBeSelected: StateMatcher = booleanStateMatcher("toBeSelected", "selected", getWidgetSelectedState);
-
-export const toHaveValue: ValueMatcher = function (
-    this: MatcherContext,
-    received: unknown,
-    expected: number,
-): MatcherResult {
+function toHaveValue(received: unknown, expected: number): MatcherResult {
     const widget = asWidget(received, "toHaveValue");
     const actual = getWidgetValue(widget).now;
+
     if (actual === null) {
         throw new Error(
-            `toHaveValue: widget does not expose a numeric value ` +
-                `(role ${Gtk.AccessibleRole[widget.getAccessibleRole()]})\n${describeWidget(widget)}`,
+            "toHaveValue: widget does not expose a numeric value " +
+            `(role ${Gtk.AccessibleRole[widget.getAccessibleRole()]})\n${describeWidget(widget)}`,
         );
     }
+
+    const isPass = actual === expected;
+
     return {
-        pass: actual === expected,
+        pass: isPass,
         message: () =>
-            `expected widget ${this.isNot ? "not " : ""}to have value ${expected}, but received ${actual}\n${describeWidget(widget)}`,
+            `expected widget ${negationPrefix(isPass)}to have value ${String(expected)}, ` +
+            `but received ${String(actual)}\n${describeWidget(widget)}`,
     };
-};
-
-interface MatcherImplementations {
-    toHaveDisplayValue: TextMatcher;
-    toHaveTextContent: TextMatcher;
-    toHaveAccessibleName: TextMatcher;
-    toHavePlaceholderText: TextMatcher;
-    toBeChecked: StateMatcher;
-    toBePressed: StateMatcher;
-    toBeExpanded: StateMatcher;
-    toBeSelected: StateMatcher;
-    toHaveValue: ValueMatcher;
 }
 
-/** The widget assertion matchers keyed by name, suitable for passing to `expect.extend`. */
-export const matchers: MatcherImplementations = {
-    toHaveDisplayValue,
-    toHaveTextContent,
-    toHaveAccessibleName,
-    toHavePlaceholderText,
-    toBeChecked,
-    toBePressed,
-    toBeExpanded,
-    toBeSelected,
-    toHaveValue,
-};
-
-type ExpectExtend = { extend: (m: MatcherImplementations) => void };
-
 const globalExpect = (): ExpectExtend | null => {
     const candidate: unknown = Reflect.get(globalThis, "expect");
+
     if (candidate && typeof (candidate as ExpectExtend).extend === "function") {
         return candidate as ExpectExtend;
     }
+
     return null;
 };
 
-let registered = false;
-
 /** Registers the widget matchers on the global `expect`, when one is available. Safe to call more than once. */
-export const registerMatchers = (): void => {
-    if (registered) return;
+const registerMatchers = (): void => {
+    if (registration.isRegistered) {
+        return;
+    }
+
     const expect = globalExpect();
-    if (!expect) return;
+
+    if (!expect) {
+        return;
+    }
+
     expect.extend(matchers);
-    registered = true;
+    registration.isRegistered = true;
 };
 
-interface WidgetMatchers<R = void> {
-    toHaveDisplayValue(expected?: TextExpectation): R;
-    toHaveTextContent(expected?: TextExpectation): R;
-    toHaveAccessibleName(expected?: TextExpectation): R;
-    toHavePlaceholderText(expected?: TextExpectation): R;
-    toBeChecked(): R;
-    toBePressed(): R;
-    toBeExpanded(): R;
-    toBeSelected(): R;
-    toHaveValue(expected: number): R;
-}
-
 declare module "@vitest/expect" {
-    // biome-ignore lint/suspicious/noExplicitAny: must match the `Assertion<T>` signature it augments for declaration merging
-    interface Assertion<T = any> extends WidgetMatchers {}
-    interface AsymmetricMatchersContaining extends WidgetMatchers {}
+    /* eslint-disable @typescript-eslint/consistent-type-definitions -- declaration merging requires interfaces */
+    interface Assertion {
+        toHaveDisplayValue(expected?: TextExpectation): void;
+        toHaveTextContent(expected?: TextExpectation): void;
+        toHaveAccessibleName(expected?: TextExpectation): void;
+        toHavePlaceholderText(expected?: TextExpectation): void;
+        toBeChecked(): void;
+        toBePressed(): void;
+        toBeExpanded(): void;
+        toBeSelected(): void;
+        toHaveValue(expected: number): void;
+    }
+
+    interface AsymmetricMatchersContaining {
+        toHaveDisplayValue(expected?: TextExpectation): void;
+        toHaveTextContent(expected?: TextExpectation): void;
+        toHaveAccessibleName(expected?: TextExpectation): void;
+        toHavePlaceholderText(expected?: TextExpectation): void;
+        toBeChecked(): void;
+        toBePressed(): void;
+        toBeExpanded(): void;
+        toBeSelected(): void;
+        toHaveValue(expected: number): void;
+    }
+    /* eslint-enable @typescript-eslint/consistent-type-definitions */
 }
+
+export {
+    toHaveDisplayValue,
+    toHaveTextContent,
+    toHaveAccessibleName,
+    toHavePlaceholderText,
+    toBeChecked,
+    toBePressed,
+    toBeExpanded,
+    toBeSelected,
+    matchers,
+    toHaveValue,
+    registerMatchers,
+    type TextExpectation,
+};