@gtkx/testing 1.0.0-rc.3 → 1.0.0

package/src/matchers.ts

@@ -1,8 +1,25 @@
-/// <reference types="@vitest/expect" />
+import type { SyncExpectationResult } from "@vitest/expect";
 import * as GObject from "@gtkx/gi/gobject";
 import * as Gtk from "@gtkx/gi/gtk";
+import type { ByRoleOptions, Matcher, MatcherOptions } from "./types.js";
+import {
+    ACCESSIBLE_NUMBER_TOLERANCE,
+    type AccessibleAttributeValue,
+    isAccessibleNumberMatch,
+    isAccessibleNumberProperty,
+    readAccessibleProperty,
+    readAccessibleState,
+} from "./accessible-native.js";
 import { getDefaultNormalizer } from "./normalize.js";
+import {
+    queryAllByDisplayValue,
+    queryAllByLabelText,
+    queryAllByPlaceholderText,
+    queryAllByRole,
+    queryAllByText,
+} from "./queries.js";
 import { formatRole } from "./role-helpers.js";
+import { type Container, descendants } from "./traversal.js";
 import {
     type CheckedState,
     getWidgetAccessibleName,
@@ -10,18 +27,16 @@ import {
     getWidgetDescribedByText,
     getWidgetDisplayValue,
     getWidgetErrorMessage,
-    getWidgetExpandedState,
     getWidgetInvalidState,
     getWidgetLabelText,
-    getWidgetPlaceholderText,
     getWidgetPressedState,
     getWidgetRequiredState,
-    getWidgetSelectedState,
     getWidgetSelection,
     getWidgetTextContent,
-    getWidgetValue,
+    getWidgetValueNow,
     hasDisplayValue,
     isWidgetDisabled,
+    isWidgetValueMatch,
     isWidgetVisible,
 } from "./widget-accessible-properties.js";
 
@@ -39,51 +54,196 @@ type TextContentOptions = {
 
 /** The expected value for a style class: an exact class name or a regular expression. */
 type ClassExpectation = string | RegExp;
-type MatcherResult = { pass: boolean; message: () => string };
-type MatcherContext = { equals: (actual: unknown, expected: unknown) => boolean };
+/** The outcome of a matcher: whether it passed, and the failure text built on demand. */
+type MatcherResult = Pick<SyncExpectationResult, "message" | "pass">;
+
+/** The matcher state bound as `this`, supplying the test runner's deep equality check. */
+type MatcherContext = {
+    /** Compares a received value against an expected one, resolving asymmetric matchers. */
+    equals: (actual: unknown, expected: unknown) => boolean;
+};
+
+/** Compares text read from the received widget; with no expected value, asserts the text is non-empty. */
 type TextMatcher = (received: unknown, expected?: TextExpectation) => MatcherResult;
+/** Asserts a single state of the received widget, taking no expected value. */
 type StateMatcher = (received: unknown) => MatcherResult;
+/** Trailing arguments of the `ByRole` query family, as a containment matcher takes them. */
+type RoleQueryArgs = [role: Gtk.AccessibleRole, options?: ByRoleOptions];
+/** Trailing arguments of the text-based query families, as a containment matcher takes them. */
+type TextQueryArgs = [text: Matcher, options?: MatcherOptions];
+/** Counts the descendants a query family finds under the received widget. */
+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 BooleanAccessibleState =
+    Gtk.AccessibleState.BUSY |
+    Gtk.AccessibleState.DISABLED |
+    Gtk.AccessibleState.EXPANDED |
+    Gtk.AccessibleState.HIDDEN |
+    Gtk.AccessibleState.SELECTED |
+    Gtk.AccessibleState.VISITED;
+
+type TristateAccessibleState = Gtk.AccessibleState.CHECKED | Gtk.AccessibleState.PRESSED;
+
+type StringAccessibleProperty =
+    Gtk.AccessibleProperty.DESCRIPTION |
+    Gtk.AccessibleProperty.HELP_TEXT |
+    Gtk.AccessibleProperty.KEY_SHORTCUTS |
+    Gtk.AccessibleProperty.LABEL |
+    Gtk.AccessibleProperty.PLACEHOLDER |
+    Gtk.AccessibleProperty.ROLE_DESCRIPTION |
+    Gtk.AccessibleProperty.VALUE_TEXT;
+
+type BooleanAccessibleProperty =
+    Gtk.AccessibleProperty.HAS_POPUP |
+    Gtk.AccessibleProperty.MODAL |
+    Gtk.AccessibleProperty.MULTI_LINE |
+    Gtk.AccessibleProperty.MULTI_SELECTABLE |
+    Gtk.AccessibleProperty.READ_ONLY |
+    Gtk.AccessibleProperty.REQUIRED;
+
+type NumberAccessibleProperty =
+    Gtk.AccessibleProperty.LEVEL |
+    Gtk.AccessibleProperty.VALUE_MAX |
+    Gtk.AccessibleProperty.VALUE_MIN |
+    Gtk.AccessibleProperty.VALUE_NOW;
+
+/** A text matcher that also takes normalization options for the text it reads. */
 type TextContentMatcher = (
     received: unknown,
     expected?: TextExpectation,
     options?: TextContentOptions,
 ) => MatcherResult;
 
+/** Signatures of the widget assertion matchers, keyed by the name each is registered under. */
 type MatcherImplementations = {
+    /** Asserts the text an editable widget or combo box shows; with no argument, that it is not empty. */
     toHaveDisplayValue: TextMatcher;
+    /** Asserts the widget's own text, or its descendants' when it has none, contains or matches the expectation. */
     toHaveTextContent: TextContentMatcher;
+    /** Asserts the widget's accessible name; with no argument, that it has one. */
     toHaveAccessibleName: TextMatcher;
+    /**
+     * Asserts the joined accessible names of the widget's `described-by` targets, falling back to its
+     * `description` and then to its tooltip.
+     */
     toHaveAccessibleDescription: TextMatcher;
+    /** Asserts the joined accessible names of the widget's `error-message` targets, read only while it is invalid. */
     toHaveAccessibleErrorMessage: TextMatcher;
-    toHavePlaceholderText: TextMatcher;
+    /** Asserts the text currently selected in an editable widget. */
     toHaveSelection: TextMatcher;
+    /**
+     * Asserts an accessible state GTK holds for the widget, taking the value type that state carries.
+     * With no expected value, asserts only that the state is set to something determinate.
+     */
+    toHaveAccessibleState: (
+        received: unknown,
+        state: Gtk.AccessibleState,
+        expected?: boolean | number,
+    ) => MatcherResult;
+    /**
+     * Asserts an accessible property GTK holds for the widget, taking the value type that property
+     * carries. With no expected value, asserts only that the property is set. Numeric properties
+     * compare the way `toHaveValue` and the `value` option of the `ByRole` queries do, within 0.001.
+     */
+    toHaveAccessibleProperty: (
+        received: unknown,
+        property: Gtk.AccessibleProperty,
+        expected?: AccessibleAttributeValue,
+    ) => MatcherResult;
+    /** Asserts the widget's checked state is checked rather than unchecked or mixed. */
     toBeChecked: StateMatcher;
+    /** Asserts the widget's checked state is mixed. */
     toBePartiallyChecked: StateMatcher;
+    /** Asserts a `Gtk.ToggleButton` is active, and throws for any other widget. */
     toBePressed: StateMatcher;
-    toBeExpanded: StateMatcher;
-    toBeSelected: StateMatcher;
+    /** Asserts the widget's accessible pressed state is mixed, and throws when it exposes none. */
+    toBePartiallyPressed: StateMatcher;
+    /** Asserts the widget is insensitive, or sits inside an insensitive ancestor. */
     toBeDisabled: StateMatcher;
+    /** Asserts the widget and all of its ancestors are sensitive. */
     toBeEnabled: StateMatcher;
+    /** Asserts the widget and its ancestors are all visible, and that none of them is fully transparent. */
     toBeVisible: StateMatcher;
+    /** Asserts the widget's root is a window that is still in the toplevel list. */
     toBeRooted: StateMatcher;
-    toBeEmpty: StateMatcher;
+    /** Asserts the widget has neither a child nor label text. */
+    toBeEmptyWidget: StateMatcher;
+    /** Asserts the widget's accessible invalid state is set to anything other than false. */
     toBeInvalid: StateMatcher;
+    /** Asserts the widget's accessible invalid state is unset or false. */
     toBeValid: StateMatcher;
+    /** Asserts the widget's accessible required state. */
     toBeRequired: StateMatcher;
+    /** Asserts the widget holds the platform focus state. */
     toHaveFocus: StateMatcher;
+    /**
+     * Asserts a widget's numeric value, or its display value when a string is given.
+     *
+     * Numbers come from the accessibility tree, which GTK keeps to a resolution of 0.001: it drops an
+     * update whose value is nearer than that to the one already published, so a widget that moves by
+     * less keeps its previous value. Numbers therefore match within 0.001, the same tolerance the
+     * `value` option of the `ByRole` queries and `toHaveAccessibleProperty` apply. That option reads
+     * the same tree, where the maximum of a paged widget such as a scrollbar is the last value it can
+     * reach, its adjustment's upper bound less one page.
+     */
     toHaveValue: (received: unknown, expected?: number | string) => MatcherResult;
+    /** 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;
+    /** Asserts the widget comes before the given widget in the widget tree, neither containing the other. */
+    toAppearBefore: (received: unknown, other: Gtk.Widget) => MatcherResult;
+    /** Asserts the widget comes after the given widget in the widget tree, neither containing the other. */
+    toAppearAfter: (received: unknown, other: Gtk.Widget) => 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. */
+    toContainOneByRole: ContainmentMatcher<RoleQueryArgs>;
+    /** Asserts at least one widget under the received one matches the `ByText` query. */
+    toContainAnyByText: ContainmentMatcher<TextQueryArgs>;
+    /** Asserts exactly one widget under the received one matches the `ByText` query. */
+    toContainOneByText: ContainmentMatcher<TextQueryArgs>;
+    /** Asserts at least one widget under the received one matches the `ByLabelText` query. */
+    toContainAnyByLabelText: ContainmentMatcher<TextQueryArgs>;
+    /** Asserts exactly one widget under the received one matches the `ByLabelText` query. */
+    toContainOneByLabelText: ContainmentMatcher<TextQueryArgs>;
+    /** Asserts at least one widget under the received one matches the `ByPlaceholderText` query. */
+    toContainAnyByPlaceholderText: ContainmentMatcher<TextQueryArgs>;
+    /** Asserts exactly one widget under the received one matches the `ByPlaceholderText` query. */
+    toContainOneByPlaceholderText: ContainmentMatcher<TextQueryArgs>;
+    /** Asserts at least one widget under the received one matches the `ByDisplayValue` query. */
+    toContainAnyByDisplayValue: ContainmentMatcher<TextQueryArgs>;
+    /** Asserts exactly one widget under the received one matches the `ByDisplayValue` query. */
+    toContainOneByDisplayValue: ContainmentMatcher<TextQueryArgs>;
+    /**
+     * Asserts the widget carries every given style class, each a name, a space-separated list, or a pattern.
+     * Pass `{ exact: true }` last to require exactly that set, which rules out patterns.
+     */
     toHaveClass: (received: unknown, ...args: unknown[]) => MatcherResult;
+    /**
+     * Asserts a GObject property, named as in GObject and looked up by its camel-cased accessor, equals the
+     * expected value. With no expected value, asserts the property is set. GObject values compare by identity.
+     */
     toHaveObjectProperty: (this: MatcherContext, received: unknown, ...args: unknown[]) => MatcherResult;
 };
 
 type ExpectExtend = { extend: (m: MatcherImplementations) => void };
 
+type AttributeExpectation = {
+    label: string;
+    comparison: string;
+    expected: AccessibleAttributeValue;
+    actual: AccessibleAttributeValue | null;
+    isPass: boolean;
+    isReadingRounded: boolean;
+};
+
 const registration = { isRegistered: false };
+const MIXED_TRISTATE: number = Gtk.AccessibleTristate.MIXED;
+const ROUNDED_READING = ", which the accessibility tree rounds to six significant digits";
 const displayValueMatcher: TextMatcher = textMatcher("toHaveDisplayValue", getWidgetDisplayValue, "exact");
 const toHaveAccessibleName: TextMatcher = textMatcher("toHaveAccessibleName", getWidgetAccessibleName, "exact");
 
@@ -99,13 +259,70 @@ const toHaveAccessibleErrorMessage: TextMatcher = textMatcher(
     "exact",
 );
 
-const toHavePlaceholderText: TextMatcher = textMatcher("toHavePlaceholderText", getWidgetPlaceholderText, "exact");
 const toHaveSelection: TextMatcher = textMatcher("toHaveSelection", getWidgetSelection, "exact");
 const toBePressed: StateMatcher = booleanStateMatcher("toBePressed", "pressed", getWidgetPressedState);
-const toBeExpanded: StateMatcher = booleanStateMatcher("toBeExpanded", "expanded", getWidgetExpandedState);
-const toBeSelected: StateMatcher = booleanStateMatcher("toBeSelected", "selected", getWidgetSelectedState);
 const toBeRequired: StateMatcher = booleanStateMatcher("toBeRequired", "required", getWidgetRequiredState);
 
+const toContainAnyByRole: ContainmentMatcher<RoleQueryArgs> = containmentMatcher(
+    "toContainAnyByRole",
+    false,
+    queryAllByRole,
+);
+
+const toContainOneByRole: ContainmentMatcher<RoleQueryArgs> = containmentMatcher(
+    "toContainOneByRole",
+    true,
+    queryAllByRole,
+);
+
+const toContainAnyByText: ContainmentMatcher<TextQueryArgs> = containmentMatcher(
+    "toContainAnyByText",
+    false,
+    queryAllByText,
+);
+
+const toContainOneByText: ContainmentMatcher<TextQueryArgs> = containmentMatcher(
+    "toContainOneByText",
+    true,
+    queryAllByText,
+);
+
+const toContainAnyByLabelText: ContainmentMatcher<TextQueryArgs> = containmentMatcher(
+    "toContainAnyByLabelText",
+    false,
+    queryAllByLabelText,
+);
+
+const toContainOneByLabelText: ContainmentMatcher<TextQueryArgs> = containmentMatcher(
+    "toContainOneByLabelText",
+    true,
+    queryAllByLabelText,
+);
+
+const toContainAnyByPlaceholderText: ContainmentMatcher<TextQueryArgs> = containmentMatcher(
+    "toContainAnyByPlaceholderText",
+    false,
+    queryAllByPlaceholderText,
+);
+
+const toContainOneByPlaceholderText: ContainmentMatcher<TextQueryArgs> = containmentMatcher(
+    "toContainOneByPlaceholderText",
+    true,
+    queryAllByPlaceholderText,
+);
+
+const toContainAnyByDisplayValue: ContainmentMatcher<TextQueryArgs> = containmentMatcher(
+    "toContainAnyByDisplayValue",
+    false,
+    queryAllByDisplayValue,
+);
+
+const toContainOneByDisplayValue: ContainmentMatcher<TextQueryArgs> = containmentMatcher(
+    "toContainOneByDisplayValue",
+    true,
+    queryAllByDisplayValue,
+);
+
 /** The widget assertion matchers keyed by name, suitable for passing to `expect.extend`. */
 const matchers: MatcherImplementations = {
     toHaveDisplayValue,
@@ -113,18 +330,18 @@ const matchers: MatcherImplementations = {
     toHaveAccessibleName,
     toHaveAccessibleDescription,
     toHaveAccessibleErrorMessage,
-    toHavePlaceholderText,
     toHaveSelection,
+    toHaveAccessibleState,
+    toHaveAccessibleProperty,
     toBeChecked,
     toBePartiallyChecked,
     toBePressed,
-    toBeExpanded,
-    toBeSelected,
+    toBePartiallyPressed,
     toBeDisabled,
     toBeEnabled,
     toBeVisible,
     toBeRooted,
-    toBeEmpty,
+    toBeEmptyWidget,
     toBeInvalid,
     toBeValid,
     toBeRequired,
@@ -132,6 +349,18 @@ const matchers: MatcherImplementations = {
     toHaveValue,
     toHaveRole,
     toContainElement,
+    toAppearBefore,
+    toAppearAfter,
+    toContainAnyByRole,
+    toContainOneByRole,
+    toContainAnyByText,
+    toContainOneByText,
+    toContainAnyByLabelText,
+    toContainOneByLabelText,
+    toContainAnyByPlaceholderText,
+    toContainOneByPlaceholderText,
+    toContainAnyByDisplayValue,
+    toContainOneByDisplayValue,
     toHaveClass,
     toHaveObjectProperty,
 };
@@ -200,6 +429,75 @@ const stateResult = (widget: Gtk.Widget, stateName: string, isPass: boolean): Ma
     message: () => `expected widget ${negationPrefix(isPass)}to be ${stateName}\n${describeWidget(widget)}`,
 });
 
+const describeAttributeValue = (value: AccessibleAttributeValue | null): string =>
+    value === null ? "unset" : JSON.stringify(value);
+
+const attributeSetResult = (
+    widget: Gtk.Widget,
+    label: string,
+    actual: AccessibleAttributeValue | null,
+): MatcherResult => {
+    const isSet = actual !== null;
+
+    return {
+        pass: isSet,
+        message: () => `expected widget ${negationPrefix(isSet)}to have ${label} set\n${describeWidget(widget)}`,
+    };
+};
+
+const describeReading = (expectation: AttributeExpectation): string =>
+    `${describeAttributeValue(expectation.actual)}${expectation.isReadingRounded ? ROUNDED_READING : ""}`;
+
+const attributeValueResult = (widget: Gtk.Widget, expectation: AttributeExpectation): MatcherResult => ({
+    pass: expectation.isPass,
+    message: () =>
+        `expected widget ${negationPrefix(expectation.isPass)}to have ${expectation.label} ` +
+        `${expectation.comparison} ${describeAttributeValue(expectation.expected)}, but received ` +
+        `${describeReading(expectation)}\n${describeWidget(widget)}`,
+});
+
+const orderResult = (widget: Gtk.Widget, other: Gtk.Widget, position: string, isPass: boolean): MatcherResult => ({
+    pass: isPass,
+    message: () =>
+        `expected widget ${negationPrefix(isPass)}to appear ${position} ${describeWidget(other)} ` +
+        `in the widget tree\n${describeWidget(widget)}`,
+});
+
+const getTreeRoot = (widget: Gtk.Widget): Gtk.Widget => {
+    let root = widget;
+    let parent = root.getParent();
+
+    while (parent) {
+        root = parent;
+        parent = root.getParent();
+    }
+
+    return root;
+};
+
+const isSeparateWidget = (first: Gtk.Widget, second: Gtk.Widget): boolean =>
+    first !== second && !first.isAncestor(second) && !second.isAncestor(first);
+
+const isPrecedingWidget = (root: Gtk.Widget, first: Gtk.Widget, second: Gtk.Widget): boolean => {
+    for (const widget of descendants(root)) {
+        if (widget === first) {
+            return true;
+        }
+
+        if (widget === second) {
+            return false;
+        }
+    }
+
+    return false;
+};
+
+const isAppearingBefore = (first: Gtk.Widget, second: Gtk.Widget): boolean => {
+    const root = getTreeRoot(first);
+
+    return isSeparateWidget(first, second) && root === getTreeRoot(second) && isPrecedingWidget(root, first, second);
+};
+
 const camelCase = (name: string): string =>
     name.replaceAll(/-([a-z])/g, (_match, letter: string) => letter.toUpperCase());
 
@@ -382,6 +680,117 @@ function booleanStateMatcher(
     };
 }
 
+function containmentMatcher<Args extends unknown[]>(
+    matcherName: string,
+    isSingle: boolean,
+    queryAll: QueryAll<Args>,
+): ContainmentMatcher<Args> {
+    const quantity = isSingle ? "exactly one widget" : "any widget";
+
+    return (received: unknown, ...args: Args): MatcherResult => {
+        const widget = asWidget(received, matcherName);
+        const matches = queryAll(widget, ...args);
+        const isPass = isSingle ? matches.length === 1 : matches.length > 0;
+
+        return {
+            pass: isPass,
+            message: () =>
+                `expected widget ${negationPrefix(isPass)}to contain ${quantity} matching ${matcherName}, ` +
+                `but found ${String(matches.length)}\n${describeWidget(widget)}`,
+        };
+    };
+}
+
+function toHaveAccessibleState(
+    received: unknown,
+    state: Gtk.AccessibleState,
+    expected?: boolean | number,
+): MatcherResult {
+    const widget = asWidget(received, "toHaveAccessibleState");
+    const actual = readAccessibleState(widget, state);
+    const label = `accessible state ${Gtk.AccessibleState[state]}`;
+
+    if (expected === undefined) {
+        return attributeSetResult(widget, label, actual);
+    }
+
+    const wanted = typeof expected === "boolean" ? Number(expected) : expected;
+
+    return attributeValueResult(widget, {
+        label,
+        comparison: "equal to",
+        expected: wanted,
+        actual,
+        isPass: actual === wanted,
+        isReadingRounded: false,
+    });
+}
+
+const propertyLabel = (property: Gtk.AccessibleProperty): string =>
+    `accessible property ${Gtk.AccessibleProperty[property]}`;
+
+const propertyExpectation = (
+    widget: Gtk.Widget,
+    property: Gtk.AccessibleProperty,
+    expected: AccessibleAttributeValue,
+    actual: AccessibleAttributeValue | null,
+): AttributeExpectation => {
+    const label = propertyLabel(property);
+
+    if (typeof expected === "number" && isAccessibleNumberProperty(property)) {
+        return {
+            label,
+            comparison: `within ${String(ACCESSIBLE_NUMBER_TOLERANCE)} of`,
+            expected,
+            actual,
+            isPass: isAccessibleNumberMatch(widget, property, expected),
+            isReadingRounded: actual !== null,
+        };
+    }
+
+    return { label, comparison: "equal to", expected, actual, isPass: actual === expected, isReadingRounded: false };
+};
+
+function toHaveAccessibleProperty(
+    received: unknown,
+    property: Gtk.AccessibleProperty,
+    expected?: AccessibleAttributeValue,
+): MatcherResult {
+    const widget = asWidget(received, "toHaveAccessibleProperty");
+    const actual = readAccessibleProperty(widget, property);
+
+    if (expected === undefined) {
+        return attributeSetResult(widget, propertyLabel(property), actual);
+    }
+
+    return attributeValueResult(widget, propertyExpectation(widget, property, expected, actual));
+}
+
+function toBePartiallyPressed(received: unknown): MatcherResult {
+    const widget = asWidget(received, "toBePartiallyPressed");
+    const state = readAccessibleState(widget, Gtk.AccessibleState.PRESSED);
+
+    if (state === null) {
+        throw notApplicable("toBePartiallyPressed", "pressed state", widget);
+    }
+
+    return stateResult(widget, "partially pressed", state === MIXED_TRISTATE);
+}
+
+function toAppearBefore(received: unknown, other: Gtk.Widget): 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 {
+    const widget = asWidget(received, "toAppearAfter");
+    const target = asWidget(other, "toAppearAfter");
+
+    return orderResult(widget, target, "after", isAppearingBefore(target, widget));
+}
+
 function readCheckedState(widget: Gtk.Widget, matcherName: string): CheckedState {
     const state = getWidgetCheckedState(widget);
 
@@ -414,6 +823,9 @@ function toHaveDisplayValue(received: unknown, expected?: TextExpectation): Matc
     return displayValueMatcher(received, expected);
 }
 
+const describeValueExpectation = (expected: number | undefined): string =>
+    expected === undefined ? "set" : `within ${String(ACCESSIBLE_NUMBER_TOLERANCE)} of ${String(expected)}`;
+
 function toHaveValue(received: unknown, expected?: number | string): MatcherResult {
     const widget = asWidget(received, "toHaveValue");
 
@@ -421,19 +833,19 @@ function toHaveValue(received: unknown, expected?: number | string): MatcherResu
         return displayValueMatcher(received, expected);
     }
 
-    const actual = getWidgetValue(widget).now;
+    const actual = getWidgetValueNow(widget);
 
     if (actual === null) {
         throw notApplicable("toHaveValue", "numeric value", widget);
     }
 
-    const isPass = expected === undefined || actual === expected;
+    const isPass = expected === undefined || isWidgetValueMatch(widget, "now", expected);
 
     return {
         pass: isPass,
         message: () =>
-            `expected widget ${negationPrefix(isPass)}to have value ${String(expected)}, ` +
-            `but received ${String(actual)}\n${describeWidget(widget)}`,
+            `expected widget ${negationPrefix(isPass)}to have value ${describeValueExpectation(expected)}, ` +
+            `but received ${String(actual)}${ROUNDED_READING}\n${describeWidget(widget)}`,
     };
 }
 
@@ -465,8 +877,8 @@ function toBeRooted(received: unknown): MatcherResult {
     return stateResult(widget, "rooted in a window", isWidgetRooted(widget));
 }
 
-function toBeEmpty(received: unknown): MatcherResult {
-    const widget = asWidget(received, "toBeEmpty");
+function toBeEmptyWidget(received: unknown): MatcherResult {
+    const widget = asWidget(received, "toBeEmptyWidget");
 
     return stateResult(widget, "empty", widget.getFirstChild() === null && getWidgetLabelText(widget) === null);
 }
@@ -555,8 +967,6 @@ function toHaveObjectProperty(this: MatcherContext, received: unknown, ...args:
         };
     }
 
-    /* eslint-disable-next-line unicorn/no-this-outside-of-class --
-       expect.extend invokes matchers with the matcher state as `this` */
     const isPass = isEqualValue(this, actual, expected);
 
     return {
@@ -591,18 +1001,30 @@ declare module "@vitest/expect" {
         toHaveAccessibleName(expected?: TextExpectation): void;
         toHaveAccessibleDescription(expected?: TextExpectation): void;
         toHaveAccessibleErrorMessage(expected?: TextExpectation): void;
-        toHavePlaceholderText(expected?: TextExpectation): void;
         toHaveSelection(expected?: TextExpectation): void;
+        /* eslint-disable-next-line unicorn/consistent-boolean-name -- expected is the jest-dom matcher argument name */
+        toHaveAccessibleState(state: BooleanAccessibleState, expected?: boolean): void;
+        toHaveAccessibleState(state: TristateAccessibleState, expected?: Gtk.AccessibleTristate): void;
+        toHaveAccessibleState(state: Gtk.AccessibleState.INVALID, expected?: Gtk.AccessibleInvalidState): void;
+        toHaveAccessibleProperty(property: StringAccessibleProperty, expected?: string): void;
+        /* eslint-disable-next-line unicorn/consistent-boolean-name -- expected is the jest-dom matcher argument name */
+        toHaveAccessibleProperty(property: BooleanAccessibleProperty, expected?: boolean): void;
+        toHaveAccessibleProperty(property: NumberAccessibleProperty, expected?: number): void;
+        toHaveAccessibleProperty(
+            property: Gtk.AccessibleProperty.AUTOCOMPLETE,
+            expected?: Gtk.AccessibleAutocomplete,
+        ): void;
+        toHaveAccessibleProperty(property: Gtk.AccessibleProperty.ORIENTATION, expected?: Gtk.Orientation): void;
+        toHaveAccessibleProperty(property: Gtk.AccessibleProperty.SORT, expected?: Gtk.AccessibleSort): void;
         toBeChecked(): void;
         toBePartiallyChecked(): void;
         toBePressed(): void;
-        toBeExpanded(): void;
-        toBeSelected(): void;
+        toBePartiallyPressed(): void;
         toBeDisabled(): void;
         toBeEnabled(): void;
         toBeVisible(): void;
         toBeRooted(): void;
-        toBeEmpty(): void;
+        toBeEmptyWidget(): void;
         toBeInvalid(): void;
         toBeValid(): void;
         toBeRequired(): void;
@@ -610,6 +1032,18 @@ declare module "@vitest/expect" {
         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;
+        toContainAnyByRole(...args: RoleQueryArgs): void;
+        toContainOneByRole(...args: RoleQueryArgs): void;
+        toContainAnyByText(...args: TextQueryArgs): void;
+        toContainOneByText(...args: TextQueryArgs): void;
+        toContainAnyByLabelText(...args: TextQueryArgs): void;
+        toContainOneByLabelText(...args: TextQueryArgs): void;
+        toContainAnyByPlaceholderText(...args: TextQueryArgs): void;
+        toContainOneByPlaceholderText(...args: TextQueryArgs): void;
+        toContainAnyByDisplayValue(...args: TextQueryArgs): void;
+        toContainOneByDisplayValue(...args: TextQueryArgs): void;
         toHaveClass(...args: (ClassExpectation | { exact: boolean })[]): void;
         toHaveObjectProperty(name: string, expected?: unknown): void;
     }
@@ -619,36 +1053,4 @@ declare module "@vitest/expect" {
     /* eslint-enable @typescript-eslint/consistent-type-definitions */
 }
 
-export {
-    toHaveDisplayValue,
-    toHaveTextContent,
-    toHaveAccessibleName,
-    toHaveAccessibleDescription,
-    toHaveAccessibleErrorMessage,
-    toHavePlaceholderText,
-    toHaveSelection,
-    toBeChecked,
-    toBePartiallyChecked,
-    toBePressed,
-    toBeExpanded,
-    toBeSelected,
-    toBeDisabled,
-    toBeEnabled,
-    toBeVisible,
-    toBeRooted,
-    toBeEmpty,
-    toBeInvalid,
-    toBeValid,
-    toBeRequired,
-    toHaveFocus,
-    toHaveValue,
-    toHaveRole,
-    toContainElement,
-    toHaveClass,
-    toHaveObjectProperty,
-    matchers,
-    registerMatchers,
-    type ClassExpectation,
-    type TextContentOptions,
-    type TextExpectation,
-};
+export { matchers, registerMatchers, type ClassExpectation, type TextContentOptions, type TextExpectation };