snap-ally 0.0.2 → 0.1.0-beta

package/README.md

@@ -1,4 +1,4 @@
-# snap-ally <span aria-hidden="true">📸♿</span>
+# snap-ally 📸♿
 
 [![npm version](https://img.shields.io/npm/v/snap-ally.svg)](https://www.npmjs.com/package/snap-ally)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -7,17 +7,13 @@ A powerful, developer-friendly Playwright reporter for **Accessibility testing**
 
 ---
 
-## <span aria-hidden="true">📺</span> Demo
+## 📺 Demo
 
-<div align="center">
-  <video src="video.webm" width="800" controls aria-label="Snap-Ally accessibility reporter demonstration video showing HTML reports and visual overlays">
-    Your browser does not support the video tag. You can <a href="video.webm">download the video</a> to view it.
-  </video>
-</div>
+**[▶️ Watch the Demo Video](https://www.loom.com/share/853c04f1f76242a699e8f82e54733007)**
 
 ---
 
-## <span aria-hidden="true">✨</span> Features
+## ✨ Features
 
 - **Beautiful HTML Reporting**: Comprehensive summary and detail pages.
 - **Visual Overlays**: Highlights violations directly on the page in screenshots.
@@ -28,7 +24,7 @@ A powerful, developer-friendly Playwright reporter for **Accessibility testing**
 
 ---
 
-## <span aria-hidden="true">🚀</span> Installation
+## 🚀 Installation
 
 ```bash
 npm install snap-ally --save-dev
@@ -36,30 +32,33 @@ npm install snap-ally --save-dev
 
 ---
 
-## <span aria-hidden="true">🛠️</span> Setup
+## 🛠️ Setup
 
 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',
+    [
+      "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",
+        },
       },
-      // Optional: Azure DevOps Integration
-      ado: {
-        organization: 'your-org',
-        project: 'your-project'
-      }
-    }]
+    ],
   ],
 });
 ```
@@ -71,23 +70,24 @@ export default defineConfig({
 Import and use `scanA11y` within your Playwright tests:
 
 ```typescript
-import { test } from '@playwright/test';
-import { scanA11y } from 'snap-ally';
+import { test } from "@playwright/test";
+import { scanA11y } from "snap-ally";
+
+test("verify page accessibility", async ({ page }, testInfo) => {
+  await page.goto("https://example.com");
 
-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 }, // Disable specific rule
-    },
-    tags: ['wcag2a', 'wcag2aa'], // Focus on specific WCAG levels
-    verbose: true,
-    pageKey: 'Homepage' // Custom name for the report file
+      'color-contrast': { enabled: false },
+    }
   });
 });
 ```
@@ -98,20 +98,21 @@ test('verify page accessibility', async ({ page }, testInfo) => {
 
 ### Reporter Options (in `playwright.config.ts`)
 
-| Option | Type | Description |
-| --- | --- | --- |
-| `outputFolder` | `string` | Where to save the reports. Defaults to `steps-report`. |
-| `colors` | `object` | Customize severity colors (critical, serious, moderate, minor). |
-| `ado` | `object` | Azure DevOps configuration for deep linking. |
-| `ado.organization` | `string` | Your Azure DevOps organization name. |
-| `ado.project` | `string` | Your Azure DevOps project name. |
+| Option             | Type     | Description                                                     |
+| ------------------ | -------- | --------------------------------------------------------------- |
+| `outputFolder`     | `string` | Where to save the reports. Defaults to `steps-report`.          |
+| `colors`           | `object` | Customize severity colors (critical, serious, moderate, minor). |
+| `ado`              | `object` | Azure DevOps configuration for deep linking.                    |
+| `ado.organization` | `string` | Your Azure DevOps organization name.                            |
+| `ado.project`      | `string` | Your Azure DevOps project name.                                 |
 
 ### `scanA11y` Options
 
 | Option | Type | Description |
 | --- | --- | --- |
 | `include` | `string` | CSS selector to limit the scan to a specific element. |
-| `verbose` | `boolean` | Log violations to the console. Defaults to `true`. |
+| `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/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.

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,22 +57,24 @@ 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;
                         }
@@ -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,13 +118,15 @@ class A11yReportAssets {
      */
     copyScreenshots(result, destFolder) {
         return result.attachments
-            .filter(a => a.name === 'screenshot')
+            .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 '';
         })
@@ -133,14 +137,15 @@ class A11yReportAssets {
      */
     copyPngAttachments(result, destFolder) {
         return result.attachments
-            .filter(a => a.name.endsWith('.png') && a.name !== 'screenshot')
+            .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,7 +157,10 @@ class A11yReportAssets {
     copyAllOtherAttachments(result, destFolder) {
         const excludedNames = ['screenshot', 'video', 'A11y'];
         return result.attachments
-            .filter(a => !excludedNames.includes(a.name) && !a.name.endsWith('.png'))
+            .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) {

package/dist/A11yScanner.d.ts

@@ -16,6 +16,8 @@ export interface A11yScannerOptions {
     tags?: string[];
     /** Any other Axe-core options to pass to the builder. */
     axeOptions?: Record<string, unknown>;
+    /** Custom identifier for the report file name. */
+    pageKey?: string;
 }
 /**
  * Performs an accessibility audit using Axe and Lighthouse.

package/dist/A11yScanner.js

@@ -9,13 +9,39 @@ 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
+        // Remove protocol
+        .replace(/^https?:\/\//, '')
+        // Remove or replace path separators and dangerous characters
+        .replace(/[\/\\:*?"<>|]/g, '-')
+        // Remove any remaining path traversal attempts
+        .replace(/\.\./g, '')
+        // Replace multiple consecutive dashes with a single dash
+        .replace(/-+/g, '-')
+        // Remove leading/trailing dashes
+        .replace(/^-+|-+$/g, '')
+        // Convert to lowercase for consistency
+        .toLowerCase()
+        // Limit length to prevent filesystem issues
+        .substring(0, 200);
+}
 /**
  * Performs an accessibility audit using Axe and Lighthouse.
  */
 async function scanA11y(page, testInfo, options = {}) {
-    var _a;
-    const verbose = (_a = options.verbose) !== null && _a !== void 0 ? _a : true;
-    const overlay = new A11yAuditOverlay_1.A11yAuditOverlay(page, page.url());
+    var _a, _b;
+    const showTerminal = (_a = options.verbose) !== null && _a !== void 0 ? _a : true;
+    const showBrowser = (_b = options.consoleLog) !== null && _b !== void 0 ? _b : true;
+    // 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);
     // Configure Axe
     let axeBuilder = new playwright_1.default({ page });
     const target = options.include || options.box;
@@ -37,13 +63,34 @@ 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.message && (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 (verbose && violationCount > 0) {
-        console.log(`\n[A11yScanner] Violations found: ${violationCount}`);
-        axeResults.violations.forEach((v, i) => {
-            console.log(`  ${i + 1}. ${v.id} [${v.impact}] - ${v.help}`);
-        });
+    if ((showTerminal || showBrowser) && violationCount > 0) {
+        const mainMsg = `[A11yScanner] Violations found: ${violationCount}`;
+        // Prepare all detail messages
+        const detailMessages = axeResults.violations.map((v, i) => `  ${i + 1}. ${v.id} [${v.impact}] - ${v.help}`);
+        // Log to terminal
+        if (showTerminal) {
+            console.log(`\n${mainMsg}`);
+            detailMessages.forEach(msg => console.log(msg));
+        }
+        // Batch log to Browser Console in a single evaluate call
+        if (showBrowser) {
+            await page.evaluate(([mainMsg, details]) => {
+                console.log(`%c ${mainMsg}`, 'color: #ea580c; font-weight: bold; font-size: 12px;');
+                details.forEach((msg) => console.log(msg));
+            }, [mainMsg, detailMessages]);
+        }
     }
     // Fail the test if violations found (softly)
     test_1.expect.soft(violationCount, `Accessibility audit failed with ${violationCount} violations.`).toBe(0);
@@ -67,9 +114,9 @@ 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
@@ -106,16 +153,18 @@ async function scanA11y(page, testInfo, options = {}) {
     }
     // Prepare data for the reporter
     const reportData = {
-        pageKey: page.url(),
+        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,20 @@ 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;

package/dist/SnapAllyReporter.d.ts

@@ -33,6 +33,7 @@ declare class SnapAllyReporter implements Reporter {
     private renderer;
     private options;
     private projectRoot;
+    printsToStdio(): boolean;
     private executionSummary;
     private tasks;
     constructor(options?: AccessibilityReporterOptions);