@itmetsam/samurai-framework 0.21.3 → 0.21.5

package/dist/assert/locator-assertions.js

@@ -1,93 +1,44 @@
-import { resolveTimeout } from "../config/timeouts.js";
-import { waitUntil, WaitTimeoutError } from "../wait/wait-until.js";
-import { AssertionError } from "./assertion-error.js";
-import { track } from "./pending-assertions.js";
-import { bindOutput } from "../wait/output-sink.js";
-import { captured, matchesText, normalizedCheck, textCheck, } from "./text-match.js";
-/**
- * Re-reads the element until `check` passes or the timeout expires, and resolves with the read that passed. A
- * timeout fails as an `AssertionError` with the last read, or as "could not read" when no read completed.
- */
-export async function readEventually({ name, locator, expected, read, check, timeout: perCall, mustExist = false, call, }) {
-    const timeout = await resolveTimeout(perCall);
-    try {
-        return await waitUntil(read, (actual) => (mustExist && actual === null ? false : check(actual)), { timeout });
-    }
-    catch (err) {
-        if (!(err instanceof WaitTimeoutError))
-            throw err;
-        // Reads never resolve to undefined, so an undefined `last` means no read completed
-        if (err.last === undefined || (mustExist && err.last === null)) {
-            throw new Error(`${call ?? `expect(locator).${name}`}: could not read ${locator.selector} within ${timeout}ms`);
-        }
-        throw new AssertionError({
-            matcher: name,
-            expected,
-            actual: err.last,
-            locator: locator.selector,
-            call,
-        });
-    }
-}
-export class LocatorAssertions {
-    constructor(locator, negated = false) {
-        this.locator = locator;
-        this.negated = negated;
-    }
+import { MoreLocatorAssertions } from "./more-locator-assertions.js";
+import { readCheckedState } from "./element-probes.js";
+import { matchesText, normalizedCheck } from "./text-match.js";
+export { readEventually } from "./locator-assertion-base.js";
+export class LocatorAssertions extends MoreLocatorAssertions {
     /** Inverts the next matcher: it retries until the condition is false */
     get not() {
         return new LocatorAssertions(this.locator, !this.negated);
     }
-    /**
-     * Re-reads the element until `check` passes or the timeout expires. With `mustExist`, a read of `null`
-     * (no element) never passes, with or without `.not`, and fails as "could not read"
-     */
-    assertEventually(matcher, expected, read, check, options, mustExist = false, save) {
-        const name = this.negated ? `not.${matcher}` : matcher;
-        return track(`expect(locator).${name}()`, readEventually({
-            name,
-            locator: this.locator,
-            expected,
-            read,
-            check: (actual) => check(actual) !== this.negated,
-            timeout: options?.timeout,
-            mustExist,
-        }).then((actual) => save?.(actual)));
+    /** The element exists, has a box and isn't hidden by CSS; `visible: false` expects the opposite, as `toBeHidden` */
+    toBeVisible(options) {
+        const want = options?.visible ?? true;
+        return this.assertEventually("toBeVisible", want, () => this.locator.isVisible(), (visible) => visible === want, options);
     }
     /**
-     * A text check that can keep what it read: with `options.output` the read that passed goes to that output, as
-     * `expected` captures it. The sink is taken now, when the call starts.
+     * Trimmed text content equals `expected` (a string, compared with whitespace collapsed on both sides) or matches it (RegExp).
+     * An array expects one entry per matched element, in order, and as many entries as elements
      */
-    assertText(matcher, expected, read, mode, options) {
-        let save;
-        if (options?.output !== undefined) {
-            const call = `expect(locator).${this.negated ? "not." : ""}${matcher}`;
-            if (this.negated)
-                throw new Error(`${call}: output can't be saved from a negated check`);
-            const keep = bindOutput(call, options.output);
-            save = (actual) => keep(captured(expected, actual));
-        }
-        return this.assertEventually(matcher, expected, read, textCheck(expected, mode), options, false, save);
-    }
-    /** For matchers that need an element: `read` answers null when there is none, which never passes */
-    assertExisting(matcher, expected, read, check, options) {
-        return this.assertEventually(matcher, expected, read, (actual) => actual !== null && check(actual), options, true);
-    }
-    toBeVisible(options) {
-        return this.assertEventually("toBeVisible", true, () => this.locator.isVisible(), (visible) => visible, options);
-    }
-    /** Trimmed text content equals `expected` (string) or matches it (RegExp) */
     toHaveText(expected, options) {
-        return this.assertText("toHaveText", expected, () => this.locator.textContent(), "exact", options);
+        if (Array.isArray(expected))
+            return this.assertTexts("toHaveText", expected, "exact", options);
+        return this.assertText("toHaveText", expected, () => this.locator.textContent(), "exact", options, true);
     }
-    /** Text content contains `expected` (string) or matches it (RegExp) */
+    /**
+     * Text content contains `expected` (a string, compared with whitespace collapsed on both sides) or matches it (RegExp).
+     * An array expects its entries, in order, in some of the matched elements (one entry per element, others may sit between)
+     */
     toContainText(expected, options) {
-        return this.assertText("toContainText", expected, () => this.locator.textContent(), "contains", options);
+        if (Array.isArray(expected))
+            return this.assertTexts("toContainText", expected, "contains", options);
+        return this.assertText("toContainText", expected, () => this.locator.textContent(), "contains", options, true);
     }
     toHaveValue(expected, options) {
         return this.assertText("toHaveValue", expected, () => this.locator.inputValue(), "exact", options);
     }
-    toHaveAttribute(name, expected, options) {
+    toHaveAttribute(name, expectedOrOptions, options) {
+        if (typeof expectedOrOptions !== "string" &&
+            !(expectedOrOptions instanceof RegExp)) {
+            return this.assertEventually("toHaveAttribute", `attribute ${name} present`, () => this.locator.getAttribute(name), (value) => value !== null, expectedOrOptions);
+        }
+        const expected = expectedOrOptions;
         return this.assertText("toHaveAttribute", expected, () => this.locator.getAttribute(name), "exact", options);
     }
     toHaveCount(expected, options) {
@@ -99,11 +50,17 @@ export class LocatorAssertions {
     }
     /** The element exists and is neither `:disabled` nor `aria-disabled="true"`; a missing element never passes, not even with `.not` */
     toBeEnabled(options) {
-        return this.assertExisting("toBeEnabled", true, () => this.locator.enabledState(), (enabled) => enabled, options);
+        const want = options?.enabled ?? true;
+        return this.assertExisting("toBeEnabled", want, () => this.locator.enabledState(), (enabled) => enabled === want, options);
     }
     /** A checked checkbox or radio input, or an element with `aria-checked="true"`; a missing element never passes, not even with `.not` */
     toBeChecked(options) {
-        return this.assertExisting("toBeChecked", true, () => this.locator.isChecked(), (checked) => checked, options);
+        const want = options?.indeterminate ? "mixed" : (options?.checked ?? true);
+        // Only "mixed" needs the three-state read; true and false use the plain one
+        if (want === "mixed") {
+            return this.assertExisting("toBeChecked", want, () => readCheckedState(this.locator), (state) => state === "mixed", options);
+        }
+        return this.assertExisting("toBeChecked", want, () => this.locator.isChecked(), (checked) => checked === want, options);
     }
     /** The class attribute equals `expected` (string, whitespace collapsed and trimmed on both sides) or matches it (RegExp, tested on the attribute as written) */
     toHaveClass(expected, options) {

package/dist/assert/more-locator-assertions.d.ts

@@ -0,0 +1,30 @@
+import { LocatorAssertionBase, type LocatorAssertionOptions, type TextAssertionOptions } from "./locator-assertion-base.js";
+export interface InViewportOptions extends LocatorAssertionOptions {
+    /** The least share (0 to 1) of the element that must be inside the viewport. Default: any part */
+    ratio?: number;
+}
+/** The locator matchers that read the element with a small script of their own; `LocatorAssertions` adds the rest */
+export declare class MoreLocatorAssertions extends LocatorAssertionBase {
+    /** An array of texts, one entry per matched element; `read` answers the texts of every match */
+    protected assertTexts(matcher: string, expected: Array<string | RegExp>, mode: "exact" | "contains", options?: TextAssertionOptions): Promise<void>;
+    /** The element has the focus; a missing element never passes, not even with `.not` */
+    toBeFocused(options?: LocatorAssertionOptions): Promise<void>;
+    /** The element's JS property `property` deep-equals `expected`; a missing element never passes, not even with `.not` */
+    toHaveJSProperty(property: string, expected: unknown, options?: LocatorAssertionOptions): Promise<void>;
+    /** Part of the element (or at least `ratio` of it) is inside the viewport; a missing element never passes, not even with `.not` */
+    toBeInViewport(options?: InViewportOptions): Promise<void>;
+    /** At least one element matches (`attached: false`, or `.not`, means none does) */
+    toBeAttached(options?: LocatorAssertionOptions & {
+        attached?: boolean;
+    }): Promise<void>;
+    /** The element is disabled (the opposite of `toBeEnabled`); a missing element never passes, not even with `.not` */
+    toBeDisabled(options?: LocatorAssertionOptions): Promise<void>;
+    /** The element accepts typing (`editable: false` expects the opposite); a missing element never passes, not even with `.not` */
+    toBeEditable(options?: LocatorAssertionOptions & {
+        editable?: boolean;
+    }): Promise<void>;
+    /** The `id` equals `expected` (string) or matches it (RegExp); a missing element never passes, not even with `.not` */
+    toHaveId(expected: string | RegExp, options?: LocatorAssertionOptions): Promise<void>;
+    /** An input or textarea with an empty value, or any other element without element children and with no text besides whitespace; a missing element never passes, not even with `.not` */
+    toBeEmpty(options?: LocatorAssertionOptions): Promise<void>;
+}

package/dist/assert/more-locator-assertions.js

@@ -0,0 +1,86 @@
+import { isDeepStrictEqual } from "node:util";
+import { track } from "./pending-assertions.js";
+import { LocatorAssertionBase, readEventually, } from "./locator-assertion-base.js";
+import { readEmpty, readFocused, readId, readJSProperty, readViewportRatio, } from "./element-probes.js";
+import { matchesText } from "./text-match.js";
+/** Floating point slack when a ratio is compared */
+const RATIO_EPSILON = 1e-6;
+const normalize = (value) => value.replace(/\s+/g, " ").trim();
+/** One text expectation against one element's text: a string after normalising both, a RegExp as written (trimmed text) */
+function textMatches(actual, expected, mode) {
+    if (expected instanceof RegExp)
+        return matchesText(actual, expected, mode);
+    return matchesText(normalize(actual), normalize(expected), mode);
+}
+/** Whether `texts` (one per element) satisfy `expected`: all in order for "exact", in order but not necessarily adjacent for "contains" */
+function arrayTextMatches(texts, expected, mode) {
+    if (mode === "exact") {
+        return (texts.length === expected.length &&
+            expected.every((item, i) => textMatches(texts[i], item, "exact")));
+    }
+    let next = 0;
+    for (const text of texts) {
+        if (next < expected.length &&
+            textMatches(text, expected[next], "contains"))
+            next++;
+    }
+    return next === expected.length;
+}
+/** The locator matchers that read the element with a small script of their own; `LocatorAssertions` adds the rest */
+export class MoreLocatorAssertions extends LocatorAssertionBase {
+    /** An array of texts, one entry per matched element; `read` answers the texts of every match */
+    assertTexts(matcher, expected, mode, options) {
+        if (options?.output !== undefined) {
+            const call = `expect(locator).${this.negated ? "not." : ""}${matcher}`;
+            throw new Error(`${call}: output can't be saved from an array of texts`);
+        }
+        return this.assertEventually(matcher, expected, async () => (await this.locator.allTextContents()).map((t) => t.trim()), (texts) => arrayTextMatches(texts, expected, mode), options);
+    }
+    /** The element has the focus; a missing element never passes, not even with `.not` */
+    toBeFocused(options) {
+        return this.assertExisting("toBeFocused", true, () => readFocused(this.locator), (focused) => focused, options);
+    }
+    /** The element's JS property `property` deep-equals `expected`; a missing element never passes, not even with `.not` */
+    toHaveJSProperty(property, expected, options) {
+        const name = this.matcherName("toHaveJSProperty");
+        return track(`expect(locator).${name}()`, readEventually({
+            name,
+            locator: this.locator,
+            expected,
+            read: () => readJSProperty(this.locator, property),
+            check: (read) => isDeepStrictEqual(read?.value, expected) !== this.negated,
+            timeout: options?.timeout,
+            mustExist: true,
+            display: (read) => read?.value,
+        }).then(() => undefined));
+    }
+    /** Part of the element (or at least `ratio` of it) is inside the viewport; a missing element never passes, not even with `.not` */
+    toBeInViewport(options) {
+        const ratio = options?.ratio ?? 0;
+        return this.assertExisting("toBeInViewport", ratio > 0 ? `ratio >= ${ratio}` : "ratio > 0", () => readViewportRatio(this.locator), (actual) => (ratio > 0 ? actual >= ratio - RATIO_EPSILON : actual > 0), options);
+    }
+    /** At least one element matches (`attached: false`, or `.not`, means none does) */
+    toBeAttached(options) {
+        const want = options?.attached ?? true;
+        return this.assertEventually("toBeAttached", want, async () => (await this.locator.count()) > 0, (attached) => attached === want, options);
+    }
+    /** The element is disabled (the opposite of `toBeEnabled`); a missing element never passes, not even with `.not` */
+    toBeDisabled(options) {
+        return this.assertExisting("toBeDisabled", true, () => this.locator.enabledState(), (enabled) => !enabled, options);
+    }
+    /** The element accepts typing (`editable: false` expects the opposite); a missing element never passes, not even with `.not` */
+    toBeEditable(options) {
+        const want = options?.editable ?? true;
+        return this.assertExisting("toBeEditable", want, async () => (await this.locator.count()) === 0
+            ? null
+            : await this.locator.isEditable(), (editable) => editable === want, options);
+    }
+    /** The `id` equals `expected` (string) or matches it (RegExp); a missing element never passes, not even with `.not` */
+    toHaveId(expected, options) {
+        return this.assertExisting("toHaveId", expected, () => readId(this.locator), (id) => matchesText(id, expected, "exact"), options);
+    }
+    /** An input or textarea with an empty value, or any other element without element children and with no text besides whitespace; a missing element never passes, not even with `.not` */
+    toBeEmpty(options) {
+        return this.assertExisting("toBeEmpty", true, () => readEmpty(this.locator), (empty) => empty, options);
+    }
+}

package/dist/assert/retry-assertions.d.ts

@@ -0,0 +1,28 @@
+import type { ValueAssertions } from "./value-assertions.js";
+export interface RetryOptions {
+    /** Time (ms) to keep trying; 0 tries once */
+    timeout?: number;
+    /** Pauses (ms) between tries; the last one repeats. Default: 100, 250, 500, then 1000 */
+    intervals?: number[];
+}
+export interface PollOptions extends RetryOptions {
+    /** Replaces the first line of a failure (`expect.poll().<matcher>`) */
+    message?: string;
+}
+/** The value matchers of `expect(value)`, each returning a promise that settles once the polled value passes (or the time is up) */
+export type PollAssertions<T> = {
+    [K in keyof Omit<ValueAssertions<T>, "not">]: ValueAssertions<T>[K] extends (...args: infer A) => unknown ? (...args: A) => Promise<void> : never;
+} & {
+    readonly not: PollAssertions<T>;
+};
+/**
+ * `expect(block).toPass()`: runs `block` (sync or async) until it stops throwing. The default timeout is 0, one try.
+ * With `negated`, until it throws. A failure rethrows the last error as it was.
+ */
+export declare function toPass(block: () => unknown, options: RetryOptions | undefined, negated: boolean): Promise<void>;
+/**
+ * `expect.poll(fn)`: the value matchers of `expect(value)`, each calling `fn` (sync or async) again and again until
+ * the matcher passes or the time is up. The timeout defaults to the expect timeout; 0 tries once.
+ * A function that throws counts as a failed try.
+ */
+export declare function poll<T>(fn: () => T | Promise<T>, options?: PollOptions, negated?: boolean): PollAssertions<Awaited<T>>;

package/dist/assert/retry-assertions.js

@@ -0,0 +1,113 @@
+import { resolveTimeout } from "../config/timeouts.js";
+import { waitUntil, WaitTimeoutError } from "../wait/wait-until.js";
+import { AssertionError } from "./assertion-error.js";
+import { track } from "./pending-assertions.js";
+/** Pauses (ms) between tries; the last one repeats */
+const DEFAULT_INTERVALS = [100, 250, 500, 1000];
+function asError(thrown) {
+    return thrown instanceof Error ? thrown : new Error(String(thrown));
+}
+/**
+ * `expect(block).toPass()`: runs `block` (sync or async) until it stops throwing. The default timeout is 0, one try.
+ * With `negated`, until it throws. A failure rethrows the last error as it was.
+ */
+export function toPass(block, options, negated) {
+    const timeout = options?.timeout ?? 0;
+    const name = negated ? "not.toPass" : "toPass";
+    const run = async () => {
+        try {
+            await waitUntil(async () => {
+                try {
+                    await block();
+                    return {};
+                }
+                catch (error) {
+                    return { error: error ?? new Error("undefined") };
+                }
+            }, (attempt) => (attempt.error === undefined) !== negated, { timeout, intervals: options?.intervals ?? DEFAULT_INTERVALS });
+        }
+        catch (err) {
+            if (!(err instanceof WaitTimeoutError))
+                throw err;
+            const last = err.last;
+            if (last === undefined) {
+                throw new Error(`expect(value).${name}: timed out after ${timeout}ms`);
+            }
+            if (negated) {
+                throw new AssertionError({
+                    matcher: name,
+                    expected: "the block to throw",
+                    actual: "it did not throw",
+                });
+            }
+            throw asError(last.error);
+        }
+    };
+    return track(`expect(value).${negated ? "not." : ""}toPass()`, run());
+}
+/** Runs one matcher of `ValueAssertions` against `value` once; an `AssertionError` is a failed try, anything else (a misused matcher) propagates */
+async function tryMatcher(value, negated, matcher, args) {
+    const { ValueAssertions } = await import("./value-assertions.js");
+    try {
+        const assertions = new ValueAssertions(value, negated);
+        assertions[matcher](...args);
+        return {};
+    }
+    catch (error) {
+        if (error instanceof AssertionError)
+            return { error };
+        throw error;
+    }
+}
+async function pollMatcher(fn, options, negated, matcher, args) {
+    const timeout = await resolveTimeout(options?.timeout);
+    const name = negated ? `not.${matcher}` : matcher;
+    const call = options?.message ?? `expect.poll().${name}`;
+    try {
+        await waitUntil(async () => {
+            let value;
+            try {
+                value = await fn();
+            }
+            catch (error) {
+                return { error };
+            }
+            return tryMatcher(value, negated, matcher, args);
+        }, (attempt) => attempt.error === undefined, { timeout, intervals: options?.intervals ?? DEFAULT_INTERVALS });
+    }
+    catch (err) {
+        if (!(err instanceof WaitTimeoutError))
+            throw err;
+        const last = err.last;
+        if (last === undefined) {
+            throw new Error(`expect.poll().${name}: timed out after ${timeout}ms`);
+        }
+        if (last.error instanceof AssertionError) {
+            throw new AssertionError({
+                matcher: last.error.matcher,
+                expected: last.error.expected,
+                actual: last.error.actual,
+                call,
+            });
+        }
+        throw new Error(`expect.poll().${name}: the function threw: ${asError(last.error).message}`);
+    }
+}
+/**
+ * `expect.poll(fn)`: the value matchers of `expect(value)`, each calling `fn` (sync or async) again and again until
+ * the matcher passes or the time is up. The timeout defaults to the expect timeout; 0 tries once.
+ * A function that throws counts as a failed try.
+ */
+export function poll(fn, options, negated = false) {
+    const target = {};
+    return new Proxy(target, {
+        get(_target, property) {
+            if (property === "not")
+                return poll(fn, options, !negated);
+            // Only matchers: anything else (`then`, which would make the object awaitable) is not there
+            if (typeof property !== "string" || !/^to[A-Z]/.test(property))
+                return undefined;
+            return (...args) => track(`expect.poll().${negated ? "not." : ""}${property}()`, pollMatcher(fn, options, negated, property, args));
+        },
+    });
+}

package/dist/assert/text-match.d.ts

@@ -10,3 +10,5 @@ export declare function captured(matcher: string | RegExp, actual: string): stri
 export declare function textCheck(expected: string | RegExp, mode: "exact" | "contains"): (actual: string | null) => boolean;
 /** A check for a text compared after normalising whitespace: a string equals it with whitespace collapsed and both sides trimmed, a RegExp tests it as written */
 export declare function normalizedCheck(expected: string | RegExp): (actual: string) => boolean;
+/** Like `textCheck`, but a string is compared with whitespace runs collapsed and both sides trimmed; a RegExp tests the text as written */
+export declare function normalizedTextCheck(expected: string | RegExp, mode: "exact" | "contains"): (actual: string | null) => boolean;

package/dist/assert/text-match.js

@@ -28,3 +28,11 @@ export function normalizedCheck(expected) {
     const normalize = (value) => value.replace(/\s+/g, " ").trim();
     return (actual) => normalize(actual) === normalize(expected);
 }
+/** Like `textCheck`, but a string is compared with whitespace runs collapsed and both sides trimmed; a RegExp tests the text as written */
+export function normalizedTextCheck(expected, mode) {
+    if (expected instanceof RegExp)
+        return textCheck(expected, mode);
+    const normalize = (value) => value.replace(/\s+/g, " ").trim();
+    const wanted = normalize(expected);
+    return (actual) => actual !== null && matchesText(normalize(actual), wanted, mode);
+}

package/dist/assert/value-assertions.d.ts

@@ -1,3 +1,5 @@
+import { type RetryOptions } from "./retry-assertions.js";
+import { type ThrowExpectation } from "./value-matchers.js";
 export declare class ValueAssertions<T> {
     private readonly actual;
     private readonly negated;
@@ -8,8 +10,29 @@ export declare class ValueAssertions<T> {
     private compare;
     /** Strict identity (`Object.is`) */
     toBe(expected: unknown): void;
-    /** Deep structural equality */
+    /**
+     * Deep structural equality, strict: a property that is `undefined` differs from a missing one (Jest's `toEqual`
+     * ignores it). `expected` may hold asymmetric matchers (`expect.any(Number)`, ...)
+     */
     toEqual(expected: unknown): void;
+    /** The object has the properties of `expected` (nested objects likewise; arrays need the same length); `expected` may hold asymmetric matchers */
+    toMatchObject(expected: object): void;
+    /** The array has an item that `toEqual` `item` */
+    toContainEqual(item: unknown): void;
+    toBeNull(): void;
+    toBeUndefined(): void;
+    /** Anything but `undefined` (`null` is defined) */
+    toBeDefined(): void;
+    /** A string, array or array-like with this `length` */
+    toHaveLength(expected: number): void;
+    /** The number is within half a unit of the `digits`-th decimal (default 2) of `expected` */
+    toBeCloseTo(expected: number, digits?: number): void;
+    toBeInstanceOf(expected: abstract new (...args: any[]) => unknown): void;
+    /**
+     * The function throws, optionally an error whose message contains a string or matches a RegExp, that is an
+     * instance of a class, or whose message equals an error's. Synchronous functions only
+     */
+    toThrow(expected?: ThrowExpectation): void;
     toBeTruthy(): void;
     toBeFalsy(): void;
     /** Array includes `item`, or string contains substring `item` */
@@ -20,4 +43,9 @@ export declare class ValueAssertions<T> {
     toBeGreaterThanOrEqual(expected: number | bigint): void;
     toBeLessThan(expected: number | bigint): void;
     toBeLessThanOrEqual(expected: number | bigint): void;
+    /**
+     * Runs the function (sync or async) until it stops throwing, then resolves; with `.not`, until it throws.
+     * The default timeout is 0: one try. A failure rethrows the last error
+     */
+    toPass(options?: RetryOptions): Promise<void>;
 }

package/dist/assert/value-assertions.js

@@ -1,6 +1,8 @@
-import { isDeepStrictEqual } from "node:util";
 import { AssertionError } from "./assertion-error.js";
+import { equalsWith, subsetMatches } from "./asymmetric.js";
+import { toPass } from "./retry-assertions.js";
 import { matchesText } from "./text-match.js";
+import { callAndCatch, describeOutcome, isCloseTo, lengthOf, thrownMatches, } from "./value-matchers.js";
 function isNumeric(value) {
     return typeof value === "number" || typeof value === "bigint";
 }
@@ -13,13 +15,13 @@ export class ValueAssertions {
     get not() {
         return new ValueAssertions(this.actual, !this.negated);
     }
-    assert(pass, matcher, expected) {
+    assert(pass, matcher, expected, actual = this.actual) {
         if (pass !== this.negated)
             return;
         throw new AssertionError({
             matcher: this.negated ? `not.${matcher}` : matcher,
             expected,
-            actual: this.actual,
+            actual,
         });
     }
     compare(matcher, expected, check) {
@@ -33,9 +35,75 @@ export class ValueAssertions {
     toBe(expected) {
         this.assert(Object.is(this.actual, expected), "toBe", expected);
     }
-    /** Deep structural equality */
+    /**
+     * Deep structural equality, strict: a property that is `undefined` differs from a missing one (Jest's `toEqual`
+     * ignores it). `expected` may hold asymmetric matchers (`expect.any(Number)`, ...)
+     */
     toEqual(expected) {
-        this.assert(isDeepStrictEqual(this.actual, expected), "toEqual", expected);
+        this.assert(equalsWith(this.actual, expected), "toEqual", expected);
+    }
+    /** The object has the properties of `expected` (nested objects likewise; arrays need the same length); `expected` may hold asymmetric matchers */
+    toMatchObject(expected) {
+        const actual = this.actual;
+        if (typeof actual !== "object" || actual === null) {
+            throw new TypeError(`toMatchObject expects an object, received ${actual === null ? "null" : typeof actual}`);
+        }
+        if (typeof expected !== "object" || expected === null) {
+            throw new TypeError(`toMatchObject expects an object to match, received ${typeof expected}`);
+        }
+        this.assert(subsetMatches(actual, expected), "toMatchObject", expected);
+    }
+    /** The array has an item that `toEqual` `item` */
+    toContainEqual(item) {
+        const actual = this.actual;
+        if (!Array.isArray(actual)) {
+            throw new TypeError(`toContainEqual expects an array, received ${typeof actual}`);
+        }
+        this.assert(actual.some((entry) => equalsWith(entry, item)), "toContainEqual", item);
+    }
+    toBeNull() {
+        this.assert(this.actual === null, "toBeNull", null);
+    }
+    toBeUndefined() {
+        this.assert(this.actual === undefined, "toBeUndefined", undefined);
+    }
+    /** Anything but `undefined` (`null` is defined) */
+    toBeDefined() {
+        this.assert(this.actual !== undefined, "toBeDefined", "defined");
+    }
+    /** A string, array or array-like with this `length` */
+    toHaveLength(expected) {
+        const length = lengthOf(this.actual);
+        if (length === undefined) {
+            throw new TypeError(`toHaveLength expects a value with a length, received ${this.actual === null ? "null" : typeof this.actual}`);
+        }
+        this.assert(length === expected, "toHaveLength", expected, length);
+    }
+    /** The number is within half a unit of the `digits`-th decimal (default 2) of `expected` */
+    toBeCloseTo(expected, digits = 2) {
+        const actual = this.actual;
+        if (typeof actual !== "number" || typeof expected !== "number") {
+            throw new TypeError(`toBeCloseTo expects numbers, received ${typeof actual} and ${typeof expected}`);
+        }
+        this.assert(isCloseTo(actual, expected, digits), "toBeCloseTo", expected);
+    }
+    toBeInstanceOf(expected) {
+        if (typeof expected !== "function") {
+            throw new TypeError(`toBeInstanceOf expects a class, received ${typeof expected}`);
+        }
+        this.assert(this.actual instanceof expected, "toBeInstanceOf", expected);
+    }
+    /**
+     * The function throws, optionally an error whose message contains a string or matches a RegExp, that is an
+     * instance of a class, or whose message equals an error's. Synchronous functions only
+     */
+    toThrow(expected) {
+        const fn = this.actual;
+        if (typeof fn !== "function") {
+            throw new TypeError(`toThrow expects a function, received ${typeof fn}`);
+        }
+        const outcome = callAndCatch(fn);
+        this.assert(thrownMatches(outcome, expected), "toThrow", expected ?? "an error", describeOutcome(outcome));
     }
     toBeTruthy() {
         this.assert(Boolean(this.actual), "toBeTruthy", "truthy");
@@ -79,4 +147,15 @@ export class ValueAssertions {
     toBeLessThanOrEqual(expected) {
         this.compare("toBeLessThanOrEqual", expected, (a, b) => a <= b);
     }
+    /**
+     * Runs the function (sync or async) until it stops throwing, then resolves; with `.not`, until it throws.
+     * The default timeout is 0: one try. A failure rethrows the last error
+     */
+    toPass(options) {
+        const block = this.actual;
+        if (typeof block !== "function") {
+            throw new TypeError(`toPass expects a function, received ${typeof block}`);
+        }
+        return toPass(block, options, this.negated);
+    }
 }

package/dist/assert/value-matchers.d.ts

@@ -0,0 +1,19 @@
+/** What `toThrow` accepts: a message part, a RegExp for the message, an error class, or an error whose message must be equal */
+export type ThrowExpectation = string | RegExp | (new (...args: any[]) => unknown) | Error;
+/** The result of calling a function under `toThrow` */
+export type Outcome = {
+    threw: false;
+} | {
+    threw: true;
+    error: unknown;
+};
+/** Calls `fn` and says whether it threw */
+export declare function callAndCatch(fn: () => unknown): Outcome;
+/** Whether what was thrown fits `expected`; with no expectation, throwing at all fits */
+export declare function thrownMatches(outcome: Outcome, expected: ThrowExpectation | undefined): boolean;
+/** What a `toThrow` failure shows as the received value */
+export declare function describeOutcome(outcome: Outcome): string;
+/** Jest's rule: the difference is under half a unit of the last digit asked for */
+export declare function isCloseTo(actual: number, expected: number, digits: number): boolean;
+/** The `length` of a string, array or array-like; undefined for anything else */
+export declare function lengthOf(value: unknown): number | undefined;