snap-ally 0.1.1-beta → 0.2.1-beta

package/dist/A11yAuditOverlay.d.ts

@@ -1,42 +1,71 @@
 import { Page, TestInfo } from '@playwright/test';
-export interface AuditAnnotation {
-    type: string;
-    description: string;
-    keyPage: string;
-}
 /**
  * Handles visual feedback and Playwright annotations during an accessibility audit.
+ *
+ * Responsibilities:
+ * - Rendering violation banners and element highlights via a Shadow DOM overlay
+ * - Capturing screenshots and attaching them to the Playwright test report
+ *
+ * All DOM mutations are isolated inside a Shadow DOM root to avoid
+ * interfering with the page under test.
  */
 export declare class A11yAuditOverlay {
-    protected page: Page;
-    protected keyPage: string;
+    private readonly page;
     private readonly overlayRootId;
-    private auditAnnotations;
-    constructor(page: Page, keyPage: string);
-    reset(): void;
+    /** IDs for elements created inside the shadow root. */
+    private static readonly BANNER_ID;
+    private static readonly HIGHLIGHT_ID;
+    constructor(page: Page);
     /**
      * Shows a compact, modern banner at the bottom of the page describing the violation.
+     *
+     * @param violation - Object containing the Axe rule `id` and human-readable `help` text.
+     * @param color     - CSS colour used as the banner background (rgb/rgba/hex).
      */
     showViolationOverlay(violation: {
         id: string;
         help: string;
     }, color: string): Promise<void>;
     /**
-     * Removes the violation description overlay.
+     * Removes the violation description banner from the page.
      */
     hideViolationOverlay(): Promise<void>;
     /**
-     * Attaches accessibility data to the Playwright test report.
+     * Draws a glowing highlight border around the element matching `selector`.
+     *
+     * The element is scrolled into view first so that the highlight coordinates
+     * are accurate after any layout shift.
+     *
+     * @param selector - A CSS selector that uniquely identifies the target element.
+     * @param color    - CSS colour for the highlight border and glow.
+     */
+    highlightElement(selector: string, color: string): Promise<void>;
+    /**
+     * Removes the element highlight from the page.
+     */
+    unhighlightElement(): Promise<void>;
+    /**
+     * Attaches arbitrary data to the Playwright test report.
+     *
+     * @param testInfo    - The current Playwright `TestInfo` instance.
+     * @param name        - Attachment name shown in the report.
+     * @param description - Content to attach (serialised as JSON by the caller).
      */
     addTestAttachment(testInfo: TestInfo, name: string, description: string): Promise<void>;
-    getAuditAnnotations(): AuditAnnotation[];
     /**
-     * Captures a screenshot and attaches it to the test report.
+     * Captures a viewport screenshot and attaches it to the test report.
+     *
+     * The screenshot uses `fullPage: false` (viewport only) to avoid browser
+     * resizing flashes that can occur with full-page captures.
+     *
+     * @param fileName - Name for the attachment in the test report.
+     * @param testInfo - The current Playwright `TestInfo` instance.
+     * @returns The raw screenshot buffer.
      */
     captureAndAttachScreenshot(fileName: string, testInfo: TestInfo): Promise<Buffer>;
-    highlightElement(selector: string, color: string): Promise<void>;
     /**
-     * Removes highlighting from an element.
+     * Wrapper around `page.evaluate` that silently swallows errors caused by
+     * the page or browser closing mid-evaluation (e.g. navigation, test teardown).
      */
-    unhighlightElement(): Promise<void>;
+    private safeEvaluate;
 }

package/dist/A11yAuditOverlay.js

@@ -4,37 +4,58 @@ exports.A11yAuditOverlay = void 0;
 const test_1 = require("@playwright/test");
 /**
  * Handles visual feedback and Playwright annotations during an accessibility audit.
+ *
+ * Responsibilities:
+ * - Rendering violation banners and element highlights via a Shadow DOM overlay
+ * - Capturing screenshots and attaching them to the Playwright test report
+ *
+ * All DOM mutations are isolated inside a Shadow DOM root to avoid
+ * interfering with the page under test.
  */
 class A11yAuditOverlay {
-    constructor(page, keyPage) {
+    constructor(page) {
         this.page = page;
-        this.keyPage = keyPage;
         this.overlayRootId = 'a11y-audit-overlay-root';
-        this.auditAnnotations = [];
-    }
-    reset() {
-        this.auditAnnotations = [];
     }
+    // ──────────────────────────────────────────────
+    //  Violation banner
+    // ──────────────────────────────────────────────
     /**
      * Shows a compact, modern banner at the bottom of the page describing the violation.
+     *
+     * @param violation - Object containing the Axe rule `id` and human-readable `help` text.
+     * @param color     - CSS colour used as the banner background (rgb/rgba/hex).
      */
     async showViolationOverlay(violation, color) {
-        await this.page.evaluate(([v, color, rootId]) => {
-            let root = document.getElementById(rootId);
-            if (!root) {
-                root = document.createElement('div');
-                root.id = rootId;
-                root.style.cssText =
-                    'position: absolute; top: 0; left: 0; width: 0; height: 0; z-index: 2147483647;';
-                document.body.appendChild(root);
-                root.attachShadow({ mode: 'open' });
-            }
-            const shadow = root.shadowRoot;
-            let container = shadow.getElementById('a11y-banner');
+        await this.safeEvaluate(([v, rawColor, rootId, bannerId]) => {
+            // --- helpers scoped to the browser context ---
+            const toAlphaColor = (c, alpha = 0.85) => {
+                if (c.includes('rgba'))
+                    return c;
+                if (c.includes('rgb'))
+                    return c.replace('rgb', 'rgba').replace(')', `, ${alpha})`);
+                // Hex – append alpha byte (0xD9 ≈ 0.85)
+                return `${c}D9`;
+            };
+            const getOrCreateRoot = (id) => {
+                let root = document.getElementById(id);
+                if (!root) {
+                    root = document.createElement('div');
+                    root.id = id;
+                    root.style.cssText =
+                        'position:absolute;top:0;left:0;width:0;height:0;z-index:2147483647;';
+                    document.body.appendChild(root);
+                    root.attachShadow({ mode: 'open' });
+                }
+                return root.shadowRoot;
+            };
+            // --- main logic ---
+            const shadow = getOrCreateRoot(rootId);
+            let container = shadow.getElementById(bannerId);
             if (!container) {
                 const style = document.createElement('style');
                 style.textContent = `
-                        #a11y-banner {
+                        #${bannerId} {
                             position: fixed;
                             left: 50%;
                             bottom: 24px;
@@ -56,7 +77,7 @@ class A11yAuditOverlay {
                             z-index: 10000;
                         }
                         .badge {
-                            background: rgba(255, 255, 255, 0.2);
+                            background: rgba(255,255,255,0.2);
                             padding: 2px 8px;
                             border-radius: 6px;
                             font-size: 11px;
@@ -74,126 +95,208 @@ class A11yAuditOverlay {
                     `;
                 shadow.appendChild(style);
                 container = document.createElement('div');
-                container.id = 'a11y-banner';
+                container.id = bannerId;
                 shadow.appendChild(container);
             }
-            const alphaColor = color.includes('rgba')
-                ? color
-                : color.includes('rgb')
-                    ? color.replace('rgb', 'rgba').replace(')', ', 0.85)')
-                    : color + 'E6';
-            container.style.backgroundColor = alphaColor;
-            container.innerHTML = `
-                    <div style="font-size: 20px;">⚠️</div>
-                    <div class="content">
-                        <div style="margin-bottom: 4px; display: flex; align-items: center; gap: 8px;">
-                            <span class="badge">${v.id}</span>
-                            <span style="opacity: 0.9;">${v.help}</span>
-                        </div>
-                    </div>
-                `;
-        }, [violation, color, this.overlayRootId]);
+            container.style.backgroundColor = toAlphaColor(rawColor);
+            // Build DOM nodes instead of innerHTML to prevent XSS
+            container.textContent = ''; // clear previous content
+            const icon = document.createElement('div');
+            icon.style.fontSize = '20px';
+            icon.textContent = '⚠️';
+            const badge = document.createElement('span');
+            badge.className = 'badge';
+            badge.textContent = v.id;
+            const helpText = document.createElement('span');
+            helpText.style.opacity = '0.9';
+            helpText.textContent = v.help;
+            const row = document.createElement('div');
+            row.style.cssText = 'margin-bottom:4px;display:flex;align-items:center;gap:8px;';
+            row.appendChild(badge);
+            row.appendChild(helpText);
+            const content = document.createElement('div');
+            content.className = 'content';
+            content.appendChild(row);
+            container.appendChild(icon);
+            container.appendChild(content);
+        }, [
+            violation,
+            color,
+            this.overlayRootId,
+            A11yAuditOverlay.BANNER_ID,
+        ]);
     }
     /**
-     * Removes the violation description overlay.
+     * Removes the violation description banner from the page.
      */
     async hideViolationOverlay() {
-        await this.page.evaluate((rootId) => {
+        await this.safeEvaluate((rootId) => {
             const el = document.getElementById(rootId);
             if (el)
                 el.remove();
         }, this.overlayRootId);
     }
+    // ──────────────────────────────────────────────
+    //  Element highlighting
+    // ──────────────────────────────────────────────
     /**
-     * Attaches accessibility data to the Playwright test report.
-     */
-    async addTestAttachment(testInfo, name, description) {
-        await testInfo.attach(name, {
-            contentType: 'application/json',
-            body: Buffer.from(description),
-        });
-    }
-    getAuditAnnotations() {
-        return this.auditAnnotations;
-    }
-    /**
-     * Captures a screenshot and attaches it to the test report.
+     * Draws a glowing highlight border around the element matching `selector`.
+     *
+     * The element is scrolled into view first so that the highlight coordinates
+     * are accurate after any layout shift.
+     *
+     * @param selector - A CSS selector that uniquely identifies the target element.
+     * @param color    - CSS colour for the highlight border and glow.
      */
-    async captureAndAttachScreenshot(fileName, testInfo) {
-        return await test_1.test.step('Capture A11y screenshot', async () => {
-            // Use viewport screenshot instead of fullPage to avoid browser resizing flashes
-            const screenshot = await this.page.screenshot({ fullPage: false });
-            await testInfo.attach(fileName, { contentType: 'image/png', body: screenshot });
-            return screenshot;
-        });
-    }
     async highlightElement(selector, color) {
-        await this.page.evaluate(([sel, color, rootId]) => {
+        await this.safeEvaluate(([sel, rawColor, rootId, highlightId]) => {
             const target = document.querySelector(sel);
             if (!target)
                 return;
-            // Scroll FIRST to ensure accurate coordinates after scroll
             target.scrollIntoView({ behavior: 'auto', block: 'center' });
-            let root = document.getElementById(rootId);
-            if (!root) {
-                root = document.createElement('div');
-                root.id = rootId;
-                root.style.cssText =
-                    'position: absolute; top: 0; left: 0; width: 0; height: 0; z-index: 2147483647;';
-                document.body.appendChild(root);
-                root.attachShadow({ mode: 'open' });
-            }
-            const shadow = root.shadowRoot;
-            let highlight = shadow.getElementById('a11y-highlight');
+            const toAlphaColor = (c, alpha) => {
+                if (c.includes('rgba'))
+                    return c.replace(/[\d.]+\)$/, `${alpha})`);
+                if (c.includes('rgb'))
+                    return c.replace('rgb', 'rgba').replace(')', `, ${alpha})`);
+                // Hex – convert alpha to 2-char hex
+                const hex = Math.round(alpha * 255)
+                    .toString(16)
+                    .padStart(2, '0');
+                return `${c}${hex}`;
+            };
+            const getOrCreateRoot = (id) => {
+                let root = document.getElementById(id);
+                if (!root) {
+                    root = document.createElement('div');
+                    root.id = id;
+                    root.style.cssText =
+                        'position:absolute;top:0;left:0;width:0;height:0;z-index:2147483647;';
+                    document.body.appendChild(root);
+                    root.attachShadow({ mode: 'open' });
+                }
+                return root.shadowRoot;
+            };
+            const shadow = getOrCreateRoot(rootId);
+            let highlight = shadow.getElementById(highlightId);
             if (!highlight) {
                 const style = document.createElement('style');
                 style.textContent = `
-                    #a11y-highlight {
-                        position: absolute;
-                        pointer-events: none;
-                        border-radius: 8px;
-                        box-sizing: border-box;
-                        z-index: 9999;
-                        box-shadow: 0 0 0 4px var(--c-alpha), 0 0 20px var(--c-alpha);
-                    }
-                    .glow {
-                        position: absolute;
-                        top: 0;
-                        left: 0;
-                        right: 0;
-                        bottom: 0;
-                        border-radius: inherit;
-                        border: 2px solid var(--c);
-                    }
-                `;
+                        #${highlightId} {
+                            position: absolute;
+                            pointer-events: none;
+                            border-radius: 8px;
+                            box-sizing: border-box;
+                            z-index: 9999;
+                            box-shadow: 0 0 0 4px var(--c-alpha), 0 0 20px var(--c-alpha);
+                        }
+                        .glow {
+                            position: absolute;
+                            inset: 0;
+                            border-radius: inherit;
+                            border: 2px solid var(--c);
+                        }
+                    `;
                 shadow.appendChild(style);
                 highlight = document.createElement('div');
-                highlight.id = 'a11y-highlight';
-                highlight.innerHTML = '<div class="glow"></div>';
+                highlight.id = highlightId;
+                const glow = document.createElement('div');
+                glow.className = 'glow';
+                highlight.appendChild(glow);
                 shadow.appendChild(highlight);
             }
+            const pad = 4;
             const rect = target.getBoundingClientRect();
-            highlight.style.left = `${rect.left + window.scrollX - 4}px`;
-            highlight.style.top = `${rect.top + window.scrollY - 4}px`;
-            highlight.style.width = `${rect.width + 8}px`;
-            highlight.style.height = `${rect.height + 8}px`;
-            highlight.style.border = `3px solid ${color}`;
-            highlight.style.setProperty('--c', color);
-            highlight.style.setProperty('--c-alpha', color.includes('rgba') ? color.replace(/[\d.]+\)$/, '0.3)') : color + '4D');
-        }, [selector, color, this.overlayRootId]);
+            highlight.style.left = `${rect.left + window.scrollX - pad}px`;
+            highlight.style.top = `${rect.top + window.scrollY - pad}px`;
+            highlight.style.width = `${rect.width + pad * 2}px`;
+            highlight.style.height = `${rect.height + pad * 2}px`;
+            highlight.style.border = `3px solid ${rawColor}`;
+            highlight.style.setProperty('--c', rawColor);
+            highlight.style.setProperty('--c-alpha', toAlphaColor(rawColor, 0.3));
+        }, [
+            selector,
+            color,
+            this.overlayRootId,
+            A11yAuditOverlay.HIGHLIGHT_ID,
+        ]);
     }
     /**
-     * Removes highlighting from an element.
+     * Removes the element highlight from the page.
      */
     async unhighlightElement() {
-        await this.page.evaluate((rootId) => {
+        await this.safeEvaluate(([rootId, highlightId]) => {
             const root = document.getElementById(rootId);
-            if (root && root.shadowRoot) {
-                const highlight = root.shadowRoot.getElementById('a11y-highlight');
+            if (root === null || root === void 0 ? void 0 : root.shadowRoot) {
+                const highlight = root.shadowRoot.getElementById(highlightId);
                 if (highlight)
                     highlight.remove();
             }
-        }, this.overlayRootId);
+        }, [this.overlayRootId, A11yAuditOverlay.HIGHLIGHT_ID]);
+    }
+    // ──────────────────────────────────────────────
+    //  Test report helpers
+    // ──────────────────────────────────────────────
+    /**
+     * Attaches arbitrary data to the Playwright test report.
+     *
+     * @param testInfo    - The current Playwright `TestInfo` instance.
+     * @param name        - Attachment name shown in the report.
+     * @param description - Content to attach (serialised as JSON by the caller).
+     */
+    async addTestAttachment(testInfo, name, description) {
+        await testInfo.attach(name, {
+            contentType: 'application/json',
+            body: Buffer.from(description),
+        });
+    }
+    /**
+     * Captures a viewport screenshot and attaches it to the test report.
+     *
+     * The screenshot uses `fullPage: false` (viewport only) to avoid browser
+     * resizing flashes that can occur with full-page captures.
+     *
+     * @param fileName - Name for the attachment in the test report.
+     * @param testInfo - The current Playwright `TestInfo` instance.
+     * @returns The raw screenshot buffer.
+     */
+    async captureAndAttachScreenshot(fileName, testInfo) {
+        return await test_1.test.step('Capture A11y screenshot', async () => {
+            const screenshot = await this.page.screenshot({ fullPage: false });
+            await testInfo.attach(fileName, { contentType: 'image/png', body: screenshot });
+            return screenshot;
+        });
+    }
+    // ──────────────────────────────────────────────
+    //  Private helpers
+    // ──────────────────────────────────────────────
+    /**
+     * Wrapper around `page.evaluate` that silently swallows errors caused by
+     * the page or browser closing mid-evaluation (e.g. navigation, test teardown).
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async safeEvaluate(fn, arg) {
+        try {
+            if (arg !== undefined) {
+                await this.page.evaluate(fn, arg);
+            }
+            else {
+                await this.page.evaluate(fn);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                (error.message.includes('Target page, context or browser has been closed') ||
+                    error.message.includes('Execution context was destroyed') ||
+                    error.message.includes('Test ended'))) {
+                // Page navigated away or test ended — overlay is no longer relevant.
+                return;
+            }
+            throw error;
+        }
     }
 }
 exports.A11yAuditOverlay = A11yAuditOverlay;
+/** IDs for elements created inside the shadow root. */
+A11yAuditOverlay.BANNER_ID = 'a11y-banner';
+A11yAuditOverlay.HIGHLIGHT_ID = 'a11y-highlight';

package/dist/A11yHtmlRenderer.js

@@ -59,11 +59,17 @@ class A11yHtmlRenderer {
         if (!fs.existsSync(outputFolder)) {
             fs.mkdirSync(outputFolder, { recursive: true });
         }
-        // 1. Copy the pure HTML template to the output location
-        fs.copyFileSync(templatePath, outputFileName);
-        // 2. Wrap the report data in a JS variable and write data.js next to the HTML file
+        // Derive a unique data filename from the HTML filename to avoid collisions
+        // when multiple reports (e.g. accessibility + execution) share the same folder.
+        const htmlBaseName = path.basename(outputFileName, '.html');
+        const dataJsName = `data-${htmlBaseName}.js`;
+        // 1. Copy the HTML template and patch the data.js reference to the unique name
+        let templateHtml = fs.readFileSync(templatePath, 'utf8');
+        templateHtml = templateHtml.replace(/(<script\s+src=")data\.js(")/, `$1${dataJsName}$2`);
+        fs.writeFileSync(outputFileName, templateHtml, 'utf8');
+        // 2. Wrap the report data in a JS variable and write the per-report data file
         const outputDir = path.dirname(outputFileName);
-        const dataJsPath = path.join(outputDir, 'data.js');
+        const dataJsPath = path.join(outputDir, dataJsName);
         const jsContent = `window.snapAllyData = ${JSON.stringify(data)};`;
         fs.writeFileSync(dataJsPath, jsContent, 'utf8');
         // 3. Copy the global CSS and JS rendering engine next to the HTML file

package/dist/A11yScanner.js

@@ -41,7 +41,7 @@ async function scanA11y(page, testInfo, options = {}) {
     // Sanitize pageKey to prevent path traversal attacks
     const rawPageKey = options.pageKey || page.url();
     const pageKey = sanitizePageKey(rawPageKey);
-    const overlay = new A11yAuditOverlay_1.A11yAuditOverlay(page, pageKey);
+    const overlay = new A11yAuditOverlay_1.A11yAuditOverlay(page);
     // Configure Axe
     let axeBuilder = new playwright_1.default({ page });
     const target = options.include || options.box;

package/dist/SnapAllyReporter.d.ts

@@ -24,22 +24,68 @@ export interface AccessibilityReporterOptions {
 }
 /**
  * Playwright reporter for accessibility audits and test steps.
- * Generates an execution summary and detailed reports per test.
+ *
+ * Generates:
+ * - A per-test execution report (steps, video, screenshots, errors)
+ * - A per-scan accessibility report (violations, evidence, ADO integration)
+ * - A global execution summary with per-browser breakdowns
  */
 declare class SnapAllyReporter implements Reporter {
-    private testIndex;
-    private outputFolder;
-    private assetsManager;
-    private renderer;
-    private options;
+    private readonly outputFolder;
+    private readonly assetsManager;
+    private readonly renderer;
+    private readonly options;
+    private readonly colors;
     private projectRoot;
-    printsToStdio(): boolean;
-    private executionSummary;
-    private tasks;
+    /**
+     * Monotonically increasing test counter.
+     * Incremented synchronously in {@link onTestEnd} to avoid race conditions
+     * when multiple async {@link processTestResult} calls run concurrently.
+     */
+    private testIndex;
+    /** Async tasks queued by `onTestEnd`; drained in `onEnd`. */
+    private readonly tasks;
+    /** Aggregated data for the final summary report. */
+    private readonly executionSummary;
     constructor(options?: AccessibilityReporterOptions);
+    printsToStdio(): boolean;
     onBegin(config: FullConfig): void;
     onTestEnd(test: TestCase, result: TestResult): void;
-    private processTestResult;
     onEnd(result: FullResult): Promise<void>;
+    private processTestResult;
+    /** Extracts structured metadata from test annotations and result steps. */
+    private extractTestMetadata;
+    /** Determines the browser name for the current test. */
+    private resolveBrowser;
+    /** Converts Playwright error objects into HTML-safe strings. */
+    private extractErrorLogs;
+    /** Return value for {@link processAccessibilityData}. */
+    private processAccessibilityData;
+    /** Collects all A11y data sources (attachments + annotations) for a test. */
+    private collectA11yDataSources;
+    /** Attempts to parse a single A11y data source into a ReportData object. */
+    private parseA11ySource;
+    /** Generates a sanitized HTML filename for an accessibility report. */
+    private buildA11yReportName;
+    /** Applies reporter-level configuration (colors, ADO, video) to a ReportData object. */
+    private applyReportConfig;
+    /**
+     * Backfills reproduction steps from `test.step` calls into a11y targets
+     * that have no steps recorded (e.g. violations found via static scan).
+     */
+    private backfillSteps;
+    /**
+     * Aggregates a11y error counts into both the browser-specific and global
+     * summaries. Returns the total error count for this scan.
+     */
+    private aggregateA11yErrors;
+    /** Updates the browser-specific test counts (passed/failed/skipped). */
+    private updateBrowserSummary;
+    /** Updates the global execution summary counts. */
+    private updateGlobalSummary;
+    /** Ensures a file group key exists in the grouped results map. */
+    private ensureGroupExists;
+    /** Lazily initialises and returns the browser summary for the given browser name. */
+    private getOrCreateBrowserSummary;
 }
 export default SnapAllyReporter;