snap-ally 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 apis3445
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# snap-ally <span aria-hidden="true">📸♿</span>
+
+[![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)
+
+A powerful, developer-friendly Playwright reporter for **Accessibility testing** using Axe-core. Beyond just reporting, it provides visual evidence to help developers fix accessibility issues faster.
+
+---
+
+## <span aria-hidden="true">📺</span> 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>
+
+---
+
+## <span aria-hidden="true">✨</span> Features
+
+- **Beautiful HTML Reporting**: Comprehensive summary and detail pages.
+- **Visual Overlays**: Highlights violations directly on the page in screenshots.
+- **Automated Bug Preview**: Generates bug-like reports for each violation with clear technical details.
+- **Azure DevOps (ADO) Integration**: Link directly to your ADO project to create/manage accessibility bugs.
+- **Video & Screenshots**: Automatically captures and attaches video/screenshots of the failing state.
+- **Configurable Axe Rules**: Enable/Disable specific rules or filter by WCAG tags.
+
+---
+
+## <span aria-hidden="true">🚀</span> Installation
+
+```bash
+npm install snap-ally --save-dev
+```
+
+---
+
+## <span aria-hidden="true">🛠️</span> Setup
+
+Add `snap-ally` to your `playwright.config.ts`:
+
+```typescript
+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'
+      }
+    }]
+  ],
+});
+```
+
+---
+
+## <span aria-hidden="true">📖</span> Usage
+
+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, {
+    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
+  });
+});
+```
+
+---
+
+## <span aria-hidden="true">⚙️</span> Configuration Options
+
+### 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. |
+
+### `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`. |
+| `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. |
+
+---
+
+## <span aria-hidden="true">🛡️</span> License
+
+This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## <span aria-hidden="true">🤝</span> Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/A11yAuditOverlay.d.ts

@@ -0,0 +1,42 @@
+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.
+ */
+export declare class A11yAuditOverlay {
+    protected page: Page;
+    protected keyPage: string;
+    private readonly overlayRootId;
+    private auditAnnotations;
+    constructor(page: Page, keyPage: string);
+    reset(): void;
+    /**
+     * Shows a compact, modern banner at the bottom of the page describing the violation.
+     */
+    showViolationOverlay(violation: {
+        id: string;
+        help: string;
+    }, color: string): Promise<void>;
+    /**
+     * Removes the violation description overlay.
+     */
+    hideViolationOverlay(): Promise<void>;
+    /**
+     * Attaches accessibility data to the Playwright test report.
+     */
+    addTestAttachment(testInfo: TestInfo, name: string, description: string): Promise<void>;
+    getAuditAnnotations(): AuditAnnotation[];
+    /**
+     * Captures a screenshot and attaches it to the test report.
+     */
+    captureAndAttachScreenshot(fileName: string, testInfo: TestInfo): Promise<Buffer>;
+    highlightElement(selector: string, color: string): Promise<void>;
+    /**
+     * Removes highlighting from an element.
+     */
+    unhighlightElement(): Promise<void>;
+}

package/dist/A11yAuditOverlay.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A11yAuditOverlay = void 0;
+const test_1 = require("@playwright/test");
+/**
+ * Handles visual feedback and Playwright annotations during an accessibility audit.
+ */
+class A11yAuditOverlay {
+    constructor(page, keyPage) {
+        this.page = page;
+        this.keyPage = keyPage;
+        this.overlayRootId = 'a11y-audit-overlay-root';
+        this.auditAnnotations = [];
+    }
+    reset() {
+        this.auditAnnotations = [];
+    }
+    /**
+     * Shows a compact, modern banner at the bottom of the page describing the violation.
+     */
+    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');
+            if (!container) {
+                const style = document.createElement('style');
+                style.textContent = `
+                        #a11y-banner {
+                            position: fixed;
+                            left: 50%;
+                            bottom: 24px;
+                            transform: translateX(-50%);
+                            width: calc(100% - 40px);
+                            max-width: 600px;
+                            padding: 12px 18px;
+                            border-radius: 12px;
+                            color: white;
+                            font-family: system-ui, -apple-system, sans-serif;
+                            font-size: 14px;
+                            display: flex;
+                            align-items: center;
+                            gap: 12px;
+                            box-shadow: 0 12px 40px rgba(0,0,0,0.3);
+                            backdrop-filter: blur(16px) saturate(180%);
+                            -webkit-backdrop-filter: blur(16px) saturate(180%);
+                            border: 1px solid rgba(255,255,255,0.15);
+                            z-index: 10000;
+                        }
+                        .badge {
+                            background: rgba(255, 255, 255, 0.2);
+                            padding: 2px 8px;
+                            border-radius: 6px;
+                            font-size: 11px;
+                            font-weight: 700;
+                            text-transform: uppercase;
+                            letter-spacing: 0.5px;
+                            border: 1px solid rgba(255,255,255,0.2);
+                        }
+                        .content {
+                            flex: 1;
+                            line-height: 1.4;
+                            font-weight: 500;
+                            overflow: hidden;
+                        }
+                    `;
+                shadow.appendChild(style);
+                container = document.createElement('div');
+                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');
+            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]);
+    }
+    /**
+     * Removes the violation description overlay.
+     */
+    async hideViolationOverlay() {
+        await this.page.evaluate((rootId) => {
+            const el = document.getElementById(rootId);
+            if (el)
+                el.remove();
+        }, this.overlayRootId);
+    }
+    /**
+     * 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.
+     */
+    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]) => {
+            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');
+            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);
+                    }
+                `;
+                shadow.appendChild(style);
+                highlight = document.createElement('div');
+                highlight.id = 'a11y-highlight';
+                highlight.innerHTML = '<div class="glow"></div>';
+                shadow.appendChild(highlight);
+            }
+            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]);
+    }
+    /**
+     * Removes highlighting from an element.
+     */
+    async unhighlightElement() {
+        await this.page.evaluate((rootId) => {
+            const root = document.getElementById(rootId);
+            if (root && root.shadowRoot) {
+                const highlight = root.shadowRoot.getElementById('a11y-highlight');
+                if (highlight)
+                    highlight.remove();
+            }
+        }, this.overlayRootId);
+    }
+}
+exports.A11yAuditOverlay = A11yAuditOverlay;

package/dist/A11yHtmlRenderer.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Handles the rendering of HTML reports using EJS templates.
+ */
+export declare class A11yHtmlRenderer {
+    /**
+     * Renders an HTML template and saves it to the specified file.
+     * @param templateName The template file name in the templates folder.
+     * @param data The data object to pass to EJS.
+     * @param outputFolder The folder where the rendered file will be saved.
+     * @param outputFileName The full path of the output file.
+     */
+    render(templateName: string, data: Record<string, unknown>, outputFolder: string, outputFileName: string): Promise<void>;
+    /**
+     * Converts ANSI color codes to HTML spans for nicer error display.
+     */
+    ansiToHtml(text: string): string;
+}

package/dist/A11yHtmlRenderer.js

@@ -0,0 +1,102 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+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.
+ */
+class A11yHtmlRenderer {
+    /**
+     * Renders an HTML template and saves it to the specified file.
+     * @param templateName The template file name in the templates folder.
+     * @param data The data object to pass to EJS.
+     * @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 {
+            throw new Error(`[A11yHtmlRenderer] Template not found: ${templatePath}`);
+        }
+        let html = '';
+        try {
+            html = ejs.render(templateContent, data);
+        }
+        catch (error) {
+            console.error(`[A11yHtmlRenderer] EJS Render Error (${templateName}):`, error);
+            throw error;
+        }
+        if (!fs.existsSync(outputFolder)) {
+            fs.mkdirSync(outputFolder, { recursive: true });
+        }
+        fs.writeFileSync(outputFileName, html);
+    }
+    /**
+     * Converts ANSI color codes to HTML spans for nicer error display.
+     */
+    ansiToHtml(text) {
+        const map = {
+            '\u001b[30m': '<span style="color:black">',
+            '\u001b[31m': '<span style="color:red">',
+            '\u001b[32m': '<span style="color:green">',
+            '\u001b[33m': '<span style="color:yellow">',
+            '\u001b[34m': '<span style="color:blue">',
+            '\u001b[35m': '<span style="color:magenta">',
+            '\u001b[36m': '<span style="color:cyan">',
+            '\u001b[37m': '<span style="color:white">',
+            '\u001b[0m': '</span>',
+            '\u001b[2m': '<span style="opacity:0.5">',
+            '\u001b[22m': '</span>',
+            '\u001b[39m': '</span>',
+        };
+        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);
+        }
+        return result;
+    }
+}
+exports.A11yHtmlRenderer = A11yHtmlRenderer;

package/dist/A11yReportAssets.d.ts

@@ -0,0 +1,37 @@
+import { TestResult } from '@playwright/test/reporter';
+/**
+ * Utilities for managing and copying report assets like videos and screenshots.
+ */
+export declare class A11yReportAssets {
+    /**
+     * Copies a file from source to a destination folder.
+     */
+    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.
+     */
+    copyTestVideo(result: TestResult, destFolder: string): Promise<string>;
+    /**
+     * Copies all screenshots found in the test attachments.
+     */
+    copyScreenshots(result: TestResult, destFolder: string): string[];
+    /**
+     * Copies all PNG attachments to the report folder and returns their new names.
+     */
+    copyPngAttachments(result: TestResult, destFolder: string): {
+        path: string;
+        name: string;
+    }[];
+    /**
+     * Copies all other attachments (traces, logs, etc.) to the report folder.
+     */
+    copyAllOtherAttachments(result: TestResult, destFolder: string): {
+        path: string;
+        name: string;
+    }[];
+    /**
+     * Writes a buffer to a file in the destination folder.
+     */
+    writeBuffer(destFolder: string, fileName: string, buffer: Buffer): string;
+}