snap-ally 0.0.4 → 0.1.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.js

@@ -24,7 +24,8 @@ class A11yAuditOverlay {
             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;';
+                root.style.cssText =
+                    'position: absolute; top: 0; left: 0; width: 0; height: 0; z-index: 2147483647;';
                 document.body.appendChild(root);
                 root.attachShadow({ mode: 'open' });
             }
@@ -76,8 +77,11 @@ class A11yAuditOverlay {
                 container.id = 'a11y-banner';
                 shadow.appendChild(container);
             }
-            const alphaColor = color.includes('rgba') ? color :
-                (color.includes('rgb') ? color.replace('rgb', 'rgba').replace(')', ', 0.85)') : color + 'E6');
+            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>
@@ -106,7 +110,7 @@ class A11yAuditOverlay {
     async addTestAttachment(testInfo, name, description) {
         await testInfo.attach(name, {
             contentType: 'application/json',
-            body: Buffer.from(description)
+            body: Buffer.from(description),
         });
     }
     getAuditAnnotations() {
@@ -134,7 +138,8 @@ class A11yAuditOverlay {
             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;';
+                root.style.cssText =
+                    'position: absolute; top: 0; left: 0; width: 0; height: 0; z-index: 2147483647;';
                 document.body.appendChild(root);
                 root.attachShadow({ mode: 'open' });
             }

package/dist/A11yHtmlRenderer.d.ts

@@ -1,11 +1,11 @@
 /**
- * Handles the rendering of HTML reports using EJS templates.
+ * Handles the rendering of HTML reports using static templates and JSON data injection.
  */
 export declare class A11yHtmlRenderer {
     /**
-     * Renders an HTML template and saves it to the specified file.
+     * Renders a static HTML template by copying it and generating the accompanied data payload.
      * @param templateName The template file name in the templates folder.
-     * @param data The data object to pass to EJS.
+     * @param data The data object to pass to the client-side JS app.
      * @param outputFolder The folder where the rendered file will be saved.
      * @param outputFileName The full path of the output file.
      */

package/dist/A11yHtmlRenderer.js

@@ -36,40 +36,53 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.A11yHtmlRenderer = void 0;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-const ejs = __importStar(require("ejs"));
 /**
- * Handles the rendering of HTML reports using EJS templates.
+ * Handles the rendering of HTML reports using static templates and JSON data injection.
  */
 class A11yHtmlRenderer {
     /**
-     * Renders an HTML template and saves it to the specified file.
+     * Renders a static HTML template by copying it and generating the accompanied data payload.
      * @param templateName The template file name in the templates folder.
-     * @param data The data object to pass to EJS.
+     * @param data The data object to pass to the client-side JS app.
      * @param outputFolder The folder where the rendered file will be saved.
      * @param outputFileName The full path of the output file.
      */
     async render(templateName, data, outputFolder, outputFileName) {
         // Resolve path relative to this file (dist/A11yHtmlRenderer.js)
-        const templatePath = path.join(__dirname, 'templates', templateName);
-        let templateContent = '';
-        try {
-            templateContent = fs.readFileSync(templatePath, 'utf8');
-        }
-        catch {
+        const templatesDir = path.join(__dirname, 'templates');
+        const templatePath = path.join(templatesDir, templateName);
+        const cssPath = path.join(templatesDir, 'global-report-styles.css');
+        const jsPath = path.join(templatesDir, 'report-app.js');
+        if (!fs.existsSync(templatePath)) {
             throw new Error(`[A11yHtmlRenderer] Template not found: ${templatePath}`);
         }
-        let html = '';
+        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
+        const outputDir = path.dirname(outputFileName);
+        const dataJsPath = path.join(outputDir, 'data.js');
+        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
+        const outCssPath = path.join(outputDir, 'global-report-styles.css');
+        const outJsPath = path.join(outputDir, 'report-app.js');
         try {
-            html = ejs.render(templateContent, data);
+            if (fs.existsSync(cssPath))
+                fs.copyFileSync(cssPath, outCssPath);
         }
-        catch (error) {
-            console.error(`[A11yHtmlRenderer] EJS Render Error (${templateName}):`, error);
-            throw error;
+        catch (e) {
+            console.error('Error copying CSS:', e);
         }
-        if (!fs.existsSync(outputFolder)) {
-            fs.mkdirSync(outputFolder, { recursive: true });
+        try {
+            if (fs.existsSync(jsPath))
+                fs.copyFileSync(jsPath, outJsPath);
+        }
+        catch (e) {
+            console.error('Error copying JS:', e);
         }
-        fs.writeFileSync(outputFileName, html);
     }
     /**
      * Converts ANSI color codes to HTML spans for nicer error display.
@@ -89,10 +102,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);
         }

package/dist/A11yReportAssets.d.ts

@@ -9,7 +9,7 @@ export declare class A11yReportAssets {
     copyToFolder(destFolder: string, srcPath: string, fileName?: string): string;
     /**
      * Copies the test video if available.
-     * Includes a small retry to ensure Playwright has finished flushing the file.
+     * Includes a more robust retry to ensure Playwright has finished flushing the file.
      */
     copyTestVideo(result: TestResult, destFolder: string): Promise<string>;
     /**

package/dist/A11yReportAssets.js

@@ -57,31 +57,33 @@ class A11yReportAssets {
     }
     /**
      * Copies the test video if available.
-     * Includes a small retry to ensure Playwright has finished flushing the file.
+     * Includes a more robust retry to ensure Playwright has finished flushing the file.
      */
     async copyTestVideo(result, destFolder) {
-        const videoAttachments = result.attachments.filter(a => a.name === 'video');
+        // More flexible matching for video attachments
+        const videoAttachments = result.attachments.filter((a) => a.name === 'video' || (a.contentType || '').startsWith('video/'));
         let bestVideo = null;
         let maxSize = -1;
         for (const attachment of videoAttachments) {
             if (!attachment.path)
                 continue;
-            // Retry logic: Wait for file to exist and have non-zero size (up to 2 seconds)
+            // Retry logic: Wait for file to exist and have non-zero size (up to 3 seconds)
             let attempts = 0;
             let isReady = false;
-            while (attempts < 10) {
+            while (attempts < 15) {
                 if (fs.existsSync(attachment.path)) {
                     try {
-                        if (fs.statSync(attachment.path).size > 0) {
+                        const stats = fs.statSync(attachment.path);
+                        if (stats.size > 0) {
                             isReady = true;
                             break;
                         }
                     }
-                    catch (e) {
+                    catch {
                         // statSync might fail if file is temporarily locked
                     }
                 }
-                await new Promise(r => setTimeout(r, 200));
+                await new Promise((r) => setTimeout(r, 200));
                 attempts++;
             }
             if (isReady) {
@@ -97,12 +99,12 @@ class A11yReportAssets {
                 }
             }
             else {
-                console.warn(`[SnapAlly] Video attachment found but file is missing or empty: ${attachment.path}`);
+                console.warn(`[SnapAlly] Video attachment found but file is missing or empty after retry: ${attachment.path}`);
             }
         }
         if (bestVideo) {
             try {
-                return this.copyToFolder(destFolder, bestVideo);
+                return this.copyToFolder(destFolder, bestVideo, 'video.webm');
             }
             catch (e) {
                 console.error(`[SnapAlly] Failed to copy video: ${e}`);
@@ -116,31 +118,39 @@ class A11yReportAssets {
      */
     copyScreenshots(result, destFolder) {
         return result.attachments
-            .filter(a => a.name === 'screenshot')
-            .map(a => {
+            .filter((a) => a.name === 'screenshot' || (a.contentType || '').startsWith('image/'))
+            .map((a) => {
             if (a.path) {
                 return this.copyToFolder(destFolder, a.path);
             }
             else if (a.body) {
-                return this.writeBuffer(destFolder, `screenshot-${Date.now()}.png`, a.body);
+                const timestamp = Date.now();
+                const name = a.name === 'screenshot'
+                    ? `screenshot-${timestamp}.png`
+                    : a.name.endsWith('.png')
+                        ? a.name
+                        : `${a.name}.png`;
+                return this.writeBuffer(destFolder, name, a.body);
             }
             return '';
         })
-            .filter(path => path !== '');
+            .filter((path) => path !== '');
     }
     /**
      * Copies all PNG attachments to the report folder and returns their new names.
      */
     copyPngAttachments(result, destFolder) {
         return result.attachments
-            .filter(a => a.name.endsWith('.png') && a.name !== 'screenshot')
-            .map(a => {
+            .filter((a) => (a.name.endsWith('.png') || (a.contentType || '') === 'image/png') &&
+            a.name !== 'screenshot')
+            .map((a) => {
             let name = '';
             if (a.path) {
                 name = this.copyToFolder(destFolder, a.path, a.name);
             }
             else if (a.body) {
-                name = this.writeBuffer(destFolder, a.name, a.body);
+                const safeName = a.name.endsWith('.png') ? a.name : `${a.name}.png`;
+                name = this.writeBuffer(destFolder, safeName, a.body);
             }
             return name ? { path: name, name: a.name } : null;
         })
@@ -152,8 +162,11 @@ class A11yReportAssets {
     copyAllOtherAttachments(result, destFolder) {
         const excludedNames = ['screenshot', 'video', 'A11y'];
         return result.attachments
-            .filter(a => !excludedNames.includes(a.name) && !a.name.endsWith('.png'))
-            .map(a => {
+            .filter((a) => !excludedNames.includes(a.name) &&
+            !a.name.endsWith('.png') &&
+            !(a.contentType || '').startsWith('image/') &&
+            !(a.contentType || '').startsWith('video/'))
+            .map((a) => {
             let name = '';
             if (a.path) {
                 name = this.copyToFolder(destFolder, a.path, a.name);

package/dist/A11yScanner.js

@@ -9,12 +9,13 @@ const playwright_1 = __importDefault(require("@axe-core/playwright"));
 const test_1 = require("@playwright/test");
 const A11yAuditOverlay_1 = require("./A11yAuditOverlay");
 const models_1 = require("./models");
+const A11yTimeUtils_1 = require("./A11yTimeUtils");
 /**
  * Sanitizes a string to be safe for use in file paths and prevents path traversal attacks.
  * Removes or replaces dangerous characters and path separators.
  */
 function sanitizePageKey(input) {
-    return input
+    return (input
         // Remove protocol
         .replace(/^https?:\/\//, '')
         // Remove or replace path separators and dangerous characters
@@ -28,7 +29,7 @@ function sanitizePageKey(input) {
         // Convert to lowercase for consistency
         .toLowerCase()
         // Limit length to prevent filesystem issues
-        .substring(0, 200);
+        .substring(0, 200));
 }
 /**
  * Performs an accessibility audit using Axe and Lighthouse.
@@ -50,6 +51,7 @@ async function scanA11y(page, testInfo, options = {}) {
         }
         else {
             // AxeBuilder for playwright also supports locators/elements in include
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             axeBuilder = axeBuilder.include(target);
         }
     }
@@ -62,7 +64,19 @@ async function scanA11y(page, testInfo, options = {}) {
     if (options.axeOptions) {
         axeBuilder = axeBuilder.options(options.axeOptions);
     }
-    const axeResults = await axeBuilder.analyze();
+    let axeResults;
+    try {
+        axeResults = await axeBuilder.analyze();
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            (error.message.includes('Test ended') ||
+                error.message.includes('Target page, context or browser has been closed'))) {
+            console.warn(`[SnapAlly] Accessibility scan skipped: ${error.message}`);
+            return;
+        }
+        throw error;
+    }
     const violationCount = axeResults.violations.length;
     if ((showTerminal || showBrowser) && violationCount > 0) {
         const mainMsg = `[A11yScanner] Violations found: ${violationCount}`;
@@ -71,7 +85,7 @@ async function scanA11y(page, testInfo, options = {}) {
         // Log to terminal
         if (showTerminal) {
             console.log(`\n${mainMsg}`);
-            detailMessages.forEach(msg => console.log(msg));
+            detailMessages.forEach((msg) => console.log(msg));
         }
         // Batch log to Browser Console in a single evaluate call
         if (showBrowser) {
@@ -82,14 +96,16 @@ async function scanA11y(page, testInfo, options = {}) {
         }
     }
     // Fail the test if violations found (softly)
-    test_1.expect.soft(violationCount, `Accessibility audit failed with ${violationCount} violations.`).toBe(0);
+    test_1.expect
+        .soft(violationCount, `Accessibility audit failed with ${violationCount} violations.`)
+        .toBe(0);
     // Run Axe Audit
     const errors = [];
     const colorMap = {
         minor: '#0ea5e9', // Ocean Blue
         moderate: '#f59e0b', // Amber/Honey
         serious: '#ea580c', // Deep Orange
-        critical: '#dc2626' // Power Red
+        critical: '#dc2626', // Power Red
     };
     // Process violations for the report
     for (const violation of axeResults.violations) {
@@ -103,16 +119,21 @@ async function scanA11y(page, testInfo, options = {}) {
                 await overlay.showViolationOverlay({ id: violation.id, help: violation.help }, severityColor);
                 if (await locator.isVisible()) {
                     await overlay.highlightElement(elementSelector, severityColor);
-                    // Allow time for video capture or manual inspection during debug
+                    // Allow a small time for overlay highlight to be visible in video
                     // eslint-disable-next-line playwright/no-wait-for-timeout
-                    await page.waitForTimeout(2000);
+                    await page.waitForTimeout(100);
                     const screenshotName = `a11y-${violation.id}-${errorIdx++}.png`;
                     const buffer = await overlay.captureAndAttachScreenshot(screenshotName, testInfo);
                     // Capture execution steps for context
-                    const excluded = new Set(['Pre Condition', 'Post Condition', 'Description', 'A11y']);
+                    const excluded = new Set([
+                        'Pre Condition',
+                        'Post Condition',
+                        'Description',
+                        'A11y',
+                    ]);
                     const contextSteps = (testInfo.annotations || [])
-                        .filter(a => !excluded.has(a.type))
-                        .map(a => a.description || '');
+                        .filter((a) => !excluded.has(a.type))
+                        .map((a) => a.description || '');
                     const nodeHtml = node.html || '';
                     const friendlySnippet = elementSelector; // Use full CSS selector path from Axe core
                     targets.push({
@@ -122,7 +143,7 @@ async function scanA11y(page, testInfo, options = {}) {
                         screenshot: screenshotName,
                         steps: contextSteps,
                         stepsJson: JSON.stringify(contextSteps),
-                        screenshotBase64: buffer.toString('base64')
+                        screenshotBase64: buffer.toString('base64'),
                     });
                     await overlay.unhighlightElement();
                 }
@@ -135,23 +156,25 @@ async function scanA11y(page, testInfo, options = {}) {
             helpUrl: violation.helpUrl,
             help: violation.help,
             guideline: violation.tags[1] || 'N/A',
-            wcagRule: violation.tags.find(t => t.startsWith('wcag')) || violation.tags[1] || 'N/A',
+            wcagRule: violation.tags.find((t) => t.startsWith('wcag')) || violation.tags[1] || 'N/A',
             total: targets.length || violation.nodes.length, // Fallback to node count if no screenshots
-            target: targets
+            target: targets,
         });
     }
     // Prepare data for the reporter
     const reportData = {
         pageKey,
+        pageUrl: page.url(),
         accessibilityScore: 0, // No longer used, derivation from Lighthouse removed
-        errors,
+        a11yErrors: errors,
         video: 'a11y-scan-video.webm', // Reference name for reporter
         criticalColor: models_1.Severity.critical,
         seriousColor: models_1.Severity.serious,
         moderateColor: models_1.Severity.moderate,
         minorColor: models_1.Severity.minor,
         adoOrganization: process.env.ADO_ORGANIZATION || '',
-        adoProject: process.env.ADO_PROJECT || ''
+        adoProject: process.env.ADO_PROJECT || '',
+        timestamp: A11yTimeUtils_1.A11yTimeUtils.formatDate(new Date()),
     };
     await overlay.addTestAttachment(testInfo, 'A11y', JSON.stringify(reportData));
     await overlay.hideViolationOverlay();

package/dist/A11yTimeUtils.d.ts

@@ -6,4 +6,8 @@ export declare class A11yTimeUtils {
      * Formats milliseconds into a human-readable duration string.
      */
     static formatDuration(ms: number): string;
+    /**
+     * Formats a Date object into a human-readable string.
+     */
+    static formatDate(date: Date): string;
 }

package/dist/A11yTimeUtils.js

@@ -20,5 +20,33 @@ class A11yTimeUtils {
         const remainingSeconds = seconds % 60;
         return `${minutes}m ${remainingSeconds.toFixed(0)}s`;
     }
+    /**
+     * Formats a Date object into a human-readable string.
+     */
+    static formatDate(date) {
+        const day = String(date.getDate()).padStart(2, '0');
+        const monthNames = [
+            'Jan',
+            'Feb',
+            'Mar',
+            'Apr',
+            'May',
+            'Jun',
+            'Jul',
+            'Aug',
+            'Sep',
+            'Oct',
+            'Nov',
+            'Dec',
+        ];
+        const month = monthNames[date.getMonth()];
+        const year = date.getFullYear();
+        let hours = date.getHours();
+        const ampm = hours >= 12 ? 'PM' : 'AM';
+        hours = hours % 12 || 12;
+        const formattedHours = String(hours).padStart(2, '0');
+        const minutes = String(date.getMinutes()).padStart(2, '0');
+        return `${day} ${month} ${year}, ${formattedHours}:${minutes} ${ampm}`;
+    }
 }
 exports.A11yTimeUtils = A11yTimeUtils;