@rehearsal-labs/retest 0.1.0 → 0.2.0

package/dist/assertions/expect.js

@@ -6,9 +6,11 @@ import { isThenable } from "../api/operation.js";
 import { Secret } from "../api/secret.js";
 import { describeLocator, textPatternOf } from "../protocol/locator.js";
 import { maxTimeout } from "../protocol/timeouts.js";
+import { pollLayout } from "./poll-layout.js";
 import { pollLocator } from "./poll-locator.js";
 import { pollPage } from "./poll-page.js";
 import { pollValue } from "./poll-value.js";
+import { pollScreenshot, readScreenshotCall } from "./screenshot.js";
 import { assertValue } from "./value.js";
 import { containCheck, equalCheck, matchCheck, sameCheck } from "./value-checks.js";
 // The type checker and JavaScript callers get the same sentence for a matcher used on the wrong kind of thing.
@@ -29,6 +31,14 @@ const misplaced = {
     toHaveValue: 'toHaveValue is for locators. Use toBe on a value.',
     toHaveURL: 'toHaveURL is for a page. Use toBe on a value.',
     toHaveTitle: 'toHaveTitle is for a page. Use toBe on a value.',
+    toOverlap: 'toOverlap is for locators. Use toBe on a value.',
+    toOverflowViewport: 'toOverflowViewport is for locators. Use toBe on a value.',
+    toHaveClippedText: 'toHaveClippedText is for locators. Use toBe on a value.',
+    toScrollHorizontally: 'toScrollHorizontally is for a page. Use toBe on a value.',
+    layout: 'Layout matchers measure a web page. A native app has no page layout to measure.',
+    toHaveScreenshot: 'toHaveScreenshot is for locators and pages. Use toEqual on a value.',
+    screenshotNot: 'toHaveScreenshot has no .not. Save a baseline of the picture you expect instead.',
+    screenshotNative: 'toHaveScreenshot compares web pages. Retest compares no picture of a native app yet.',
     not: '.not is for locator and page matchers. Write the value matcher that says what you expect.',
     twice: '.not is written once.',
 };
@@ -121,6 +131,40 @@ class LocatorExpectation {
             return this.#assert({ matcher: 'toHaveValue', pattern: textPatternOf(value) }, options);
         throw misuse(`toHaveValue() takes the expected value as a string or a RegExp, received ${formatValue(value)}.`, this.#scope.run);
     }
+    toOverlap(other, options) {
+        const { run } = this.#scope;
+        const found = locatorTarget(other);
+        if (found === undefined)
+            throw misuse(`toOverlap() takes the other element's locator, such as page.getByTestId('help'), received ${formatValue(other)}.`, run);
+        if (found.run !== run)
+            throw misuse('The other locator belongs to another test. Find it again with its page.', run);
+        if (found.app !== this.#target.app) {
+            const own = describeLocator(this.#target.recipe);
+            throw misuse(`toOverlap() compares two elements of one page: ${own} is on ${this.#target.app} and ${describeLocator(found.recipe)} on ${found.app}.`, run);
+        }
+        return this.#measure({ matcher: 'toOverlap', other: found.recipe }, options);
+    }
+    toOverflowViewport(options) {
+        return this.#measure({ matcher: 'toOverflowViewport' }, options);
+    }
+    toHaveClippedText(options) {
+        return this.#measure({ matcher: 'toHaveClippedText' }, options);
+    }
+    toHaveScreenshot(name, options) {
+        const { run, stepId } = this.#scope;
+        const { app, recipe } = this.#target;
+        const { soft, negated } = this.#sense;
+        const location = run.location();
+        if (negated)
+            throw misuse(misplaced.screenshotNot, run);
+        if (this.#target.run !== run)
+            throw misuse('This locator belongs to another test. Find it again with its page.', run);
+        const call = readScreenshotCall(name, options);
+        if (typeof call === 'string')
+            throw misuse(call, run);
+        const label = `${soft ? 'expect.soft' : 'expect'}(${describeLocator(recipe)}).toHaveScreenshot()`;
+        return run.assertion(label, location, () => pollScreenshot({ run, stepId, app, recipe, record: call.record, location, soft, timeoutMs: call.timeoutMs }), app);
+    }
     toBe() {
         throw misuse(misplaced.toBe, this.#scope.run);
     }
@@ -145,6 +189,18 @@ class LocatorExpectation {
         const label = `${soft ? 'expect.soft' : 'expect'}(${describeLocator(recipe)})${negated ? '.not' : ''}.${matched.matcher}()`;
         return run.assertion(label, location, () => pollLocator({ run, stepId, app, recipe, record, location, soft, timeoutMs }), app);
     }
+    #measure(matched, options) {
+        const { run, stepId } = this.#scope;
+        const { app, recipe } = this.#target;
+        const { soft, negated } = this.#sense;
+        const location = run.location();
+        if (this.#target.run !== run)
+            throw misuse('This locator belongs to another test. Find it again with its page.', run);
+        const timeoutMs = readAssertionOptions(matched.matcher, options, this.#scope);
+        const record = negated ? { ...matched, not: true } : matched;
+        const label = `${soft ? 'expect.soft' : 'expect'}(${describeLocator(recipe)})${negated ? '.not' : ''}.${matched.matcher}()`;
+        return run.assertion(label, location, () => pollLayout({ run, stepId, app, recipe, record, location, soft, timeoutMs }), app);
+    }
 }
 class PageExpectation {
     #scope;
@@ -175,6 +231,33 @@ class PageExpectation {
             return this.#assert({ matcher: 'toHaveTitle', pattern: textPatternOf(title) }, options);
         throw misuse(`toHaveTitle() takes the title as a string or a RegExp, received ${formatValue(title)}.`, this.#scope.run);
     }
+    toScrollHorizontally(options) {
+        const { run, stepId } = this.#scope;
+        const { app } = this.#target;
+        const { soft, negated } = this.#sense;
+        const location = run.location();
+        if (this.#target.run !== run)
+            throw misuse('This page belongs to another test. Use the page this test was given.', run);
+        const timeoutMs = readAssertionOptions('toScrollHorizontally', options, this.#scope);
+        const record = negated ? { matcher: 'toScrollHorizontally', not: true } : { matcher: 'toScrollHorizontally' };
+        const label = `${soft ? 'expect.soft' : 'expect'}(page)${negated ? '.not' : ''}.toScrollHorizontally()`;
+        return run.assertion(label, location, () => pollLayout({ run, stepId, app, recipe: undefined, record, location, soft, timeoutMs }), app);
+    }
+    toHaveScreenshot(name, options) {
+        const { run, stepId } = this.#scope;
+        const { app } = this.#target;
+        const { soft, negated } = this.#sense;
+        const location = run.location();
+        if (negated)
+            throw misuse(misplaced.screenshotNot, run);
+        if (this.#target.run !== run)
+            throw misuse('This page belongs to another test. Use the page this test was given.', run);
+        const call = readScreenshotCall(name, options);
+        if (typeof call === 'string')
+            throw misuse(call, run);
+        const label = `${soft ? 'expect.soft' : 'expect'}(page).toHaveScreenshot()`;
+        return run.assertion(label, location, () => pollScreenshot({ run, stepId, app, recipe: undefined, record: call.record, location, soft, timeoutMs: call.timeoutMs }), app);
+    }
     toBe() {
         throw misuse(misplaced.toBe, this.#scope.run);
     }
@@ -260,6 +343,21 @@ class ValueExpectation {
     toHaveTitle() {
         throw misuse(misplaced.toHaveTitle, this.#scope.run);
     }
+    toOverlap() {
+        throw misuse(misplaced.toOverlap, this.#scope.run);
+    }
+    toOverflowViewport() {
+        throw misuse(misplaced.toOverflowViewport, this.#scope.run);
+    }
+    toHaveClippedText() {
+        throw misuse(misplaced.toHaveClippedText, this.#scope.run);
+    }
+    toScrollHorizontally() {
+        throw misuse(misplaced.toScrollHorizontally, this.#scope.run);
+    }
+    toHaveScreenshot() {
+        throw misuse(misplaced.toHaveScreenshot, this.#scope.run);
+    }
     get not() {
         throw misuse(misplaced.not, this.#scope.run);
     }

package/dist/assertions/look-until.d.ts

@@ -19,6 +19,11 @@ export type LookOptions<Observed> = {
         ok: true;
     }>): Look<Observed> | undefined;
     passes(observation: Observed): boolean;
+    /**
+     * The waits before each look in milliseconds, counting from 0 for the first, the last repeating, for a check whose
+     * looks must be spaced, such as a screenshot's. Absent: `pollDelay`'s.
+     */
+    delays?: readonly number[];
 };
 /** How the looks went: the last, how many, when they began, and the failure that stopped them, if one did. */
 export type Looked<Observed> = {

package/dist/assertions/look-until.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"look-until.d.ts","sourceRoot":"","sources":["../../src/assertions/look-until.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC1E,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAItE,mHAAmH;AACnH,MAAM,MAAM,IAAI,CAAC,QAAQ,IAAI;IAC3B,WAAW,EAAE,QAAQ,CAAA;IACrB,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5B,CAAA;AAED,MAAM,MAAM,WAAW,CAAC,QAAQ,IAAI;IAClC,GAAG,EAAE,OAAO,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;IACpC,+FAA+F;IAC/F,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAChF,4EAA4E;IAC5E,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,EAAE;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IAC9E,MAAM,CAAC,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAA;CACvC,CAAA;AAED,8GAA8G;AAC9G,MAAM,MAAM,MAAM,CAAC,QAAQ,IAAI;IAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAAA;CAAE,CAAA;AAKtI,kHAAkH;AAClH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,+HAA+H;AAC/H,eAAO,MAAM,WAAW,EAAE,MAAW,CAAA;AAErC;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CA0CnG"}
+{"version":3,"file":"look-until.d.ts","sourceRoot":"","sources":["../../src/assertions/look-until.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC1E,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAItE,mHAAmH;AACnH,MAAM,MAAM,IAAI,CAAC,QAAQ,IAAI;IAC3B,WAAW,EAAE,QAAQ,CAAA;IACrB,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5B,CAAA;AAED,MAAM,MAAM,WAAW,CAAC,QAAQ,IAAI;IAClC,GAAG,EAAE,OAAO,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;IACpC,+FAA+F;IAC/F,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAChF,4EAA4E;IAC5E,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,EAAE;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IAC9E,MAAM,CAAC,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAA;IACtC;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3B,CAAA;AAED,8GAA8G;AAC9G,MAAM,MAAM,MAAM,CAAC,QAAQ,IAAI;IAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAAA;CAAE,CAAA;AAKtI,kHAAkH;AAClH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,+HAA+H;AAC/H,eAAO,MAAM,WAAW,EAAE,MAAW,CAAA;AAErC;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CA0CnG"}

package/dist/assertions/look-until.js

@@ -28,7 +28,7 @@ export async function lookUntil(options) {
     for (;;) {
         // Rounded up, so a wait cut to the deadline ends at it; a timer that fires early leaves time, and the loop waits again.
         const waitToEndMs = deadline.waitToEndMs;
-        const delay = smallestBudget(pollDelay(attempts), waitToEndMs);
+        const delay = smallestBudget(options.delays === undefined ? pollDelay(attempts) : (options.delays[Math.min(attempts, options.delays.length - 1)] ?? 0), waitToEndMs);
         let after;
         const changes = last?.changes;
         if (changes === undefined) {

package/dist/assertions/poll-layout.d.ts

@@ -0,0 +1,24 @@
+import type { TestRun } from '../api/test-run.ts';
+import type { SourceLocation } from '../protocol/failures.ts';
+import type { LayoutCheckRecord } from '../protocol/layout-checks.ts';
+import type { LocatorRecipe } from '../protocol/locator.ts';
+export type LayoutPollOptions = {
+    run: TestRun;
+    stepId: string | undefined;
+    app: string;
+    /** The element the matcher was called on; absent for a page matcher. */
+    recipe: LocatorRecipe | undefined;
+    /** The matcher and its arguments, which the parent judges the look the event names with. */
+    record: LayoutCheckRecord;
+    location: SourceLocation | undefined;
+    soft: boolean;
+    /** The matcher's own `timeout`, which may shorten the assertion budget and never lengthens it. */
+    timeoutMs?: number | undefined;
+};
+/**
+ * Measures an app's page until the layout check passes or the assertion's time runs out, as a locator assertion looks:
+ * it only reads, and never repeats the action before it. The event names the look its verdict rested on, carries the
+ * check whole, and records what that look measured, so the parent can judge it again.
+ */
+export declare function pollLayout(options: LayoutPollOptions): Promise<void>;
+//# sourceMappingURL=poll-layout.d.ts.map

package/dist/assertions/poll-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poll-layout.d.ts","sourceRoot":"","sources":["../../src/assertions/poll-layout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,KAAK,EAAW,cAAc,EAAiB,MAAM,yBAAyB,CAAA;AAErF,OAAO,KAAK,EAAe,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AAClF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAQ3D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,OAAO,CAAA;IACZ,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX,wEAAwE;IACxE,MAAM,EAAE,aAAa,GAAG,SAAS,CAAA;IACjC,4FAA4F;IAC5F,MAAM,EAAE,iBAAiB,CAAA;IACzB,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;IACpC,IAAI,EAAE,OAAO,CAAA;IACb,kGAAkG;IAClG,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC/B,CAAA;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsC1E"}

package/dist/assertions/poll-layout.js

@@ -0,0 +1,63 @@
+import { elapsedMs } from "../protocol/deadline.js";
+import { failure, truncateText } from "../protocol/failures.js";
+import { layoutCheck, layoutRequest } from "../protocol/layout-checks.js";
+import { lookUntil } from "./look-until.js";
+import { assertionTime, lookOf, lookReference } from "./poll-locator.js";
+import { reportAssertion } from "./report.js";
+/**
+ * Measures an app's page until the layout check passes or the assertion's time runs out, as a locator assertion looks:
+ * it only reads, and never repeats the action before it. The event names the look its verdict rested on, carries the
+ * check whole, and records what that look measured, so the parent can judge it again.
+ */
+export async function pollLayout(options) {
+    const { run, app, recipe, record, location } = options;
+    const check = layoutCheck(record);
+    const request = layoutRequest(record, recipe);
+    const timeoutMs = assertionTime(run, options.timeoutMs);
+    const looked = await lookUntil({
+        run,
+        timeoutMs,
+        location,
+        look: (lookMs, after) => run.observeLayout(app, request, lookMs, location, after),
+        read: (result) => (result.kind === 'observeLayout' ? lookOf(result.observation, result) : undefined),
+        passes: check.passes,
+    });
+    const { stopped, attempts } = looked;
+    const last = looked.last?.observation;
+    const passed = stopped === undefined && last !== undefined && check.passes(last);
+    const fields = {
+        testId: run.testId,
+        attemptId: run.attemptId,
+        ...(options.stepId === undefined ? {} : { stepId: options.stepId }),
+        session: app,
+        matcher: check.matcher,
+        ...(recipe === undefined ? {} : { locator: recipe }),
+        expected: truncateText(check.expected),
+        actual: last === undefined ? null : nullableText(check.actual(last)),
+        comparison: check.comparison,
+        attempts,
+        timeoutMs,
+        durationMs: elapsedMs(looked.startedAt, run.time.now),
+        ...(location === undefined ? {} : { location }),
+        ...lookReference(looked.last),
+        ...(last === undefined ? {} : { layout: check.measured(last) }),
+        check: record,
+    };
+    if (passed)
+        return reportAssertion(run, fields, undefined, false);
+    // Only the check's own verdict is softened; a page that could not be read stops the test as usual.
+    if (stopped !== undefined)
+        return reportAssertion(run, fields, stopped, false);
+    reportAssertion(run, fields, unmet({ check, recipe, last, attempts, timeoutMs, location }), options.soft);
+}
+function unmet({ check, recipe, last, attempts, timeoutMs, location }) {
+    if (last === undefined)
+        return failure('timeout', `The page answered no look within ${timeoutMs} ms.`, location);
+    const looked = `Looked ${attempts} ${attempts === 1 ? 'time' : 'times'} in ${timeoutMs} ms.`;
+    const details = { expected: truncateText(check.expected), received: nullableText(check.actual(last)), attempts, timeoutMs, comparison: check.comparison };
+    const reason = check.unmet(last, recipe);
+    return { ...failure(reason.class, `${reason.message} ${looked}`, location), details };
+}
+function nullableText(text) {
+    return text === null ? null : truncateText(text);
+}

package/dist/assertions/screenshot.d.ts

@@ -0,0 +1,36 @@
+import type { TestRun } from '../api/test-run.ts';
+import type { SourceLocation } from '../protocol/failures.ts';
+import type { LocatorRecipe } from '../protocol/locator.ts';
+import type { ScreenshotCheckRecord } from '../protocol/screenshot.ts';
+/** A screenshot check as the test called it: its record, and its own `timeout`, when it gave one. */
+export type ScreenshotCall = {
+    record: ScreenshotCheckRecord;
+    timeoutMs?: number;
+};
+/**
+ * Reads what a test passed `toHaveScreenshot`: the baseline's name, with a `.png` it ends in left off, and the options.
+ * Answers with a sentence for anything else, which the caller throws as misuse.
+ *
+ * @example readScreenshotCall('dashboard.png', { maxDiffPixels: 50 }) // { record: { matcher: 'toHaveScreenshot', name: 'dashboard', maxDiffPixels: 50 } }
+ */
+export declare function readScreenshotCall(name: unknown, options: unknown): ScreenshotCall | string;
+export type ScreenshotPollOptions = {
+    run: TestRun;
+    stepId: string | undefined;
+    app: string;
+    /** The element the matcher was called on; absent for the page. */
+    recipe: LocatorRecipe | undefined;
+    record: ScreenshotCheckRecord;
+    location: SourceLocation | undefined;
+    soft: boolean;
+    timeoutMs?: number | undefined;
+};
+/**
+ * Takes pictures of an app's page, or of one element, at the waits `pictureWaits` lists, until a picture has settled
+ * and passes against its baseline, the baseline is missing or cannot be read, or the assertion's time runs out, then
+ * judges the last. It only reads, and never repeats the action before it, so a page still loading passes once it
+ * shows its baseline, and a page that never stops moving fails as one that did not settle. The event names the look
+ * its verdict rested on and carries the check whole; the parent records what the picture showed.
+ */
+export declare function pollScreenshot(options: ScreenshotPollOptions): Promise<void>;
+//# sourceMappingURL=screenshot.d.ts.map

package/dist/assertions/screenshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../src/assertions/screenshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,KAAK,EAAW,cAAc,EAAiB,MAAM,yBAAyB,CAAA;AACrF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,KAAK,EAAmB,qBAAqB,EAAkB,MAAM,2BAA2B,CAAA;AAUvG,qGAAqG;AACrG,MAAM,MAAM,cAAc,GAAG;IAAE,MAAM,EAAE,qBAAqB,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAIlF;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,cAAc,GAAG,MAAM,CA2B3F;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,GAAG,EAAE,OAAO,CAAA;IACZ,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX,kEAAkE;IAClE,MAAM,EAAE,aAAa,GAAG,SAAS,CAAA;IACjC,MAAM,EAAE,qBAAqB,CAAA;IAC7B,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;IACpC,IAAI,EAAE,OAAO,CAAA;IACb,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC/B,CAAA;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2ClF"}

package/dist/assertions/screenshot.js

@@ -0,0 +1,125 @@
+import { formatValue } from "../api/format-value.js";
+import { elapsedMs } from "../protocol/deadline.js";
+import { failure, truncateText } from "../protocol/failures.js";
+import { pictureWaits, screenshotCheck, screenshotNameRefusal, screenshotRequest, thresholdRefusal } from "../protocol/screenshot.js";
+import { maxTimeout } from "../protocol/timeouts.js";
+import { lookUntil } from "./look-until.js";
+import { assertionTime, lookOf, lookReference } from "./poll-locator.js";
+import { reportAssertion } from "./report.js";
+const optionNames = ['threshold', 'maxDiffPixels', 'maxDiffPixelRatio', 'timeout'];
+/**
+ * Reads what a test passed `toHaveScreenshot`: the baseline's name, with a `.png` it ends in left off, and the options.
+ * Answers with a sentence for anything else, which the caller throws as misuse.
+ *
+ * @example readScreenshotCall('dashboard.png', { maxDiffPixels: 50 }) // { record: { matcher: 'toHaveScreenshot', name: 'dashboard', maxDiffPixels: 50 } }
+ */
+export function readScreenshotCall(name, options) {
+    if (typeof name !== 'string')
+        return `toHaveScreenshot() takes the name of its baseline, such as 'dashboard', received ${formatValue(name)}.`;
+    const named = name.endsWith('.png') ? name.slice(0, -'.png'.length) : name;
+    const refused = screenshotNameRefusal(named);
+    if (refused !== undefined)
+        return name === named ? refused : `${refused} A .png at the end of ${formatValue(name)} is left off.`;
+    if (options === undefined)
+        return { record: { matcher: 'toHaveScreenshot', name: named } };
+    const shape = `toHaveScreenshot() takes options such as { maxDiffPixels: 50 }, received ${formatValue(options)}.`;
+    if (typeof options !== 'object' || options === null || Array.isArray(options))
+        return shape;
+    const given = Object.entries(options).filter(([, value]) => value !== undefined);
+    if (given.some(([key]) => !optionNames.includes(key)))
+        return `${shape} Its options are threshold, maxDiffPixels, maxDiffPixelRatio and timeout.`;
+    const read = (key) => given.find(([option]) => option === key)?.[1];
+    const threshold = read('threshold');
+    const maxDiffPixels = read('maxDiffPixels');
+    const maxDiffPixelRatio = read('maxDiffPixelRatio');
+    const timeout = read('timeout');
+    if (threshold !== undefined && !isFraction(threshold))
+        return thresholdRefusal(formatValue(threshold));
+    if (maxDiffPixels !== undefined && !isCount(maxDiffPixels))
+        return `The maxDiffPixels option of toHaveScreenshot() is a whole number of pixels from 0, received ${formatValue(maxDiffPixels)}.`;
+    if (maxDiffPixelRatio !== undefined && !isFraction(maxDiffPixelRatio))
+        return `The maxDiffPixelRatio option of toHaveScreenshot() is a part of the pixels from 0 to 1, received ${formatValue(maxDiffPixelRatio)}.`;
+    if (timeout !== undefined && !(isCount(timeout) && timeout >= 1 && timeout <= maxTimeout))
+        return `The timeout option of toHaveScreenshot() must be a whole number of milliseconds from 1 to ${maxTimeout}, received ${formatValue(timeout)}.`;
+    const record = {
+        matcher: 'toHaveScreenshot',
+        name: named,
+        ...(threshold === undefined ? {} : { threshold }),
+        ...(maxDiffPixels === undefined ? {} : { maxDiffPixels }),
+        ...(maxDiffPixelRatio === undefined ? {} : { maxDiffPixelRatio }),
+    };
+    return timeout === undefined ? { record } : { record, timeoutMs: timeout };
+}
+/**
+ * Takes pictures of an app's page, or of one element, at the waits `pictureWaits` lists, until a picture has settled
+ * and passes against its baseline, the baseline is missing or cannot be read, or the assertion's time runs out, then
+ * judges the last. It only reads, and never repeats the action before it, so a page still loading passes once it
+ * shows its baseline, and a page that never stops moving fails as one that did not settle. The event names the look
+ * its verdict rested on and carries the check whole; the parent records what the picture showed.
+ */
+export async function pollScreenshot(options) {
+    const { run, app, recipe, record, location } = options;
+    const check = screenshotCheck(record);
+    const request = screenshotRequest(record, recipe);
+    const timeoutMs = assertionTime(run, options.timeoutMs);
+    let previous;
+    const looked = await lookUntil({
+        run,
+        timeoutMs,
+        location,
+        look: (lookMs) => run.observeScreenshot(app, request, previous, lookMs, location),
+        read: (result) => {
+            if (result.kind !== 'observeScreenshot')
+                return undefined;
+            previous = result.observationId;
+            return lookOf(result.observation, result);
+        },
+        passes: check.done,
+        delays: pictureWaits,
+    });
+    const { stopped, attempts } = looked;
+    const last = looked.last?.observation;
+    const passed = stopped === undefined && last !== undefined && check.passes(last);
+    const fields = {
+        testId: run.testId,
+        attemptId: run.attemptId,
+        ...(options.stepId === undefined ? {} : { stepId: options.stepId }),
+        session: app,
+        matcher: check.matcher,
+        ...(recipe === undefined ? {} : { locator: recipe }),
+        expected: truncateText(check.expected),
+        actual: last === undefined ? null : nullableText(check.actual(last)),
+        comparison: check.comparison,
+        attempts,
+        timeoutMs,
+        durationMs: elapsedMs(looked.startedAt, run.time.now),
+        ...(location === undefined ? {} : { location }),
+        ...lookReference(looked.last),
+        check: record,
+    };
+    if (passed)
+        return reportAssertion(run, fields, undefined, false);
+    // Only the check's own verdict is softened; a page that could not be pictured stops the test as usual.
+    if (stopped !== undefined)
+        return reportAssertion(run, fields, stopped, false);
+    reportAssertion(run, fields, unmet({ check, recipe, last, attempts, timeoutMs, location }), options.soft);
+}
+function unmet({ check, recipe, last, attempts, timeoutMs, location }) {
+    if (last === undefined)
+        return failure('timeout', `The page answered no look within ${timeoutMs} ms.`, location);
+    const looked = `Looked ${attempts} ${attempts === 1 ? 'time' : 'times'} in ${timeoutMs} ms.`;
+    const details = { expected: truncateText(check.expected), received: nullableText(check.actual(last)), attempts, timeoutMs, comparison: check.comparison };
+    const reason = check.unmet(last, recipe);
+    // A picture or a baseline that cannot be read says all there is, as the parent's own judgement says it.
+    const message = reason.class === 'setup_failed' ? reason.message : `${reason.message} ${looked}`;
+    return { ...failure(reason.class, message, location), details };
+}
+function nullableText(text) {
+    return text === null ? null : truncateText(text);
+}
+function isFraction(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+function isCount(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}

package/dist/browser/accessibility.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"accessibility.d.ts","sourceRoot":"","sources":["../../src/browser/accessibility.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAMvD,6HAA6H;AAC7H,MAAM,MAAM,SAAS,GAAG;IAAE,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAA;AAEtF,oDAAoD;AACpD,eAAO,MAAM,aAAa,EAAE,SAAS,QAAQ,EAU5C,CAAA;AAqBD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,MAAM,EAAE,CAEhE;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAsBtH"}
+{"version":3,"file":"accessibility.d.ts","sourceRoot":"","sources":["../../src/browser/accessibility.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAMvD,6HAA6H;AAC7H,MAAM,MAAM,SAAS,GAAG;IAAE,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAA;AAEtF,oDAAoD;AACpD,eAAO,MAAM,aAAa,EAAE,SAAS,QAAQ,EAU5C,CAAA;AA0BD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,MAAM,EAAE,CAEhE;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAiBtH"}

package/dist/browser/accessibility.js

@@ -29,6 +29,9 @@ const treeSchema = s.object({
     nodes: s.array(s.object({ ignored: s.boolean(), name: nameSchema, backendDOMNodeId: s.optional(s.number({ integer: true })) })),
 });
 const resolvedSchema = s.object({ object: s.object({ objectId: s.optional(s.string()) }) });
+const fullTreeSchema = s.object({
+    nodes: s.array(s.object({ ignored: s.boolean(), role: s.optional(s.object({ value: s.optional(s.string()) })), name: nameSchema, backendDOMNodeId: s.optional(s.number({ integer: true })) })),
+});
 /**
  * The names to ask Chrome's tree for a WAI-ARIA role by.
  *
@@ -43,6 +46,8 @@ export function chromeRolesFor(role) {
  * as elements under `aria-hidden="true"`; elements that are not rendered or are inert are not in its tree at all.
  */
 export async function elementsByRole(scope, query, deadline) {
+    if (scope.frame !== undefined)
+        return frameElementsByRole(scope, scope.frame, query, deadline);
     const { session, context, objectGroup } = scope;
     const evaluate = { expression: 'document', contextId: context, objectGroup };
     const document = await request(session, 'Runtime.evaluate', evaluate, documentSchema, sendOptions(deadline));
@@ -57,7 +62,23 @@ export async function elementsByRole(scope, query, deadline) {
         if (query.name === undefined || matchesText(node.name?.value ?? '', query.name, query.exact))
             found.add(node.backendDOMNodeId);
     }
-    const ids = [...found];
+    return resolveAll(scope, [...found], deadline);
+}
+// A frame of another site that is out of view is never drawn, and Chrome does not answer a query of its tree that waits
+// for it to be (`Accessibility.queryAXTree`). So a frame's whole tree is read at once, as Chrome computes it then, and the
+// query is answered from it by the same roles and names.
+async function frameElementsByRole(scope, frameId, query, deadline) {
+    const { nodes } = await request(scope.session, 'Accessibility.getFullAXTree', { frameId }, fullTreeSchema, sendOptions(deadline));
+    const found = new Set();
+    for (const node of nodes) {
+        if (node.ignored || node.backendDOMNodeId === undefined || !query.roles.includes(node.role?.value ?? ''))
+            continue;
+        if (query.name === undefined || matchesText(node.name?.value ?? '', query.name, query.exact))
+            found.add(node.backendDOMNodeId);
+    }
+    return resolveAll(scope, [...found], deadline);
+}
+async function resolveAll(scope, ids, deadline) {
     const elements = [];
     for (let start = 0; start < ids.length; start += resolveBatch) {
         const objectIds = await Promise.all(ids.slice(start, start + resolveBatch).map((id) => resolve(scope, id, deadline)));

package/dist/browser/actionability.d.ts

@@ -1,6 +1,7 @@
 import type { ActionIntent, SelectPlan } from './element-queries.ts';
 import type { Point } from './input.ts';
-import type { IsolatedWorld } from './isolated-world.ts';
+import type { Guard } from './input-guard.ts';
+import type { PageWorld } from './isolated-world.ts';
 import type { Deadline } from '../protocol/deadline.ts';
 import type { Failure } from '../protocol/failures.ts';
 import type { LocatorRecipe } from '../protocol/locator.ts';
@@ -9,12 +10,14 @@ import type { PageFacts } from '../protocol/page-facts.ts';
  * An element, or the document, that passed every check. `point` is where to act, or null for a key, which goes to
  * the focus. `context` is the document the look ran in, which holds the guard the look armed with `token`, or none
  * for a `select`'s look. `via` is `'label'` when a hidden control is acted on through its label, `scale` the visual
- * viewport's, `page` the page the look read, and `plan` the keys that make a select's choice.
+ * viewport's, `page` the page the look read, and `plan` the keys that make a select's choice. An element in a frame
+ * has, in `around`, the guards its look armed in the documents around the frame.
  */
 export type ReadyTarget = {
     point: Point | null;
     context: number;
     token: number | null;
+    around?: readonly Guard[];
     via: 'label' | undefined;
     scale: number;
     page: PageFacts;
@@ -41,7 +44,7 @@ export type PendingNavigation = {
     url: string;
 };
 export type ActionabilityOptions = {
-    world: IsolatedWorld;
+    world: PageWorld;
     /** The element to act on, or undefined for input the document takes, which only waits out a navigation. */
     locator: LocatorRecipe | undefined;
     intent: ActionIntent;
@@ -70,10 +73,10 @@ export declare function invalidSelector({ step, message }: {
     message: string;
 }, locator: LocatorRecipe, intent: ActionIntent | undefined): Failure;
 /**
- * The failure for a locator by Playwright's rules on a document that holds an open shadow root. Playwright looks inside
- * one, and Retest does not, so it fails at once rather than find less than Playwright would.
+ * The failure for a role or label lookup whose search holds an open shadow root, on an engine whose accessibility tree,
+ * as Retest reads it, does not look inside one. Chrome's does, so the lookup fails at once rather than find less.
  *
- * @example shadowRefused('<todo-list>', { by: 'role', role: 'button', dialect: 'playwright' }, undefined).class // 'unsupported'
+ * @example shadowRefused('<todo-list>', { by: 'role', role: 'button' }, undefined).class // 'unsupported'
  */
 export declare function shadowRefused(host: string, locator: LocatorRecipe, intent: ActionIntent | undefined): Failure;
 //# sourceMappingURL=actionability.d.ts.map

package/dist/browser/actionability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actionability.d.ts","sourceRoot":"","sources":["../../src/browser/actionability.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAoC,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtG,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,KAAK,EAAc,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAA;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAW1D;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,GAAG,EAAE,OAAO,GAAG,SAAS,CAAA;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,SAAS,CAAA;IACf,IAAI,EAAE,UAAU,GAAG,IAAI,CAAA;CACxB,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GACpB,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,WAAW,CAAC,GAC3C;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACjE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAA;AAEnC,mHAAmH;AACnH,MAAM,MAAM,iBAAiB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAA;AAE/C,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,aAAa,CAAA;IACpB,2GAA2G;IAC3G,OAAO,EAAE,aAAa,GAAG,SAAS,CAAA;IAClC,MAAM,EAAE,YAAY,CAAA;IACpB,QAAQ,EAAE,QAAQ,CAAA;IAClB,+FAA+F;IAC/F,iBAAiB,EAAE,MAAM,iBAAiB,GAAG,SAAS,CAAA;CACvD,CAAA;AA0BD;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,YAAY,CAAC,CAW9F;AAmFD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,CAKvJ;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,CAO7G"}
+{"version":3,"file":"actionability.d.ts","sourceRoot":"","sources":["../../src/browser/actionability.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAA8C,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAChH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAA;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAY1D;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,CAAA;IACzB,GAAG,EAAE,OAAO,GAAG,SAAS,CAAA;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,SAAS,CAAA;IACf,IAAI,EAAE,UAAU,GAAG,IAAI,CAAA;CACxB,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GACpB,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,WAAW,CAAC,GAC3C;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACjE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAA;AAEnC,mHAAmH;AACnH,MAAM,MAAM,iBAAiB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAA;AAE/C,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,SAAS,CAAA;IAChB,2GAA2G;IAC3G,OAAO,EAAE,aAAa,GAAG,SAAS,CAAA;IAClC,MAAM,EAAE,YAAY,CAAA;IACpB,QAAQ,EAAE,QAAQ,CAAA;IAClB,+FAA+F;IAC/F,iBAAiB,EAAE,MAAM,iBAAiB,GAAG,SAAS,CAAA;CACvD,CAAA;AA0BD;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,YAAY,CAAC,CAW9F;AAoFD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,CAKvJ;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,CAQ7G"}

package/dist/browser/actionability.js

@@ -5,6 +5,7 @@ import { secretPlaceholder } from "../protocol/secret.js";
 import { CdpTimeoutError } from "./cdp/errors.js";
 import { pageFactsOf } from "./document-facts.js";
 import { armDocument, describeAction, prepare } from "./element-queries.js";
+import { engineShortOfShadowRoots } from "./locate.js";
 import { originRefusal } from "./origin-refusal.js";
 import { originAndPath } from "./page-url.js";
 const firstPauseMs = 20;
@@ -61,10 +62,10 @@ async function look({ world, locator, intent, deadline, pendingNavigation }, las
     }
     return lookedAt(seen, locator, intent);
 }
-function lookedAt({ value: readiness, context }, locator, intent) {
+function lookedAt({ value: readiness, context, around }, locator, intent) {
     switch (readiness.status) {
         case 'ready':
-            return { kind: 'settled', target: readyTarget(readiness, context) };
+            return { kind: 'settled', target: readyTarget(readiness, context, around) };
         case 'unchanged':
             return { kind: 'settled', target: { ok: true, kind: 'unchanged', page: pageFactsOf(readiness.page), context } };
         case 'missing':
@@ -102,9 +103,10 @@ function settledFailure(readiness, locator, intent) {
         }
     }
 }
-function readyTarget(readiness, context) {
+function readyTarget(readiness, context, around) {
     const { point, token, via, scale, page, plan } = readiness;
-    return { ok: true, kind: 'ready', point, context, token, via: via ?? undefined, scale, page: pageFactsOf(page), plan };
+    const through = around === undefined || around.length === 0 ? {} : { around };
+    return { ok: true, kind: 'ready', point, context, token, ...through, via: via ?? undefined, scale, page: pageFactsOf(page), plan };
 }
 // Only an action on an element can meet an element that does not suit it.
 function elementOf(locator) {
@@ -133,16 +135,17 @@ export function invalidSelector({ step, message }, locator, intent) {
     return { class: 'usage', message: `Could not ${action}: the page cannot read the CSS selector in ${selector}. ${message}`, details: { selector } };
 }
 /**
- * The failure for a locator by Playwright's rules on a document that holds an open shadow root. Playwright looks inside
- * one, and Retest does not, so it fails at once rather than find less than Playwright would.
+ * The failure for a role or label lookup whose search holds an open shadow root, on an engine whose accessibility tree,
+ * as Retest reads it, does not look inside one. Chrome's does, so the lookup fails at once rather than find less.
  *
- * @example shadowRefused('<todo-list>', { by: 'role', role: 'button', dialect: 'playwright' }, undefined).class // 'unsupported'
+ * @example shadowRefused('<todo-list>', { by: 'role', role: 'button' }, undefined).class // 'unsupported'
  */
 export function shadowRefused(host, locator, intent) {
     const action = intent === undefined ? `read ${describeLocator(locator)}` : describeAction(intent, locator);
+    const engine = engineShortOfShadowRoots() ?? 'this browser';
     return {
         class: 'unsupported',
-        message: `Could not ${action}: the page holds an open shadow root, in ${host}. Playwright looks inside shadow roots and Retest does not, so Retest refuses the lookup rather than find less than Playwright would.`,
+        message: `Could not ${action}: on ${engine}, Retest finds by role or label outside shadow roots only, and the open shadow root of ${host} could hold a match. Find the element by test id, text or CSS.`,
         details: { host },
     };
 }
@@ -214,6 +217,12 @@ function unsupported(readiness, locator, intent) {
                 message: `Could not ${action}: it is ${element}, which takes one option, and select() was given a list. Pass one option, not a list.`,
                 details: { element },
             };
+        case 'toggle': {
+            // Only an intent that carries the engine's reason asks the page to refuse a toggle.
+            if (intent.action !== 'select' || intent.toggleRefusal === undefined)
+                throw new Error("Retest's page script refused a toggle its engine sends");
+            return { class: 'unsupported', message: `Could not ${action}: ${intent.toggleRefusal} Retest sent no input.`, details: { inputSent: false } };
+        }
     }
 }
 function unready(last, locator, intent, deadline) {

package/dist/browser/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/browser/browser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAe7G,4HAA4H;AAC5H,MAAM,MAAM,cAAc,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAEvG,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,eAAe,CAAA;IACxB,cAAc,EAAE,MAAM,CAAA;IACtB,UAAU,EAAE,aAAa,CAAA;IACzB,OAAO,EAAE,cAAc,CAAA;IACvB,+FAA+F;IAC/F,eAAe,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAC1C,CAAA;AAKD,oEAAoE;AACpE,qBAAa,eAAgB,YAAW,UAAU;;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,wFAAwF;IACxF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;gBAUhB,OAAO,EAAE,cAAc;IA2BnC,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,QAAQ,IAAI,kBAAkB,CAEjC;IAIK,OAAO,CAAC,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAwC9E,YAAY,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAU5D,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAkDxC;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,CAIzH"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/browser/browser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAiB7G,4HAA4H;AAC5H,MAAM,MAAM,cAAc,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAEvG,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,eAAe,CAAA;IACxB,cAAc,EAAE,MAAM,CAAA;IACtB,UAAU,EAAE,aAAa,CAAA;IACzB,OAAO,EAAE,cAAc,CAAA;IACvB,+FAA+F;IAC/F,eAAe,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAC1C,CAAA;AAKD,oEAAoE;AACpE,qBAAa,eAAgB,YAAW,UAAU;;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,wFAAwF;IACxF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;gBAYhB,OAAO,EAAE,cAAc;IA8BnC,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,QAAQ,IAAI,kBAAkB,CAEjC;IAIK,OAAO,CAAC,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IA2C9E,YAAY,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAU5D,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAmDxC;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,CAIzH"}