@lullabot/playwright-testing 0.1.0

package/lib/github/report-paths.js

@@ -0,0 +1,200 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePathPrefix = parsePathPrefix;
+exports.createPathResolver = createPathResolver;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Translate the file paths a Playwright JSON report records into paths the
+ * process reading that report can actually open.
+ *
+ * The two are not always the same file system. Running Playwright inside a
+ * container — which is the normal arrangement for this package, where the suite
+ * runs in DDEV's web container — records every attachment under the path it had
+ * *there*, `/var/www/html/…`. A workflow step reading the report on the runner
+ * is on the other side of that boundary, and `/var/www/html` means nothing to
+ * it. The report is readable, the attachments are not, and nothing about the
+ * failure says why.
+ *
+ * The bind mount that creates the problem also solves it: the same files are
+ * visible from both sides under different prefixes, so the paths need
+ * re-rooting rather than fetching. What the two views share is the tail of the
+ * path — the part below the mount point — so the mount point is found by
+ * hanging progressively longer tails of a recorded path off the directories
+ * around the report until one of them names a file that exists.
+ *
+ * Every mapping is confirmed against the disk before it is used, so a wrong
+ * guess resolves to nothing rather than to the wrong image. The report's own
+ * `config` is deliberately not consulted: `rootDir` is the *test* directory
+ * rather than the project root, and `outputDir` need not contain the report,
+ * so neither reliably shares a tail with the path the report was read from.
+ *
+ * Symlinking the container path on the runner instead looks like it should
+ * work and does not: the Ubuntu runner image ships Apache, so /var/www/html
+ * already exists as a directory and `ln -sfn` quietly creates the link inside
+ * it. The command exits 0 and changes nothing.
+ */
+/**
+ * Shortest tail worth trying, in path components.
+ *
+ * A bare file name is too little to identify a file by — some unrelated
+ * `fixture-diff.png` elsewhere in the tree would match. One directory of
+ * context makes a coincidence unlikely, and longer tails are tried first
+ * regardless, so the most specific match always wins.
+ */
+const MIN_TAIL_COMPONENTS = 2;
+/**
+ * Parse a `FROM:TO` pair, as `--path-prefix` takes it.
+ *
+ * Split on the first colon: `TO` is a local absolute path and may itself
+ * contain one on Windows, whereas `FROM` comes from a container and will not.
+ */
+function parsePathPrefix(value) {
+    const separator = value.indexOf(':');
+    if (separator <= 0)
+        return null;
+    const from = value.slice(0, separator).trim();
+    const to = value.slice(separator + 1).trim();
+    if (!from || !to)
+        return null;
+    return { from, to };
+}
+/**
+ * Build the function that turns a recorded path into a readable one.
+ *
+ * A path that already resolves is left alone, so this costs one `stat` per
+ * attachment when the report and the files are on the same side. A mapping
+ * worked out for one attachment is kept and tried first for the rest, so the
+ * search runs once per run rather than once per image.
+ */
+function createPathResolver(options) {
+    const exists = options.exists ?? ((filePath) => fs.existsSync(filePath));
+    const explicit = options.prefixes ?? [];
+    const searchRoots = ancestors(path.dirname(path.resolve(options.reportPath)));
+    const learned = [];
+    /** Hang tails of the recorded path off each directory around the report. */
+    function search(filePath) {
+        const target = splitPath(filePath);
+        // Longest tail first, so the most specific match wins. Stop one short of
+        // the whole path: something has to be left to rewrite.
+        for (let length = target.components.length - 1; length >= MIN_TAIL_COMPONENTS; length--) {
+            const tail = target.components.slice(target.components.length - length).join('/');
+            for (const root of searchRoots) {
+                const candidate = `${trimTrailingSeparators(root)}/${tail}`;
+                if (!exists(candidate))
+                    continue;
+                return {
+                    path: candidate,
+                    found: true,
+                    prefix: { from: joinPath(target, target.components.length - length), to: root },
+                };
+            }
+        }
+        return null;
+    }
+    return (filePath) => {
+        if (exists(filePath))
+            return { path: filePath, found: true };
+        for (const prefix of [...explicit, ...learned]) {
+            const rewritten = applyPrefix(filePath, prefix);
+            if (rewritten && exists(rewritten))
+                return { path: rewritten, found: true, prefix };
+        }
+        const discovered = search(filePath);
+        if (!discovered)
+            return { path: filePath, found: false };
+        if (discovered.prefix)
+            learned.push(discovered.prefix);
+        return discovered;
+    };
+}
+/** Swap one prefix for another, or null when the path is not under it. */
+function applyPrefix(filePath, prefix) {
+    const from = splitPath(prefix.from);
+    const target = splitPath(filePath);
+    if (target.components.length < from.components.length)
+        return null;
+    for (let index = 0; index < from.components.length; index++) {
+        if (target.components[index] !== from.components[index])
+            return null;
+    }
+    const rest = target.components.slice(from.components.length);
+    const to = trimTrailingSeparators(prefix.to);
+    return rest.length === 0 ? to : `${to}/${rest.join('/')}`;
+}
+/**
+ * Trim trailing separators.
+ *
+ * An index scan rather than `/[\\/]+$/`, because that pattern backtracks
+ * quadratically over a long run of separators — and these strings are paths
+ * out of a report this package did not write.
+ */
+function trimTrailingSeparators(value) {
+    let end = value.length;
+    while (end > 0 && (value[end - 1] === '/' || value[end - 1] === '\\'))
+        end--;
+    return value.slice(0, end);
+}
+/**
+ * Split a path into a root and its components, accepting either separator.
+ *
+ * The two sides of the boundary need not agree on the separator, and the
+ * recorded paths come from a report rather than from this platform.
+ */
+function splitPath(value) {
+    const match = /^([A-Za-z]:[\\/]|[\\/])?/.exec(value);
+    const prefix = match?.[1] ?? '';
+    return {
+        root: prefix.replace(/\\/g, '/'),
+        components: value.slice(prefix.length).split(/[\\/]+/).filter(Boolean),
+    };
+}
+/** Rebuild a path from its first `count` components. */
+function joinPath(split, count) {
+    return split.root + split.components.slice(0, count).join('/');
+}
+/** A directory and every directory above it. */
+function ancestors(directory) {
+    const out = [];
+    let current = directory;
+    for (;;) {
+        out.push(current);
+        const parent = path.dirname(current);
+        if (parent === current)
+            return out;
+        current = parent;
+    }
+}

package/lib/hover.d.ts

@@ -0,0 +1,13 @@
+import { Page } from "@playwright/test";
+/**
+ * Move the pointer away from page content for a deterministic screenshot.
+ *
+ * Pointer position survives clicks, navigation, and layout changes. That can
+ * leave an unrelated element under the pointer and activate its `:hover`
+ * styles. A transparent shield gives the pointer a neutral target regardless
+ * of what the page renders at the chosen coordinate.
+ *
+ * The returned cleanup function removes the shield. Call it after the
+ * screenshot so normal pointer hit testing is restored.
+ */
+export declare function clearHover(page: Page): Promise<() => Promise<void>>;

package/lib/hover.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearHover = clearHover;
+const HOVER_SHIELD_ATTRIBUTE = 'data-playwright-testing-hover-shield';
+/**
+ * Move the pointer away from page content for a deterministic screenshot.
+ *
+ * Pointer position survives clicks, navigation, and layout changes. That can
+ * leave an unrelated element under the pointer and activate its `:hover`
+ * styles. A transparent shield gives the pointer a neutral target regardless
+ * of what the page renders at the chosen coordinate.
+ *
+ * The returned cleanup function removes the shield. Call it after the
+ * screenshot so normal pointer hit testing is restored.
+ */
+async function clearHover(page) {
+    await page.evaluate((attribute) => {
+        document.querySelector(`[${attribute}]`)?.remove();
+        const shield = document.createElement('playwright-testing-hover-shield');
+        shield.setAttribute(attribute, '');
+        shield.setAttribute('aria-hidden', 'true');
+        shield.style.cssText = [
+            'all: initial !important',
+            'position: fixed !important',
+            'inset: 0 !important',
+            'display: block !important',
+            'width: 100vw !important',
+            'height: 100vh !important',
+            'margin: 0 !important',
+            'padding: 0 !important',
+            'border: 0 !important',
+            'opacity: 0 !important',
+            'pointer-events: auto !important',
+            'z-index: 2147483647 !important',
+        ].join(';');
+        document.documentElement.appendChild(shield);
+    }, HOVER_SHIELD_ATTRIBUTE);
+    try {
+        // Playwright emits a mousemove even when the pointer was already at this
+        // coordinate, ensuring mouseleave/pointerleave handlers get a chance to
+        // respond to the new hit target.
+        await page.mouse.move(0, 0);
+    }
+    catch (error) {
+        await removeHoverShield(page);
+        throw error;
+    }
+    let removed = false;
+    return async () => {
+        if (removed) {
+            return;
+        }
+        removed = true;
+        await removeHoverShield(page);
+    };
+}
+async function removeHoverShield(page) {
+    await page.evaluate((attribute) => {
+        document.querySelector(`[${attribute}]`)?.remove();
+    }, HOVER_SHIELD_ATTRIBUTE);
+}

package/lib/images.d.ts

@@ -0,0 +1,118 @@
+import { Page } from "@playwright/test";
+export interface WaitForImagesOptions {
+    /** How long to wait for visible images to decode. */
+    decodeTimeoutMs?: number;
+    /**
+     * Re-request broken images with a cache-busting URL. This mutates `src`,
+     * `srcset`, and enclosing `<picture>` sources, so it is disabled by default.
+     */
+    recoverErroredImages?: boolean;
+    /** Optional adapter hook run after the viewport has returned to the top. */
+    afterScroll?: (page: Page) => Promise<void>;
+}
+/**
+ * Wait for images specified by a selector to load.
+ *
+ * The function must scroll the page to handle lazy-loading images. After all
+ * images have loaded, the page is scrolled back to the top.
+ *
+ * See https://github.com/microsoft/playwright/issues/14388 for further details.
+ *
+ * @param page
+ * @param selector
+ */
+export declare function waitForImages(page: Page, selector: string, options?: WaitForImagesOptions): Promise<void>;
+/**
+ * Wait for a single image to stop being in flight.
+ *
+ * Returns without a promise for an image that needs no waiting at all: one that
+ * has already settled, or a 1x1 image that is visually hidden for accessibility
+ * (a common visually-hidden accessibility technique), which would otherwise
+ * hang forever -- even
+ * though such images are :visible, Chrome doesn't load them at desktop widths. See
+ * https://www.tpgi.com/the-anatomy-of-visually-hidden/ for how .visually-hidden
+ * works.
+ *
+ * Otherwise it waits for the request to finish, whether it succeeds or fails.
+ * Waiting on `load` alone would hang until the test timed out on any image that
+ * errors after the wait begins -- a 404, or an image proxy that fails while it
+ * fetches the original on demand -- because such an image only ever
+ * fires `error`. That hang is worse than useless here: it happens before
+ * waitForImagesToDecode() runs, so it also denies the one piece of code that
+ * knows how to re-request a broken image the chance to recover it. Settling on
+ * `error` hands the image on to that recovery instead.
+ *
+ * Listeners are added rather than assigned to `onload`/`onerror` so that any
+ * handler the page itself installed keeps working.
+ *
+ * This runs in the browser via `evaluate()`, which serializes the function
+ * source, so it must stay self-contained and reference nothing else in this
+ * module. It is exported so the waiting can be tested directly.
+ *
+ * @param image
+ */
+export declare function settleImage(image: HTMLImageElement): void | Promise<void>;
+/**
+ * Wait for all image tags on the page to load.
+ *
+ * @param page
+ */
+export declare function waitForAllImages(page: Page, options?: WaitForImagesOptions): Promise<void>;
+/**
+ * Poll every visible image until it decodes, optionally re-requesting failures.
+ *
+ * A loaded image is `complete` with a `naturalWidth` greater than zero. An
+ * errored request (a 404, or an image proxy that fails while it
+ * fetches the original on demand) is `complete` with a `naturalWidth` of 0 and
+ * would otherwise be screenshotted as a broken image. A zero `naturalWidth` is
+ * ambiguous, though -- a valid but dimensionless image such as an SVG without an
+ * intrinsic size reports it too -- so `decode()` disambiguates: it rejects only
+ * for a genuine failure. When recovery is explicitly enabled, a broken image
+ * is re-requested with a cache-busting query parameter. The retry reuses
+ * `currentSrc` (the URL already
+ * chosen from `srcset`) and drops the responsive sources so that exact image
+ * loads, keeping the render identical to a clean first load. 1x1
+ * visually-hidden images are skipped.
+ *
+ * This runs in the browser via `page.evaluate()`, which serializes the function
+ * source, so it must stay self-contained and reference nothing else in this
+ * module. It is exported separately from waitForImagesToDecode() so the polling
+ * can be tested directly.
+ *
+ * Every image is checked at least once, even with a timeout of zero, and the
+ * images that never settled are returned rather than swallowed so the caller
+ * can report them.
+ *
+ * @param options.timeoutMs How long to keep polling before giving up.
+ * @param options.pollMs How long to sleep between polls.
+ * @param options.reloadIntervalMs How long to leave a re-requested image to
+ *   resolve before re-requesting it again.
+ * @param options.recoverErroredImages Whether broken image sources may be
+ *   rewritten and re-requested. Defaults to false.
+ * @returns The URLs of the images that never decoded. Empty when they all did.
+ */
+export declare function decodeVisibleImages(options: {
+    timeoutMs: number;
+    pollMs?: number;
+    reloadIntervalMs?: number;
+    recoverErroredImages?: boolean;
+}): Promise<string[]>;
+/**
+ * Wait for every visible image to finish decoding.
+ *
+ * See decodeVisibleImages() for how an image is judged loaded, broken, or
+ * merely dimensionless, and how broken ones are re-requested.
+ *
+ * Giving up is not an error: a page that legitimately references a missing
+ * image should still be screenshotted and still have its accessibility checked,
+ * and the screenshot comparison is what fails. But the wait is not silent
+ * either -- the images that never decoded are warned about, so a mysterious
+ * pixel diff (and the timeout's worth of delay before it) has an explanation --
+ * and they are returned so a caller can assert on them.
+ *
+ * @param page
+ * @param timeoutMs How long to wait for images to decode before giving up.
+ * @param recoverErroredImages Whether broken image sources may be rewritten.
+ * @returns The URLs of the images that never decoded. Empty when they all did.
+ */
+export declare function waitForImagesToDecode(page: Page, timeoutMs?: number, recoverErroredImages?: boolean): Promise<string[]>;

package/lib/images.js

@@ -0,0 +1,260 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitForImages = waitForImages;
+exports.settleImage = settleImage;
+exports.waitForAllImages = waitForAllImages;
+exports.decodeVisibleImages = decodeVisibleImages;
+exports.waitForImagesToDecode = waitForImagesToDecode;
+/**
+ * Wait for images specified by a selector to load.
+ *
+ * The function must scroll the page to handle lazy-loading images. After all
+ * images have loaded, the page is scrolled back to the top.
+ *
+ * See https://github.com/microsoft/playwright/issues/14388 for further details.
+ *
+ * @param page
+ * @param selector
+ */
+async function waitForImages(page, selector, options = {}) {
+    const locators = page.locator(selector);
+    try {
+        // Trigger lazy-loading images. Since this should be fast, and we don't want to
+        // have to deal with concurrency bugs, we do this in serial.
+        for (const l of await locators.all()) {
+            // Ensure images are connected to the DOM before trying to scroll to them.
+            // https://github.com/microsoft/playwright/issues/23758
+            if (await l.evaluate(image => image.isConnected)) {
+                await l.scrollIntoViewIfNeeded();
+            }
+        }
+        // Make sure all images have loaded.
+        const promises = (await locators.all()).map(locator => locator.evaluate(settleImage));
+        await Promise.all(promises);
+        // The wait above treats an errored image as "loaded". Decode each visible
+        // image as well; source rewriting is available only when explicitly enabled.
+        await waitForImagesToDecode(page, options.decodeTimeoutMs ?? 15000, options.recoverErroredImages ?? false);
+    }
+    finally {
+        // Lazy-loading scrolls the document. Always put it back, including when an
+        // image listener, decode poll, or adapter hook fails.
+        await page.evaluate(() => window.scroll({
+            top: 0,
+            left: 0,
+            behavior: 'instant',
+        }));
+        // window.scroll is async and doesn't return a promise, so wait until the
+        // browser confirms we are at the top again.
+        const scrollState = { forced: false };
+        await page.waitForFunction(state => {
+            if (window.scrollY !== 0 && !state.forced) {
+                window.scroll({ top: 0, left: 0, behavior: 'instant' });
+                state.forced = true;
+            }
+            return window.scrollY === 0;
+        }, scrollState);
+        await options.afterScroll?.(page);
+    }
+}
+/**
+ * Wait for a single image to stop being in flight.
+ *
+ * Returns without a promise for an image that needs no waiting at all: one that
+ * has already settled, or a 1x1 image that is visually hidden for accessibility
+ * (a common visually-hidden accessibility technique), which would otherwise
+ * hang forever -- even
+ * though such images are :visible, Chrome doesn't load them at desktop widths. See
+ * https://www.tpgi.com/the-anatomy-of-visually-hidden/ for how .visually-hidden
+ * works.
+ *
+ * Otherwise it waits for the request to finish, whether it succeeds or fails.
+ * Waiting on `load` alone would hang until the test timed out on any image that
+ * errors after the wait begins -- a 404, or an image proxy that fails while it
+ * fetches the original on demand -- because such an image only ever
+ * fires `error`. That hang is worse than useless here: it happens before
+ * waitForImagesToDecode() runs, so it also denies the one piece of code that
+ * knows how to re-request a broken image the chance to recover it. Settling on
+ * `error` hands the image on to that recovery instead.
+ *
+ * Listeners are added rather than assigned to `onload`/`onerror` so that any
+ * handler the page itself installed keeps working.
+ *
+ * This runs in the browser via `evaluate()`, which serializes the function
+ * source, so it must stay self-contained and reference nothing else in this
+ * module. It is exported so the waiting can be tested directly.
+ *
+ * @param image
+ */
+function settleImage(image) {
+    if ((image.width <= 1 && image.height <= 1) || image.complete) {
+        return;
+    }
+    return new Promise(resolve => {
+        const settled = () => {
+            image.removeEventListener("load", settled);
+            image.removeEventListener("error", settled);
+            resolve();
+        };
+        image.addEventListener("load", settled);
+        image.addEventListener("error", settled);
+    });
+}
+/**
+ * Wait for all image tags on the page to load.
+ *
+ * @param page
+ */
+async function waitForAllImages(page, options = {}) {
+    await waitForImages(page, 'img:visible', options);
+}
+/**
+ * Poll every visible image until it decodes, optionally re-requesting failures.
+ *
+ * A loaded image is `complete` with a `naturalWidth` greater than zero. An
+ * errored request (a 404, or an image proxy that fails while it
+ * fetches the original on demand) is `complete` with a `naturalWidth` of 0 and
+ * would otherwise be screenshotted as a broken image. A zero `naturalWidth` is
+ * ambiguous, though -- a valid but dimensionless image such as an SVG without an
+ * intrinsic size reports it too -- so `decode()` disambiguates: it rejects only
+ * for a genuine failure. When recovery is explicitly enabled, a broken image
+ * is re-requested with a cache-busting query parameter. The retry reuses
+ * `currentSrc` (the URL already
+ * chosen from `srcset`) and drops the responsive sources so that exact image
+ * loads, keeping the render identical to a clean first load. 1x1
+ * visually-hidden images are skipped.
+ *
+ * This runs in the browser via `page.evaluate()`, which serializes the function
+ * source, so it must stay self-contained and reference nothing else in this
+ * module. It is exported separately from waitForImagesToDecode() so the polling
+ * can be tested directly.
+ *
+ * Every image is checked at least once, even with a timeout of zero, and the
+ * images that never settled are returned rather than swallowed so the caller
+ * can report them.
+ *
+ * @param options.timeoutMs How long to keep polling before giving up.
+ * @param options.pollMs How long to sleep between polls.
+ * @param options.reloadIntervalMs How long to leave a re-requested image to
+ *   resolve before re-requesting it again.
+ * @param options.recoverErroredImages Whether broken image sources may be
+ *   rewritten and re-requested. Defaults to false.
+ * @returns The URLs of the images that never decoded. Empty when they all did.
+ */
+async function decodeVisibleImages(options) {
+    const timeoutMs = options.timeoutMs;
+    const pollMs = options.pollMs ?? 250;
+    const reloadIntervalMs = options.reloadIntervalMs ?? 2000;
+    const recoverErroredImages = options.recoverErroredImages ?? false;
+    const deadline = Date.now() + timeoutMs;
+    const isCandidate = (img) => {
+        // Skip 1x1 visually-hidden images (see waitForImages above).
+        if (img.width <= 1 && img.height <= 1) {
+            return false;
+        }
+        const rect = img.getBoundingClientRect();
+        if (rect.width === 0 || rect.height === 0) {
+            return false;
+        }
+        const style = getComputedStyle(img);
+        return style.visibility !== "hidden" && style.display !== "none";
+    };
+    const reload = (img) => {
+        const src = img.currentSrc || img.src;
+        if (!src || src.startsWith("data:")) {
+            return;
+        }
+        try {
+            const url = new URL(src, location.href);
+            url.searchParams.set("playwrightReload", String(Date.now()));
+            // Drop the responsive sources so the resolved URL we just loaded is the
+            // one fetched, instead of re-running srcset selection.
+            const picture = img.closest("picture");
+            if (picture) {
+                picture.querySelectorAll("source").forEach(source => source.remove());
+            }
+            img.removeAttribute("srcset");
+            img.src = url.href;
+        }
+        catch {
+            // Ignore anything that is not a reloadable URL.
+        }
+    };
+    let lastReload = 0;
+    // Checking before testing the deadline means a zero or already-elapsed
+    // timeout still reports on the images instead of claiming success.
+    for (;;) {
+        const candidates = Array.from(document.images).filter(isCandidate);
+        // Collect the verdicts positionally rather than pushing as each check
+        // settles, so anything reported below stays in document order.
+        const verdicts = await Promise.all(candidates.map(async (img) => {
+            if (img.complete && img.naturalWidth > 0) {
+                return "loaded"; // Loaded with intrinsic dimensions.
+            }
+            if (!img.complete) {
+                return "loading";
+            }
+            // Complete with a zero naturalWidth is ambiguous: a genuine load error
+            // (404/503) rejects decode(), while a valid but dimensionless image
+            // (such as an SVG with no intrinsic size) resolves it. Only the former
+            // should be re-requested; the latter is already settled.
+            try {
+                await img.decode();
+                return "loaded";
+            }
+            catch {
+                return "errored";
+            }
+        }));
+        const pending = candidates.filter((img, index) => verdicts[index] !== "loaded");
+        const errored = candidates.filter((img, index) => verdicts[index] === "errored");
+        if (pending.length === 0) {
+            return [];
+        }
+        if (Date.now() >= deadline) {
+            return pending.map(img => {
+                const src = img.currentSrc || img.src;
+                try {
+                    // Report the URL as the page authored it, without the cache-busting
+                    // parameter a retry added, so the warning is greppable.
+                    const url = new URL(src, location.href);
+                    url.searchParams.delete("playwrightReload");
+                    return url.href;
+                }
+                catch {
+                    return src;
+                }
+            });
+        }
+        // Re-request errored images, throttled so each retry has time to resolve.
+        if (recoverErroredImages && Date.now() - lastReload > reloadIntervalMs) {
+            lastReload = Date.now();
+            errored.forEach(reload);
+        }
+        await new Promise(resolve => setTimeout(resolve, pollMs));
+    }
+}
+/**
+ * Wait for every visible image to finish decoding.
+ *
+ * See decodeVisibleImages() for how an image is judged loaded, broken, or
+ * merely dimensionless, and how broken ones are re-requested.
+ *
+ * Giving up is not an error: a page that legitimately references a missing
+ * image should still be screenshotted and still have its accessibility checked,
+ * and the screenshot comparison is what fails. But the wait is not silent
+ * either -- the images that never decoded are warned about, so a mysterious
+ * pixel diff (and the timeout's worth of delay before it) has an explanation --
+ * and they are returned so a caller can assert on them.
+ *
+ * @param page
+ * @param timeoutMs How long to wait for images to decode before giving up.
+ * @param recoverErroredImages Whether broken image sources may be rewritten.
+ * @returns The URLs of the images that never decoded. Empty when they all did.
+ */
+async function waitForImagesToDecode(page, timeoutMs = 15000, recoverErroredImages = false) {
+    const undecoded = await page.evaluate(decodeVisibleImages, { timeoutMs, recoverErroredImages });
+    if (undecoded.length > 0) {
+        console.warn(`waitForImagesToDecode: ${undecoded.length} image(s) did not finish loading within ${timeoutMs}ms and may be captured as broken: ${undecoded.join(', ')}`);
+    }
+    return undecoded;
+}

package/lib/index.d.ts

@@ -0,0 +1,13 @@
+export * from './focus.js';
+export * from './accessibility-baseline.js';
+export * from './accessibility-baseline-file.js';
+export * from './accessible-screenshot.js';
+export * from './fonts.js';
+export * from './frames.js';
+export * from './hover.js';
+export * from './images.js';
+export * from './interaction-states.js';
+export * from './pseudo-state.js';
+export * from './videos.js';
+export * from './visualdiff.js';
+export * from './mock/index.js';