snap-ally 0.2.7-beta → 0.3.0

package/dist/core/A11yHtmlRenderer.js

@@ -0,0 +1,118 @@
+"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"));
+/**
+ * Handles the rendering of HTML reports using static templates and JSON data injection.
+ */
+class A11yHtmlRenderer {
+    /**
+     * 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 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/core/A11yHtmlRenderer.js)
+        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}`);
+        }
+        if (!fs.existsSync(outputFolder)) {
+            fs.mkdirSync(outputFolder, { recursive: true });
+        }
+        // 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, 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
+        const outCssPath = path.join(outputDir, 'global-report-styles.css');
+        const outJsPath = path.join(outputDir, 'report-app.js');
+        try {
+            if (fs.existsSync(cssPath))
+                fs.copyFileSync(cssPath, outCssPath);
+        }
+        catch (e) {
+            console.error('Error copying CSS:', e);
+        }
+        try {
+            if (fs.existsSync(jsPath))
+                fs.copyFileSync(jsPath, outJsPath);
+        }
+        catch (e) {
+            console.error('Error copying JS:', e);
+        }
+    }
+    /**
+     * 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/core/A11yReportAssets.d.ts

@@ -0,0 +1,30 @@
+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 all video attachments to the report folder for portability.
+     * @returns An array of filenames written to the destination folder.
+     */
+    copyVideos(result: TestResult, destFolder: string): string[];
+    /**
+     * Copies all screenshots found in the test attachments.
+     */
+    copyScreenshots(result: TestResult, destFolder: string): string[];
+    /**
+     * Copies all other attachments (traces, logs, etc.) to the report folder.
+     */
+    copyAllOtherAttachments(result: TestResult, destFolder: string): {
+        path: string;
+        name: string;
+    }[];
+    /**
+     * Persists an in-memory buffer to a file in the destination folder.
+     */
+    saveBuffer(destFolder: string, fileName: string, buffer: Buffer): string;
+}

package/dist/core/A11yReportAssets.js

@@ -0,0 +1,127 @@
+"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.A11yReportAssets = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Utilities for managing and copying report assets like videos and screenshots.
+ */
+class A11yReportAssets {
+    /**
+     * Copies a file from source to a destination folder.
+     */
+    copyToFolder(destFolder, srcPath, fileName) {
+        if (!srcPath || !fs.existsSync(srcPath)) {
+            return '';
+        }
+        const name = fileName || path.basename(srcPath);
+        const destFile = path.join(destFolder, name);
+        if (!fs.existsSync(destFolder)) {
+            fs.mkdirSync(destFolder, { recursive: true });
+        }
+        fs.copyFileSync(srcPath, destFile);
+        return name;
+    }
+    /**
+     * Copies all video attachments to the report folder for portability.
+     * @returns An array of filenames written to the destination folder.
+     */
+    copyVideos(result, destFolder) {
+        return result.attachments
+            .filter((a) => (a.name === 'video' || (a.contentType || '').startsWith('video/')) && a.path)
+            .map((attachment) => this.copyToFolder(destFolder, attachment.path))
+            .filter((p) => !!p);
+    }
+    /**
+     * Copies all screenshots found in the test attachments.
+     */
+    copyScreenshots(result, destFolder) {
+        return result.attachments
+            .filter((a) => a.name === 'screenshot' ||
+            a.name.endsWith('.png') ||
+            (a.contentType || '').startsWith('image/'))
+            .map((a) => {
+            if (a.path) {
+                return this.copyToFolder(destFolder, a.path, a.name !== 'screenshot' ? a.name : undefined);
+            }
+            else if (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.saveBuffer(destFolder, name, a.body);
+            }
+            return '';
+        })
+            .filter((path) => path !== '');
+    }
+    /**
+     * Copies all other attachments (traces, logs, etc.) to the report folder.
+     */
+    copyAllOtherAttachments(result, destFolder) {
+        const excludedNames = ['screenshot', 'video', 'A11y'];
+        return result.attachments
+            .filter((a) => !excludedNames.includes(a.name) &&
+            !a.name.toLowerCase().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);
+            }
+            else if (a.body) {
+                name = this.saveBuffer(destFolder, a.name, a.body);
+            }
+            return name ? { path: name, name: a.name } : null;
+        })
+            .filter((item) => item !== null);
+    }
+    /**
+     * Persists an in-memory buffer to a file in the destination folder.
+     */
+    saveBuffer(destFolder, fileName, buffer) {
+        if (!fs.existsSync(destFolder)) {
+            fs.mkdirSync(destFolder, { recursive: true });
+        }
+        const destFile = path.join(destFolder, fileName);
+        fs.writeFileSync(destFile, buffer);
+        return fileName;
+    }
+}
+exports.A11yReportAssets = A11yReportAssets;

package/dist/core/A11yScanner.d.ts

@@ -0,0 +1,8 @@
+import type { Page, TestInfo } from '@playwright/test';
+import { A11yScannerOptions } from '../models';
+/**
+ * Performs an accessibility audit using Axe and Lighthouse.
+ */
+export declare function scanA11y(page: Page, testInfo: TestInfo, options?: A11yScannerOptions): Promise<void>;
+/** Alias for backward compatibility */
+export declare const checkAccessibility: typeof scanA11y;

package/dist/core/A11yScanner.js

@@ -0,0 +1,178 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkAccessibility = void 0;
+exports.scanA11y = scanA11y;
+const playwright_1 = __importDefault(require("@axe-core/playwright"));
+const A11yVisualReporter_1 = require("./A11yVisualReporter");
+const models_1 = require("../models");
+const A11yTimeUtils_1 = require("../utils/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, _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 A11yVisualReporter_1.A11yVisualReporter(page);
+    // Configure Axe
+    let axeBuilder = new playwright_1.default({ page });
+    const target = options.include || options.box;
+    if (target) {
+        if (typeof target === 'string') {
+            axeBuilder = axeBuilder.include(target);
+        }
+        else {
+            // AxeBuilder for playwright also supports locators/elements in include
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            axeBuilder = axeBuilder.include(target);
+        }
+    }
+    if (options.rules) {
+        axeBuilder = axeBuilder.options({ rules: options.rules });
+    }
+    if (options.tags) {
+        axeBuilder = axeBuilder.withTags(options.tags);
+    }
+    if (options.axeOptions) {
+        axeBuilder = axeBuilder.options(options.axeOptions);
+    }
+    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}`;
+        // 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, color]) => {
+                console.log(`%c ${mainMsg}`, `color: ${color}; font-weight: bold; font-size: 12px;`);
+                details.forEach((msg) => console.log(msg));
+            }, [mainMsg, detailMessages, models_1.DEFAULT_COLORS.serious]);
+        }
+    }
+    // Fail the test if violations found (softly)
+    // Dynamically require to avoid eager loading @playwright/test during config evaluation
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { expect } = require('@playwright/test');
+    expect
+        .soft(violationCount, `Accessibility audit failed with ${violationCount} violations.`)
+        .toBe(0);
+    // Run Axe Audit
+    const errors = [];
+    // Process violations for the report
+    for (const violation of axeResults.violations) {
+        let errorIdx = 0;
+        const targets = [];
+        const severityColor = (0, models_1.getSeverityColor)(violation.impact);
+        for (const node of violation.nodes) {
+            for (const selector of node.target) {
+                const elementSelector = selector.toString();
+                const locator = page.locator(elementSelector);
+                await overlay.showBanner({ id: violation.id, help: violation.help }, severityColor);
+                if (await locator.isVisible()) {
+                    await overlay.highlightElement(elementSelector, severityColor);
+                    // Allow a small time for overlay highlight to be visible in video
+                    // eslint-disable-next-line playwright/no-wait-for-timeout
+                    await page.waitForTimeout(100);
+                    const screenshotName = `a11y-${violation.id}-${errorIdx++}.png`;
+                    const buffer = await overlay.captureScreenshot(screenshotName, testInfo);
+                    // Capture execution steps for context
+                    const excluded = new Set([
+                        'Pre Condition',
+                        'Post Condition',
+                        'Description',
+                        'A11y',
+                    ]);
+                    const contextSteps = (testInfo.annotations || [])
+                        .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({
+                        element: elementSelector,
+                        snippet: friendlySnippet,
+                        html: nodeHtml,
+                        screenshot: screenshotName,
+                        steps: contextSteps,
+                        stepsJson: JSON.stringify(contextSteps),
+                        screenshotBase64: buffer.toString('base64'),
+                    });
+                    await overlay.removeHighlight();
+                }
+            }
+        }
+        errors.push({
+            id: violation.id,
+            description: violation.description,
+            severity: violation.impact || 'unknown',
+            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',
+            total: targets.length || violation.nodes.length, // Fallback to node count if no screenshots
+            target: targets,
+        });
+    }
+    // Prepare data for the reporter
+    const reportData = {
+        pageKey,
+        pageUrl: page.url(),
+        accessibilityScore: 0, // No longer used, derivation from Lighthouse removed
+        a11yErrors: errors,
+        criticalColor: models_1.DEFAULT_COLORS.critical,
+        seriousColor: models_1.DEFAULT_COLORS.serious,
+        moderateColor: models_1.DEFAULT_COLORS.moderate,
+        minorColor: models_1.DEFAULT_COLORS.minor,
+        adoOrganization: process.env.ADO_ORGANIZATION || '',
+        adoProject: process.env.ADO_PROJECT || '',
+        timestamp: A11yTimeUtils_1.A11yTimeUtils.formatDate(new Date()),
+    };
+    await overlay.attachData(testInfo, 'A11y', JSON.stringify(reportData));
+    await overlay.clean();
+}
+/** Alias for backward compatibility */
+exports.checkAccessibility = scanA11y;

package/dist/core/A11yVisualReporter.d.ts

@@ -0,0 +1,50 @@
+import type { Page, TestInfo } from '@playwright/test';
+/**
+ * Manages visual feedback on the page during an accessibility scan.
+ * Handles element highlights, violation banners, and report attachments.
+ */
+export declare class A11yVisualReporter {
+    private readonly page;
+    private readonly rootId;
+    private static readonly BANNER_ID;
+    private static readonly HIGHLIGHT_ID;
+    constructor(page: Page);
+    /**
+     * Shows a violation banner at the bottom of the page.
+     */
+    showBanner(violation: {
+        id: string;
+        help: string;
+    }, color: string): Promise<void>;
+    /**
+     * Highlights an element on the page.
+     */
+    highlightElement(selector: string, color: string): Promise<void>;
+    /**
+     * Removes all visual feedback from the page.
+     */
+    clean(): Promise<void>;
+    /**
+     * Removes the element highlight.
+     */
+    removeHighlight(): Promise<void>;
+    /**
+     * Attaches JSON data to the test report.
+     */
+    attachData(testInfo: TestInfo, name: string, data: string): Promise<void>;
+    /**
+     * Captures and attaches a screenshot to the test report.
+     */
+    captureScreenshot(name: string, testInfo: TestInfo): Promise<Buffer>;
+    /**
+     * Injects helper functions into the page context.
+     */
+    private ensureHelpers;
+    private safeEvaluate;
+}
+declare global {
+    interface Window {
+        snapAllyGetRoot: (id: string) => ShadowRoot;
+        snapAllyToAlpha: (color: string, alpha: number) => string;
+    }
+}