@lullabot/playwright-testing 1.0.0 → 1.1.0

package/lib/accessible-screenshot.js

@@ -29,16 +29,19 @@ let a11yActionHintShown = false;
  * @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 ?? {};
+    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.');
+        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 (!testInfo.annotations.some((a) => a.type === "@a11y")) {
+        testInfo.annotations.push({ type: "@a11y" });
     }
-    if (bestPracticeMode !== 'off') {
+    // An in-code baseline is shared by both scans. Track matches across this
+    // check so that a rule detected by either scan is not reported as stale.
+    const sharedBaselineMatches = new Set();
+    if (bestPracticeMode !== "off") {
         const bpResults = await runBestPracticeScan(page, testInfo, {
             exclude: [...exclude, ...bestPracticeExclude],
             rules,
@@ -49,10 +52,10 @@ async function checkAccessibility(page, testInfo, options) {
         await dispatchAssertion({
             testInfo,
             results: bpResults,
-            scan: 'best-practice',
+            scan: "best-practice",
             expectFn: test_1.expect.soft,
-            scanLabel: 'Best-practice scan',
-        }, baseline);
+            scanLabel: "Best-practice scan",
+        }, baseline, sharedBaselineMatches);
     }
     const wcagScanResults = await runWcagScan(page, testInfo, {
         wcagTags,
@@ -65,10 +68,10 @@ async function checkAccessibility(page, testInfo, options) {
     await dispatchAssertion({
         testInfo,
         results: wcagScanResults,
-        scan: 'wcag',
+        scan: "wcag",
         expectFn: test_1.expect,
-        scanLabel: 'WCAG scan',
-    }, baseline);
+        scanLabel: "WCAG scan",
+    }, baseline, sharedBaselineMatches);
 }
 /**
  * Dispatch the assertion for one scan to the correct mode:
@@ -85,15 +88,15 @@ async function checkAccessibility(page, testInfo, options) {
  *    test (matching Playwright's missing-snapshot behaviour); locally,
  *    seeding passes so the first run is green.
  */
-async function dispatchAssertion(ctx, inCodeBaseline) {
+async function dispatchAssertion(ctx, inCodeBaseline, sharedBaselineMatches) {
     if (inCodeBaseline) {
-        return assertBaseline(ctx, inCodeBaseline);
+        return assertBaseline(ctx, inCodeBaseline, sharedBaselineMatches);
     }
     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') {
+    if (update === "all" || update === "changed") {
         return assertSnapshot(ctx);
     }
     const callCount = (0, accessibility_baseline_file_js_1.nextAccessibilityScanCount)(ctx.testInfo, ctx.scan);
@@ -104,25 +107,25 @@ async function dispatchAssertion(ctx, inCodeBaseline) {
     }
     // Seed and either pass (local) or fail (CI).
     const normalized = extractNormalizedViolations(ctx.results);
-    const seedViolations = normalized.map(v => ({
+    const seedViolations = normalized.map((v) => ({
         rule: v.rule,
         targets: v.targets,
-        reason: 'TODO',
-        willBeFixedIn: 'TODO',
+        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',
+        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');
+        ctx.expectFn(null, message).toBe("a11y baseline file present");
         return;
     }
     ctx.testInfo.annotations.push({
-        type: 'Accessibility',
+        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.`,
@@ -137,8 +140,7 @@ async function dispatchAssertion(ctx, inCodeBaseline) {
  * option drives soft- vs hard-failure behaviour.
  */
 async function runBestPracticeScan(page, testInfo, opts) {
-    const builder = new playwright_1.default({ page })
-        .withTags(['best-practice']);
+    const builder = new playwright_1.default({ page }).withTags(["best-practice"]);
     for (const selector of opts.exclude) {
         builder.exclude(selector);
     }
@@ -146,13 +148,13 @@ async function runBestPracticeScan(page, testInfo, opts) {
         builder.options({ rules: opts.rules });
     }
     const results = await builder.analyze();
-    await testInfo.attach('a11y-best-practice-scan-results', {
+    await testInfo.attach("a11y-best-practice-scan-results", {
         body: JSON.stringify(results, null, 2),
-        contentType: 'application/json'
+        contentType: "application/json",
     });
     testInfo.annotations.push({
-        type: 'Accessibility',
-        description: `Best-practice scan: ${results.violations.length} violations (${results.passes.length} rules passed)`
+        type: "Accessibility",
+        description: `Best-practice scan: ${results.violations.length} violations (${results.passes.length} rules passed)`,
     });
     return results;
 }
@@ -160,8 +162,7 @@ async function runBestPracticeScan(page, testInfo, opts) {
  * 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);
+    const builder = new playwright_1.default({ page }).withTags(opts.wcagTags);
     for (const selector of opts.exclude) {
         builder.exclude(selector);
     }
@@ -169,9 +170,9 @@ async function runWcagScan(page, testInfo, opts) {
         builder.options({ rules: opts.rules });
     }
     const results = await builder.analyze();
-    await testInfo.attach('a11y-wcag-scan-results', {
+    await testInfo.attach("a11y-wcag-scan-results", {
         body: JSON.stringify(results, null, 2),
-        contentType: 'application/json'
+        contentType: "application/json",
     });
     return results;
 }
@@ -182,39 +183,41 @@ async function runWcagScan(page, testInfo, opts) {
 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');
+        .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');
+        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');
+        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', {
+        await testInfo.attach("a11y-violation-screenshot", {
             body: screenshot,
-            contentType: 'image/png',
+            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();
+            document.querySelector("style[data-a11y-highlight]")?.remove();
         });
     }
 }
 /**
  * Assert violations against a baseline allowlist (in-code or on-disk).
  */
-function assertBaseline(ctx, baseline) {
+function assertBaseline(ctx, baseline, sharedBaselineMatches) {
     (0, accessibility_baseline_js_1.validateAccessibilityBaseline)(baseline);
     const { testInfo, results, scanLabel, expectFn } = ctx;
     const allViolations = extractNormalizedViolations(results);
@@ -225,13 +228,14 @@ function assertBaseline(ctx, baseline) {
             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));
+            return entry.targets.some((baselineTarget) => violation.targets.some((violationTarget) => violationTarget === baselineTarget));
         });
         if (baselineIndex >= 0) {
             matchedBaselineIndices.add(baselineIndex);
+            sharedBaselineMatches?.add(baselineIndex);
             const entry = baseline[baselineIndex];
             testInfo.annotations.push({
-                type: 'Baselined a11y violation',
+                type: "Baselined a11y violation",
                 description: `${entry.rule}: ${entry.reason} — ${entry.willBeFixedIn}`,
             });
         }
@@ -239,25 +243,31 @@ function assertBaseline(ctx, baseline) {
             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`,
-            });
-        }
-    });
+    // The WCAG scan always runs last, even when best-practice is disabled.
+    // Report shared entries once after both scans have contributed matches,
+    // before the hard assertion can throw. On-disk baselines belong to one
+    // scan and continue to report stale entries independently.
+    if (!sharedBaselineMatches || ctx.scan === "wcag") {
+        const matches = sharedBaselineMatches ?? matchedBaselineIndices;
+        baseline.forEach((entry, idx) => {
+            if (!matches.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',
+        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');
+        expectFn(null, details).toBe("no accessibility violations");
     }
 }
 /**
@@ -267,22 +277,24 @@ 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') {
+    if (scan === "wcag") {
         testInfo.annotations.push({
-            type: 'Accessibility',
-            description: `WCAG scan: ${results.violations.length} violations (${results.passes.length} rules passed)`
+            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', {
+            const suggestions = allViolations
+                .map((v) => formatBaselineSuggestion(v))
+                .join("\n");
+            await testInfo.attach("a11y-baseline-suggestions", {
                 body: suggestions,
-                contentType: 'text/plain',
+                contentType: "text/plain",
             });
             testInfo.annotations.push({
-                type: 'Accessibility',
-                description: 'To manage violations explicitly, switch to baseline mode. See a11y-baseline-suggestions attachment.',
+                type: "Accessibility",
+                description: "To manage violations explicitly, switch to baseline mode. See a11y-baseline-suggestions attachment.",
             });
         }
     }
@@ -299,11 +311,13 @@ async function assertSnapshot(ctx) {
  */
 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.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.');
+    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
@@ -347,7 +361,7 @@ async function takeAccessibleScreenshot(page, testInfo, options, scrollLocator,
         // 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'));
+        const hasHover = interactionStates.some(({ states }) => states.includes("hover"));
         if (hasHover) {
             await removeHoverShield?.();
             removeHoverShield = undefined;
@@ -369,15 +383,17 @@ async function takeAccessibleScreenshot(page, testInfo, options, scrollLocator,
             // 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()))));
+            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.');
+                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,
+                x: window.scrollX,
+                y: window.scrollY,
+                width: window.innerWidth,
+                height: window.innerHeight,
             }));
             const clip = {
                 x: Math.round(bounds.x + (screenshotOptions.fullPage ? geometry.x : 0)),
@@ -386,18 +402,24 @@ async function takeAccessibleScreenshot(page, testInfo, options, scrollLocator,
                 height: Math.round(bounds.height),
             };
             if (clip.width <= 0 || clip.height <= 0) {
-                throw new Error('clipLocator must have positive rounded dimensions.');
+                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 (!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.');
+                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);
+        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.
@@ -435,9 +457,9 @@ async function takeAccessibleScreenshot(page, testInfo, options, scrollLocator,
 function normalizeTarget(target) {
     const uniqueHtmlID = /(#[^#]*)--\d+/;
     const ariaLabelledById = /(aria-labelledby="[^"]+)--\d+"/;
-    if (typeof target === 'string') {
+    if (typeof target === "string") {
         return target
-            .replace(uniqueHtmlID, '$1--UNIQUE-ID')
+            .replace(uniqueHtmlID, "$1--UNIQUE-ID")
             .replace(ariaLabelledById, '$1--UNIQUE-ID"');
     }
     return target;
@@ -447,12 +469,12 @@ function normalizeTarget(target) {
  * flat, deduplicated CSS selector strings.
  */
 function extractNormalizedViolations(results) {
-    return results.violations.map(violation => {
+    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(' ');
+                const str = typeof normalized === "string" ? normalized : normalized.join(" ");
                 if (!flatTargets.includes(str)) {
                     flatTargets.push(str);
                 }
@@ -462,7 +484,7 @@ function extractNormalizedViolations(results) {
             rule: violation.id,
             targets: flatTargets,
             description: violation.description,
-            impact: violation.impact ?? 'unknown',
+            impact: violation.impact ?? "unknown",
             helpUrl: violation.helpUrl,
         };
     });
@@ -471,7 +493,7 @@ function extractNormalizedViolations(results) {
  * Format a single violation as a copy-pasteable baseline entry.
  */
 function formatBaselineSuggestion(violation) {
-    const targetsStr = violation.targets.map(t => `'${t}'`).join(', ');
+    const targetsStr = violation.targets.map((t) => `'${t}'`).join(", ");
     return `{
   rule: '${violation.rule}',
   targets: [${targetsStr}],
@@ -491,12 +513,12 @@ function formatViolationDetails(results, violations) {
         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('');
+        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');
+    return lines.join("\n");
 }
 /**
  * Filter violations down to stable elements.
@@ -507,11 +529,11 @@ function formatViolationDetails(results, violations) {
  * @param accessibilityScanResults
  */
 function violationFingerprints(accessibilityScanResults) {
-    const violationFps = accessibilityScanResults.violations.map(violation => ({
+    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) => {
+        targets: violation.nodes.map((node) => node.target.map((target) => {
             return normalizeTarget(target);
         })),
     }));

package/lib/focus.js

@@ -19,7 +19,10 @@ async function blurActiveElement(page) {
         // `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") {
+        if (!el ||
+            el === document.body ||
+            el === document.documentElement ||
+            typeof el.blur !== "function") {
             return false;
         }
         el.blur();

package/lib/frames.js

@@ -7,20 +7,20 @@ exports.waitForFrames = waitForFrames;
  * @param page
  */
 async function waitForFrames(page) {
-    const locators = await page.locator('iframe');
+    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.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');
+                await frame?.waitForURL(new RegExp(".*/.*", "i"));
+                await frame?.waitForLoadState("load");
             }
         }
     }