@lullabot/playwright-testing 0.1.0

package/lib/accessible-screenshot.js

@@ -0,0 +1,519 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkAccessibility = checkAccessibility;
+exports.takeAccessibleScreenshot = takeAccessibleScreenshot;
+exports.normalizeTarget = normalizeTarget;
+const playwright_1 = __importDefault(require("@axe-core/playwright"));
+const test_1 = require("@playwright/test");
+const images_js_1 = require("./images.js");
+const frames_js_1 = require("./frames.js");
+const fonts_js_1 = require("./fonts.js");
+const videos_js_1 = require("./videos.js");
+const focus_js_1 = require("./focus.js");
+const hover_js_1 = require("./hover.js");
+const interaction_states_js_1 = require("./interaction-states.js");
+const accessibility_baseline_js_1 = require("./accessibility-baseline.js");
+const accessibility_baseline_file_js_1 = require("./accessibility-baseline-file.js");
+let a11yActionHintShown = false;
+/**
+ * Run accessibility checks on the current page using axe-core.
+ *
+ * Runs a best-practice scan (unless bestPracticeMode is 'off') and a WCAG scan,
+ * attaching JSON results and asserting on violations via snapshots.
+ *
+ * @param page The Page fixture from the test.
+ * @param testInfo The testInfo object from the test.
+ * @param options Accessibility options to customise the scan.
+ */
+async function checkAccessibility(page, testInfo, options) {
+    const { wcagTags = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'], exclude = [], bestPracticeExclude = [], wcagExclude = [], bestPracticeMode = 'soft', rules, baseline, screenshotViolations = true, } = options ?? {};
+    if (process.env.CI && !a11yActionHintShown) {
+        console.log('Tip: Use @lullabot/playwright-testing/github to surface accessibility violations in pull requests.');
+        a11yActionHintShown = true;
+    }
+    // Add @a11y annotation (deduplicated).
+    if (!testInfo.annotations.some(a => a.type === '@a11y')) {
+        testInfo.annotations.push({ type: '@a11y' });
+    }
+    if (bestPracticeMode !== 'off') {
+        const bpResults = await runBestPracticeScan(page, testInfo, {
+            exclude: [...exclude, ...bestPracticeExclude],
+            rules,
+        });
+        // Best-practice always uses expect.soft() so the WCAG scan below runs
+        // even when best-practice violations exist. `bestPracticeMode === 'hard'`
+        // is preserved as a marker but does not change soft-vs-hard here.
+        await dispatchAssertion({
+            testInfo,
+            results: bpResults,
+            scan: 'best-practice',
+            expectFn: test_1.expect.soft,
+            scanLabel: 'Best-practice scan',
+        }, baseline);
+    }
+    const wcagScanResults = await runWcagScan(page, testInfo, {
+        wcagTags,
+        exclude: [...exclude, ...wcagExclude],
+        rules,
+    });
+    if (screenshotViolations && wcagScanResults.violations.length > 0) {
+        await screenshotViolatingElements(page, testInfo, wcagScanResults);
+    }
+    await dispatchAssertion({
+        testInfo,
+        results: wcagScanResults,
+        scan: 'wcag',
+        expectFn: test_1.expect,
+        scanLabel: 'WCAG scan',
+    }, baseline);
+}
+/**
+ * Dispatch the assertion for one scan to the correct mode:
+ *
+ * 1. Explicit in-code `baseline` option -> baseline mode (existing behaviour).
+ * 2. A snapshot file already exists on disk for this test -> snapshot mode
+ *    (existing behaviour, preserves all previously committed snapshots).
+ * 3. Playwright is in explicit snapshot-update mode (`all`/`changed`, set via
+ *    `--update-snapshots`) -> snapshot mode (Playwright will create the
+ *    snapshot). `'missing'` is Playwright's default config value and does NOT
+ *    indicate explicit user intent, so it falls through to baseline mode.
+ * 4. Otherwise -> on-disk baseline mode. If the JSON file exists, load and
+ *    match against it. If it does not, seed it. On CI seeding fails the
+ *    test (matching Playwright's missing-snapshot behaviour); locally,
+ *    seeding passes so the first run is green.
+ */
+async function dispatchAssertion(ctx, inCodeBaseline) {
+    if (inCodeBaseline) {
+        return assertBaseline(ctx, inCodeBaseline);
+    }
+    if (await (0, accessibility_baseline_file_js_1.snapshotExists)(ctx.testInfo)) {
+        return assertSnapshot(ctx);
+    }
+    const update = ctx.testInfo.config?.updateSnapshots;
+    if (update === 'all' || update === 'changed') {
+        return assertSnapshot(ctx);
+    }
+    const callCount = (0, accessibility_baseline_file_js_1.nextAccessibilityScanCount)(ctx.testInfo, ctx.scan);
+    const filePath = (0, accessibility_baseline_file_js_1.baselineFilePath)(ctx.testInfo, ctx.scan, callCount);
+    const existing = await (0, accessibility_baseline_file_js_1.readBaselineFile)(filePath);
+    if (existing) {
+        return assertBaseline(ctx, existing.violations);
+    }
+    // Seed and either pass (local) or fail (CI).
+    const normalized = extractNormalizedViolations(ctx.results);
+    const seedViolations = normalized.map(v => ({
+        rule: v.rule,
+        targets: v.targets,
+        reason: 'TODO',
+        willBeFixedIn: 'TODO',
+    }));
+    const seed = (0, accessibility_baseline_file_js_1.buildSeed)(seedViolations);
+    await (0, accessibility_baseline_file_js_1.writeBaselineFile)(filePath, seed);
+    await ctx.testInfo.attach(`a11y-${ctx.scan}-baseline-seed`, {
+        path: filePath,
+        contentType: 'application/json',
+    });
+    if (process.env.CI) {
+        const message = `${ctx.scanLabel}: a11y baseline file was missing for this test. Seeded to ${filePath} — download the attached file from CI artifacts (or re-run locally) and commit it before merging.`;
+        ctx.expectFn(null, message).toBe('a11y baseline file present');
+        return;
+    }
+    ctx.testInfo.annotations.push({
+        type: 'Accessibility',
+        description: seed.violations.length === 0
+            ? `${ctx.scanLabel}: a11y baseline seeded at ${filePath} (no violations).`
+            : `${ctx.scanLabel}: a11y baseline seeded at ${filePath} with ${seed.violations.length} entries — fill in reason/willBeFixedIn before committing.`,
+    });
+    // A local seed is deliberately permissive and contains TODO metadata. The
+    // next run validates the committed file before treating entries as waivers.
+}
+/**
+ * Run the best-practice axe scan, attach results, and return them for
+ * dispatch. The assertion (snapshot vs baseline) is decided by the
+ * dispatcher based on what's already on disk and the `bestPracticeMode`
+ * option drives soft- vs hard-failure behaviour.
+ */
+async function runBestPracticeScan(page, testInfo, opts) {
+    const builder = new playwright_1.default({ page })
+        .withTags(['best-practice']);
+    for (const selector of opts.exclude) {
+        builder.exclude(selector);
+    }
+    if (opts.rules) {
+        builder.options({ rules: opts.rules });
+    }
+    const results = await builder.analyze();
+    await testInfo.attach('a11y-best-practice-scan-results', {
+        body: JSON.stringify(results, null, 2),
+        contentType: 'application/json'
+    });
+    testInfo.annotations.push({
+        type: 'Accessibility',
+        description: `Best-practice scan: ${results.violations.length} violations (${results.passes.length} rules passed)`
+    });
+    return results;
+}
+/**
+ * Run the WCAG axe scan, attach results, and return them for assertion.
+ */
+async function runWcagScan(page, testInfo, opts) {
+    const builder = new playwright_1.default({ page })
+        .withTags(opts.wcagTags);
+    for (const selector of opts.exclude) {
+        builder.exclude(selector);
+    }
+    if (opts.rules) {
+        builder.options({ rules: opts.rules });
+    }
+    const results = await builder.analyze();
+    await testInfo.attach('a11y-wcag-scan-results', {
+        body: JSON.stringify(results, null, 2),
+        contentType: 'application/json'
+    });
+    return results;
+}
+/**
+ * Take a full-page screenshot with violating elements highlighted and
+ * attach it to the test report.
+ */
+async function screenshotViolatingElements(page, testInfo, results) {
+    // Collect all raw CSS selectors from violation nodes.
+    const selectors = results.violations
+        .flatMap(v => v.nodes)
+        .flatMap(n => n.target)
+        .filter((t) => typeof t === 'string');
+    if (selectors.length === 0)
+        return;
+    // Inject highlight outlines on all violating elements.
+    await page.evaluate((sels) => {
+        const style = document.createElement('style');
+        style.setAttribute('data-a11y-highlight', 'true');
+        // Use a CSS rule for each selector so the outline persists even if
+        // elements are repositioned during the screenshot.
+        const rules = sels.map(s => `${s} { outline: 3px solid #e53e3e !important; outline-offset: 2px !important; }`).join('\n');
+        style.textContent = rules;
+        document.head.appendChild(style);
+    }, selectors);
+    try {
+        const screenshot = await page.screenshot({ fullPage: true });
+        await testInfo.attach('a11y-violation-screenshot', {
+            body: screenshot,
+            contentType: 'image/png',
+        });
+    }
+    finally {
+        // Remove the injected styles even if capture or report attachment fails.
+        await page.evaluate(() => {
+            document.querySelector('style[data-a11y-highlight]')?.remove();
+        });
+    }
+}
+/**
+ * Assert violations against a baseline allowlist (in-code or on-disk).
+ */
+function assertBaseline(ctx, baseline) {
+    (0, accessibility_baseline_js_1.validateAccessibilityBaseline)(baseline);
+    const { testInfo, results, scanLabel, expectFn } = ctx;
+    const allViolations = extractNormalizedViolations(results);
+    const matchedBaselineIndices = new Set();
+    const unmatchedViolations = [];
+    for (const violation of allViolations) {
+        const baselineIndex = baseline.findIndex((entry) => {
+            if (entry.rule !== violation.rule)
+                return false;
+            // Check for at least one overlapping normalized target.
+            return entry.targets.some(baselineTarget => violation.targets.some(violationTarget => violationTarget === baselineTarget));
+        });
+        if (baselineIndex >= 0) {
+            matchedBaselineIndices.add(baselineIndex);
+            const entry = baseline[baselineIndex];
+            testInfo.annotations.push({
+                type: 'Baselined a11y violation',
+                description: `${entry.rule}: ${entry.reason} — ${entry.willBeFixedIn}`,
+            });
+        }
+        else {
+            unmatchedViolations.push(violation);
+        }
+    }
+    // Report stale baseline entries.
+    baseline.forEach((entry, idx) => {
+        if (!matchedBaselineIndices.has(idx)) {
+            testInfo.annotations.push({
+                type: 'Stale a11y baseline entry',
+                description: `${entry.rule} on ${entry.targets.join(', ')} — no longer detected`,
+            });
+        }
+    });
+    // Summary annotation for baseline mode.
+    const baselinedCount = matchedBaselineIndices.size;
+    testInfo.annotations.push({
+        type: 'Accessibility',
+        description: `${scanLabel}: ${unmatchedViolations.length} new violations (${baselinedCount} baselined)`,
+    });
+    // Fail on unmatched violations with detailed output.
+    if (unmatchedViolations.length > 0) {
+        const details = formatViolationDetails(results, unmatchedViolations);
+        expectFn(null, details).toBe('no accessibility violations');
+    }
+}
+/**
+ * Assert via snapshot comparison (legacy mode for tests with committed snapshots).
+ */
+async function assertSnapshot(ctx) {
+    const { testInfo, results, scan, expectFn } = ctx;
+    // Match the legacy summary annotation phrasing for WCAG; best-practice's
+    // pre-existing summary annotation is emitted in runBestPracticeScan.
+    if (scan === 'wcag') {
+        testInfo.annotations.push({
+            type: 'Accessibility',
+            description: `WCAG scan: ${results.violations.length} violations (${results.passes.length} rules passed)`
+        });
+        // If there are violations, attach baseline suggestions and push annotation.
+        if (results.violations.length > 0) {
+            const allViolations = extractNormalizedViolations(results);
+            const suggestions = allViolations.map(v => formatBaselineSuggestion(v)).join('\n');
+            await testInfo.attach('a11y-baseline-suggestions', {
+                body: suggestions,
+                contentType: 'text/plain',
+            });
+            testInfo.annotations.push({
+                type: 'Accessibility',
+                description: 'To manage violations explicitly, switch to baseline mode. See a11y-baseline-suggestions attachment.',
+            });
+        }
+    }
+    return expectFn(violationFingerprints(results)).toMatchSnapshot();
+}
+/**
+ * Take a visual comparison, and also ensure there's no accessibility issues.
+ *
+ * @param page The Page fixture from the test.
+ * @param testInfo The testInfo object from the test.
+ * @param options Screenshot options from toHaveScreenshot().
+ * @param scrollLocator A locator to ensure is visible before taking the screenshot.
+ * @param locator A specific locator to take the screenshot of. aXe still checks the whole page.
+ */
+async function takeAccessibleScreenshot(page, testInfo, options, scrollLocator, locator) {
+    const screenshotOptions = options ?? {};
+    if (screenshotOptions.clipLocator && (screenshotOptions.clip || (locator && locator !== page))) {
+        throw new Error('clipLocator cannot be combined with clip or a locator screenshot target.');
+    }
+    if (screenshotOptions.clipLocator && screenshotOptions.clipLocator.page() !== page) {
+        throw new Error('clipLocator must belong to the screenshot page.');
+    }
+    // The default is 5 seconds. However, even on a fast machine it can take
+    // longer than 5 seconds for large pages like node forms to stabilize. This
+    // doesn't affect end users because the page still being rendered is
+    // typically below the viewport, and it's loaded by the time they scroll.
+    // So, we set this to at least 10 seconds, unless it's already larger.
+    // To test changing this, try running this command and see if it times out:
+    const interactionStates = screenshotOptions.interactionStates ?? [];
+    (0, interaction_states_js_1.validateInteractionStates)(interactionStates);
+    // Do not pass package-specific orchestration options to Playwright's matcher.
+    const { clipLocator: _clipLocator, accessibility: _accessibility, blur: _blur, clearHover: _clearHover, interactionStates: _interactionStates, stabilization, ...nativeScreenshotOptions } = screenshotOptions;
+    const playwrightScreenshotOptions = {
+        ...nativeScreenshotOptions,
+        timeout: Math.max(nativeScreenshotOptions.timeout ?? 0, 10000),
+    };
+    // Blur any focused element so a stray focus ring does not make the screenshot
+    // non-deterministic, unless the caller is intentionally capturing focus. Do
+    // this before the load/stability waits so that any layout change a blur
+    // handler triggers (a closing dropdown, injected validation markup) settles
+    // before we capture.
+    if (screenshotOptions.blur !== false) {
+        await (0, focus_js_1.blurActiveElement)(page);
+    }
+    let removeHoverShield = screenshotOptions.clearHover === false ? undefined : await (0, hover_js_1.clearHover)(page);
+    let videoPlaybackRestored = false;
+    let cleanupInteractionStates;
+    try {
+        await (0, frames_js_1.waitForFrames)(page);
+        // Loading lazy frames can scroll the page. Load images afterwards so that
+        // any images exposed by that scrolling are settled and waitForAllImages()
+        // restores the viewport to the top before capture.
+        await (0, images_js_1.waitForAllImages)(page, stabilization?.images);
+        await (0, fonts_js_1.waitForFonts)(page);
+        // Last of the waits, so the video frames it composites are as fresh as
+        // possible when the capture happens. It restores the scroll position it
+        // found, so it does not disturb where the waits above leave the page.
+        await (0, videos_js_1.waitForVideos)(page, stabilization?.videos);
+        if (scrollLocator) {
+            await scrollLocator.scrollIntoViewIfNeeded();
+        }
+        // A hover action cannot hit its target through the transparent shield used
+        // to clear incidental hover. Remove it only after all stability waits, then
+        // apply real hover before real focus so focusing cannot disturb the pointer.
+        const hasHover = interactionStates.some(({ states }) => states.includes('hover'));
+        if (hasHover) {
+            await removeHoverShield?.();
+            removeHoverShield = undefined;
+        }
+        if (interactionStates.length > 0) {
+            cleanupInteractionStates = await (0, interaction_states_js_1.applyInteractionStates)(interactionStates, {
+                clearHover: async () => {
+                    const removeInteractionShield = await (0, hover_js_1.clearHover)(page);
+                    await removeInteractionShield();
+                },
+            });
+        }
+        let locatorToScreenshot = page;
+        if (locator) {
+            locatorToScreenshot = locator;
+        }
+        if (screenshotOptions.clipLocator) {
+            await screenshotOptions.clipLocator.scrollIntoViewIfNeeded();
+            // Scrolling can expose lazy content. Await fonts and two paint frames
+            // before measuring; the existing waits have already loaded page media.
+            await (0, fonts_js_1.waitForFonts)(page);
+            await page.evaluate(() => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(() => resolve()))));
+            const bounds = await screenshotOptions.clipLocator.boundingBox();
+            if (!bounds)
+                throw new Error('clipLocator has no visible bounding box.');
+            // boundingBox is in main-frame viewport coordinates, including for
+            // locators inside frames. Read scroll offsets from the main page.
+            const geometry = await page.evaluate(() => ({
+                x: window.scrollX, y: window.scrollY,
+                width: window.innerWidth, height: window.innerHeight,
+            }));
+            const clip = {
+                x: Math.round(bounds.x + (screenshotOptions.fullPage ? geometry.x : 0)),
+                y: Math.round(bounds.y + (screenshotOptions.fullPage ? geometry.y : 0)),
+                width: Math.round(bounds.width),
+                height: Math.round(bounds.height),
+            };
+            if (clip.width <= 0 || clip.height <= 0) {
+                throw new Error('clipLocator must have positive rounded dimensions.');
+            }
+            if (!screenshotOptions.fullPage && (clip.x < 0 || clip.y < 0 || clip.x + clip.width > geometry.width || clip.y + clip.height > geometry.height)) {
+                throw new Error('clipLocator does not fit in the viewport; use fullPage: true to capture the whole target.');
+            }
+            if (clip.x < 0 || clip.y < 0) {
+                throw new Error('clipLocator must have non-negative document coordinates.');
+            }
+            playwrightScreenshotOptions.clip = clip;
+        }
+        // Soft failure here so we can get accessibility violations too.
+        await test_1.expect.soft(locatorToScreenshot).toHaveScreenshot(playwrightScreenshotOptions);
+        // Settling a video pauses it, clears `autoplay` and rewinds it. That is only
+        // wanted for the duration of the capture: a test that screenshots a page and
+        // then asserts that a video is playing should still pass.
+        await (0, videos_js_1.restoreVideoPlayback)(page);
+        videoPlaybackRestored = true;
+        await removeHoverShield?.();
+        removeHoverShield = undefined;
+        return await checkAccessibility(page, testInfo, screenshotOptions.accessibility);
+    }
+    finally {
+        // Nest cleanup so a failure in one operation cannot prevent the remaining
+        // browser state from being restored.
+        try {
+            await removeHoverShield?.();
+        }
+        finally {
+            try {
+                if (!videoPlaybackRestored) {
+                    await (0, videos_js_1.restoreVideoPlayback)(page);
+                }
+            }
+            finally {
+                await cleanupInteractionStates?.();
+            }
+        }
+    }
+}
+/**
+ * Normalize a single CSS selector target for stable comparison.
+ *
+ * Replaces unique numeric HTML IDs and aria-labelledby suffixes with
+ * a stable placeholder so that snapshots and baseline matching are
+ * deterministic across runs.
+ */
+function normalizeTarget(target) {
+    const uniqueHtmlID = /(#[^#]*)--\d+/;
+    const ariaLabelledById = /(aria-labelledby="[^"]+)--\d+"/;
+    if (typeof target === 'string') {
+        return target
+            .replace(uniqueHtmlID, '$1--UNIQUE-ID')
+            .replace(ariaLabelledById, '$1--UNIQUE-ID"');
+    }
+    return target;
+}
+/**
+ * Extract violations from axe results and normalize their targets into
+ * flat, deduplicated CSS selector strings.
+ */
+function extractNormalizedViolations(results) {
+    return results.violations.map(violation => {
+        const flatTargets = [];
+        for (const node of violation.nodes) {
+            for (const target of node.target) {
+                const normalized = normalizeTarget(target);
+                const str = typeof normalized === 'string' ? normalized : normalized.join(' ');
+                if (!flatTargets.includes(str)) {
+                    flatTargets.push(str);
+                }
+            }
+        }
+        return {
+            rule: violation.id,
+            targets: flatTargets,
+            description: violation.description,
+            impact: violation.impact ?? 'unknown',
+            helpUrl: violation.helpUrl,
+        };
+    });
+}
+/**
+ * Format a single violation as a copy-pasteable baseline entry.
+ */
+function formatBaselineSuggestion(violation) {
+    const targetsStr = violation.targets.map(t => `'${t}'`).join(', ');
+    return `{
+  rule: '${violation.rule}',
+  targets: [${targetsStr}],
+  reason: '',  // TODO: explain why this is accepted
+  willBeFixedIn: '',  // TODO: link to tracking ticket
+},`;
+}
+/**
+ * Format detailed failure output for unmatched violations, including
+ * copy-pasteable baseline entries.
+ */
+function formatViolationDetails(results, violations) {
+    const lines = [];
+    for (const v of violations) {
+        const targetsStr = JSON.stringify(v.targets);
+        lines.push(`Accessibility violation (${v.impact}): ${v.rule}`);
+        lines.push(`  ${v.description}`);
+        lines.push(`  Help: ${v.helpUrl}`);
+        lines.push(`  Targets: ${targetsStr}`);
+        lines.push('');
+        lines.push('  Add to your baseline to accept this violation:');
+        lines.push('  ' + formatBaselineSuggestion(v).split('\n').join('\n  '));
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/**
+ * Filter violations down to stable elements.
+ *
+ * If we try to create a snapshot of the entire report, it will fail on random
+ * unique HTML IDs.
+ *
+ * @param accessibilityScanResults
+ */
+function violationFingerprints(accessibilityScanResults) {
+    const violationFps = accessibilityScanResults.violations.map(violation => ({
+        rule: violation.id,
+        // These are CSS selectors which uniquely identify each element with
+        // a violation of the rule in question.
+        targets: violation.nodes.map(node => node.target.map((target) => {
+            return normalizeTarget(target);
+        })),
+    }));
+    return JSON.stringify(violationFps, null, 2);
+}

package/lib/focus.d.ts

@@ -0,0 +1,14 @@
+import { Page } from "@playwright/test";
+/**
+ * Remove keyboard focus from the active element.
+ *
+ * A focused form control paints a focus outline/ring. Whether an element still
+ * has focus when the screenshot is taken depends on test timing, so that ring
+ * appears in some runs and not others, producing a visual diff that is invisible
+ * to a human but trips the strict pixel budget. Blurring the active element
+ * first makes the focus state deterministic.
+ *
+ * @param page
+ * @returns `true` if an element was blurred, `false` if nothing was focused.
+ */
+export declare function blurActiveElement(page: Page): Promise<boolean>;

package/lib/focus.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blurActiveElement = blurActiveElement;
+/**
+ * Remove keyboard focus from the active element.
+ *
+ * A focused form control paints a focus outline/ring. Whether an element still
+ * has focus when the screenshot is taken depends on test timing, so that ring
+ * appears in some runs and not others, producing a visual diff that is invisible
+ * to a human but trips the strict pixel budget. Blurring the active element
+ * first makes the focus state deterministic.
+ *
+ * @param page
+ * @returns `true` if an element was blurred, `false` if nothing was focused.
+ */
+async function blurActiveElement(page) {
+    return page.evaluate(() => {
+        const el = document.activeElement;
+        // `document.activeElement` falls back to `<body>`/`<html>` when nothing is
+        // focused. Blurring that paints no focus ring but can still fire `focusout`
+        // handlers, so skip it and only blur a genuinely focused control.
+        if (!el || el === document.body || el === document.documentElement || typeof el.blur !== "function") {
+            return false;
+        }
+        el.blur();
+        return true;
+    });
+}

package/lib/fonts.d.ts

@@ -0,0 +1,18 @@
+import { Page } from "@playwright/test";
+/**
+ * Wait for all web fonts to finish loading.
+ *
+ * Visual snapshots can flake when text is first painted with fallback font
+ * metrics before the web fonts finish loading. The fallback glyphs have
+ * different widths, so text wraps onto a different number of lines and the page
+ * renders at a slightly different height than it does once the real fonts are
+ * applied. By the time Playwright retries the layout has settled, which is why
+ * these failures usually only show up on the first attempt.
+ *
+ * Awaiting `document.fonts.ready` blocks until every font face the page has
+ * requested has finished loading (or failed), so the screenshot always captures
+ * the settled, web-font layout.
+ *
+ * @param page
+ */
+export declare function waitForFonts(page: Page): Promise<void>;

package/lib/fonts.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitForFonts = waitForFonts;
+/**
+ * Wait for all web fonts to finish loading.
+ *
+ * Visual snapshots can flake when text is first painted with fallback font
+ * metrics before the web fonts finish loading. The fallback glyphs have
+ * different widths, so text wraps onto a different number of lines and the page
+ * renders at a slightly different height than it does once the real fonts are
+ * applied. By the time Playwright retries the layout has settled, which is why
+ * these failures usually only show up on the first attempt.
+ *
+ * Awaiting `document.fonts.ready` blocks until every font face the page has
+ * requested has finished loading (or failed), so the screenshot always captures
+ * the settled, web-font layout.
+ *
+ * @param page
+ */
+async function waitForFonts(page) {
+    await page.evaluate(async () => {
+        await document.fonts.ready;
+    });
+}

package/lib/frames.d.ts

@@ -0,0 +1,7 @@
+import { Page } from "@playwright/test";
+/**
+ * Wait for all frames to load.
+ *
+ * @param page
+ */
+export declare function waitForFrames(page: Page): Promise<void>;

package/lib/frames.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitForFrames = waitForFrames;
+/**
+ * Wait for all frames to load.
+ *
+ * @param page
+ */
+async function waitForFrames(page) {
+    const locators = await page.locator('iframe');
+    // Trigger lazy-loading iframes. Since this should be fast, and we don't want to
+    // have to deal with concurrency bugs, we do this in serial.
+    for (const locator of await locators.all()) {
+        // Ensure iframes are connected to the DOM before trying to scroll to them.
+        // https://github.com/microsoft/playwright/issues/23758
+        if (await locator.evaluate(iframe => iframe.isConnected)) {
+            if (await locator.isVisible()) {
+                await locator.scrollIntoViewIfNeeded();
+                await locator.scrollIntoViewIfNeeded();
+                const element = await locator.elementHandle();
+                const frame = await element?.contentFrame();
+                await frame?.waitForURL(new RegExp('.*/.*', 'i'));
+                await frame?.waitForLoadState('load');
+            }
+        }
+    }
+}