snap-ally 0.1.0-beta → 0.2.1-beta

package/README.md

@@ -37,29 +37,29 @@ npm install snap-ally --save-dev
 Add `snap-ally` to your `playwright.config.ts`:
 
 ```typescript
-import { defineConfig } from "@playwright/test";
+import { defineConfig } from '@playwright/test';
 
 export default defineConfig({
-  reporter: [
-    [
-      "snap-ally",
-      {
-        outputFolder: "a11y-report",
-        // Optional: Visual Customization
-        colors: {
-          critical: "#dc2626",
-          serious: "#ea580c",
-          moderate: "#f59e0b",
-          minor: "#0ea5e9",
-        },
-        // Optional: Azure DevOps Integration
-        ado: {
-          organization: "your-org",
-          project: "your-project",
-        },
-      },
+    reporter: [
+        [
+            'snap-ally',
+            {
+                outputFolder: 'a11y-report',
+                // Optional: Visual Customization
+                colors: {
+                    critical: '#dc2626',
+                    serious: '#ea580c',
+                    moderate: '#f59e0b',
+                    minor: '#0ea5e9',
+                },
+                // Optional: Azure DevOps Integration
+                ado: {
+                    organization: 'your-org',
+                    project: 'your-project',
+                },
+            },
+        ],
     ],
-  ],
 });
 ```
 
@@ -70,25 +70,25 @@ export default defineConfig({
 Import and use `scanA11y` within your Playwright tests:
 
 ```typescript
-import { test } from "@playwright/test";
-import { scanA11y } from "snap-ally";
-
-test("verify page accessibility", async ({ page }, testInfo) => {
-  await page.goto("https://example.com");
-
-  // Basic scan
-  await scanA11y(page, testInfo);
-
-  // Advanced scan with configuration
-  await scanA11y(page, testInfo, {
-    verbose: true,      // Log results to terminal
-    consoleLog: true,   // Log results to browser console
-    pageKey: 'Homepage', // Custom name for the report file
-    tags: ['wcag2a', 'wcag2aa'], 
-    rules: {
-      'color-contrast': { enabled: false },
-    }
-  });
+import { test } from '@playwright/test';
+import { scanA11y } from 'snap-ally';
+
+test('verify page accessibility', async ({ page }, testInfo) => {
+    await page.goto('https://example.com');
+
+    // Basic scan
+    await scanA11y(page, testInfo);
+
+    // Advanced scan with configuration
+    await scanA11y(page, testInfo, {
+        verbose: true, // Log results to terminal
+        consoleLog: true, // Log results to browser console
+        pageKey: 'Homepage', // Custom name for the report file
+        tags: ['wcag2a', 'wcag2aa'],
+        rules: {
+            'color-contrast': { enabled: false },
+        },
+    });
 });
 ```
 
@@ -108,14 +108,14 @@ test("verify page accessibility", async ({ page }, testInfo) => {
 
 ### `scanA11y` Options
 
-| Option | Type | Description |
-| --- | --- | --- |
-| `include` | `string` | CSS selector to limit the scan to a specific element. |
-| `verbose` | `boolean` | **Terminal Logs**: Print violations to terminal. Defaults to `true`. |
-| `consoleLog` | `boolean` | **Browser Logs**: Print violations to browser console. Defaults to `true`. |
-| `rules` | `object` | Axe-core rule configuration. |
-| `tags` | `string[]` | List of Axe-core tags to run (e.g., `['wcag2aa']`). |
-| `pageKey` | `string` | Custom identifier for the report file name. |
+| Option       | Type       | Description                                                                |
+| ------------ | ---------- | -------------------------------------------------------------------------- |
+| `include`    | `string`   | CSS selector to limit the scan to a specific element.                      |
+| `verbose`    | `boolean`  | **Terminal Logs**: Print violations to terminal. Defaults to `true`.       |
+| `consoleLog` | `boolean`  | **Browser Logs**: Print violations to browser console. Defaults to `true`. |
+| `rules`      | `object`   | Axe-core rule configuration.                                               |
+| `tags`       | `string[]` | List of Axe-core tags to run (e.g., `['wcag2aa']`).                        |
+| `pageKey`    | `string`   | Custom identifier for the report file name.                                |
 
 ---
 

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,36 +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;
@@ -55,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;
@@ -73,122 +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
@@ -102,10 +108,7 @@ class A11yHtmlRenderer {
             '\u001b[22m': '</span>',
             '\u001b[39m': '</span>',
         };
-        let result = text
-            .replace(/&/g, '&amp;')
-            .replace(/</g, '&lt;')
-            .replace(/>/g, '&gt;');
+        let result = text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
         for (const [code, tag] of Object.entries(map)) {
             result = result.split(code).join(tag);
         }