@a11y-skills/audit 0.1.0 → 0.3.0

package/dist/playwright/runTextSpacingCheck.js

@@ -0,0 +1,285 @@
+/**
+ * Text Spacing Check — WCAG 1.4.12 (Text Spacing)
+ *
+ * Captures baseline metrics, injects the WCAG 1.4.12 spacing overrides, and
+ * reports elements whose text becomes clipped (overflow:hidden) under the
+ * increased spacing.
+ *
+ * The caller is responsible for navigating the page before calling this.
+ */
+import { TEXT_SPACING_CSS, TEXT_SPACING_CLIP_TOLERANCE, TEXT_SPACING_CHECK_SELECTOR, DEFAULT_TEXT_SPACING_RESULT_FILE, DEFAULT_TEXT_SPACING_SCREENSHOT_FILE, HTML_SNIPPET_MAX_LENGTH, } from '../constants.js';
+import { buildAuditResult, normalizeTextSpacingCheck, } from '../utils/axe-format.js';
+import { saveAuditResult, takeAuditScreenshot, resolveScreenshotPath, logAuditHeader, logSummary, logIssueList, logOutputPaths, } from '../utils/test-harness.js';
+/** Collect metrics for elements with hidden overflow (browser context). */
+function collectElementMetrics(args) {
+    const { checkSelector, htmlSnippetMaxLength } = args;
+    function getHtmlSnippet(element) {
+        let html = '';
+        try {
+            html = element.outerHTML || '';
+        }
+        catch {
+            html = '';
+        }
+        if (!html) {
+            return { html: `<${element.tagName.toLowerCase()}>`, htmlTruncated: false };
+        }
+        if (html.length > htmlSnippetMaxLength) {
+            return { html: html.slice(0, htmlSnippetMaxLength), htmlTruncated: true };
+        }
+        return { html, htmlTruncated: false };
+    }
+    function getUniqueSelector(element, elementIndex) {
+        if (element.id) {
+            return `#${element.id}`;
+        }
+        const path = [];
+        let current = element;
+        while (current && current !== document.body) {
+            let selector = current.tagName.toLowerCase();
+            const parent = current.parentElement;
+            if (parent) {
+                const childIndex = Array.from(parent.children).indexOf(current) + 1;
+                selector += `:nth-child(${childIndex})`;
+            }
+            path.unshift(selector);
+            current = parent;
+        }
+        return path.length > 0 ? path.join(' > ') : `[data-index="${elementIndex}"]`;
+    }
+    function isVisible(element) {
+        const style = window.getComputedStyle(element);
+        return (style.display !== 'none' &&
+            style.visibility !== 'hidden' &&
+            parseFloat(style.opacity) > 0);
+    }
+    function hasHiddenOverflow(style) {
+        return (style.overflow === 'hidden' ||
+            style.overflow === 'clip' ||
+            style.overflowX === 'hidden' ||
+            style.overflowX === 'clip' ||
+            style.overflowY === 'hidden' ||
+            style.overflowY === 'clip');
+    }
+    const elements = document.querySelectorAll(checkSelector);
+    const metrics = [];
+    elements.forEach((element, index) => {
+        if (!isVisible(element)) {
+            return;
+        }
+        const style = window.getComputedStyle(element);
+        const hasText = element.textContent && element.textContent.trim().length > 0;
+        if (hasText && hasHiddenOverflow(style)) {
+            metrics.push({
+                selector: getUniqueSelector(element, index),
+                tagName: element.tagName.toLowerCase(),
+                ...getHtmlSnippet(element),
+                scrollWidth: element.scrollWidth,
+                scrollHeight: element.scrollHeight,
+                clientWidth: element.clientWidth,
+                clientHeight: element.clientHeight,
+                overflow: style.overflow,
+                overflowX: style.overflowX,
+                overflowY: style.overflowY,
+            });
+        }
+    });
+    return metrics;
+}
+/** Inject text spacing CSS and re-collect metrics (browser context). */
+function injectSpacingAndCollect(args) {
+    const { css, checkSelector, htmlSnippetMaxLength } = args;
+    const styleEl = document.createElement('style');
+    styleEl.id = 'wcag-text-spacing-override';
+    styleEl.textContent = css;
+    document.head.appendChild(styleEl);
+    // Force reflow
+    void document.body.offsetHeight;
+    function getHtmlSnippet(element) {
+        let html = '';
+        try {
+            html = element.outerHTML || '';
+        }
+        catch {
+            html = '';
+        }
+        if (!html) {
+            return { html: `<${element.tagName.toLowerCase()}>`, htmlTruncated: false };
+        }
+        if (html.length > htmlSnippetMaxLength) {
+            return { html: html.slice(0, htmlSnippetMaxLength), htmlTruncated: true };
+        }
+        return { html, htmlTruncated: false };
+    }
+    function getUniqueSelector(element, elementIndex) {
+        if (element.id) {
+            return `#${element.id}`;
+        }
+        const path = [];
+        let current = element;
+        while (current && current !== document.body) {
+            let selector = current.tagName.toLowerCase();
+            const parent = current.parentElement;
+            if (parent) {
+                const childIndex = Array.from(parent.children).indexOf(current) + 1;
+                selector += `:nth-child(${childIndex})`;
+            }
+            path.unshift(selector);
+            current = parent;
+        }
+        return path.length > 0 ? path.join(' > ') : `[data-index="${elementIndex}"]`;
+    }
+    function isVisible(element) {
+        const style = window.getComputedStyle(element);
+        return (style.display !== 'none' &&
+            style.visibility !== 'hidden' &&
+            parseFloat(style.opacity) > 0);
+    }
+    function hasHiddenOverflow(style) {
+        return (style.overflow === 'hidden' ||
+            style.overflow === 'clip' ||
+            style.overflowX === 'hidden' ||
+            style.overflowX === 'clip' ||
+            style.overflowY === 'hidden' ||
+            style.overflowY === 'clip');
+    }
+    const elements = document.querySelectorAll(checkSelector);
+    const metrics = [];
+    elements.forEach((element, index) => {
+        if (!isVisible(element)) {
+            return;
+        }
+        const style = window.getComputedStyle(element);
+        const hasText = element.textContent && element.textContent.trim().length > 0;
+        if (hasText && hasHiddenOverflow(style)) {
+            metrics.push({
+                selector: getUniqueSelector(element, index),
+                tagName: element.tagName.toLowerCase(),
+                ...getHtmlSnippet(element),
+                scrollWidth: element.scrollWidth,
+                scrollHeight: element.scrollHeight,
+                clientWidth: element.clientWidth,
+                clientHeight: element.clientHeight,
+                overflow: style.overflow,
+                overflowX: style.overflowX,
+                overflowY: style.overflowY,
+            });
+        }
+    });
+    return metrics;
+}
+function determineIssueType(hasHorizontalIssue, hasVerticalIssue) {
+    if (hasHorizontalIssue && hasVerticalIssue) {
+        return 'both';
+    }
+    if (hasVerticalIssue) {
+        return 'vertical-clip';
+    }
+    return 'horizontal-clip';
+}
+function detectClippingIssues(beforeMetrics, afterMetrics, tolerance) {
+    const beforeMap = new Map();
+    beforeMetrics.forEach((m) => beforeMap.set(m.selector, m));
+    const issues = [];
+    afterMetrics.forEach((after) => {
+        const before = beforeMap.get(after.selector);
+        const defaultBefore = {
+            scrollWidth: after.clientWidth,
+            scrollHeight: after.clientHeight,
+            clientWidth: after.clientWidth,
+            clientHeight: after.clientHeight,
+        };
+        const beforeData = before || defaultBefore;
+        const horizontalClipBefore = beforeData.scrollWidth > beforeData.clientWidth + tolerance;
+        const horizontalClipAfter = after.scrollWidth > after.clientWidth + tolerance;
+        const verticalClipBefore = beforeData.scrollHeight > beforeData.clientHeight + tolerance;
+        const verticalClipAfter = after.scrollHeight > after.clientHeight + tolerance;
+        const newHorizontalClip = !horizontalClipBefore && horizontalClipAfter;
+        const newVerticalClip = !verticalClipBefore && verticalClipAfter;
+        const worsenedHorizontalClip = horizontalClipBefore &&
+            horizontalClipAfter &&
+            after.scrollWidth - after.clientWidth >
+                beforeData.scrollWidth - beforeData.clientWidth + tolerance;
+        const worsenedVerticalClip = verticalClipBefore &&
+            verticalClipAfter &&
+            after.scrollHeight - after.clientHeight >
+                beforeData.scrollHeight - beforeData.clientHeight + tolerance;
+        const hasHorizontalIssue = newHorizontalClip || worsenedHorizontalClip;
+        const hasVerticalIssue = newVerticalClip || worsenedVerticalClip;
+        if (hasHorizontalIssue || hasVerticalIssue) {
+            issues.push({
+                selector: after.selector,
+                tagName: after.tagName,
+                html: after.html,
+                htmlTruncated: after.htmlTruncated,
+                beforeMetrics: {
+                    scrollWidth: beforeData.scrollWidth,
+                    scrollHeight: beforeData.scrollHeight,
+                    clientWidth: beforeData.clientWidth,
+                    clientHeight: beforeData.clientHeight,
+                },
+                afterMetrics: {
+                    scrollWidth: after.scrollWidth,
+                    scrollHeight: after.scrollHeight,
+                    clientWidth: after.clientWidth,
+                    clientHeight: after.clientHeight,
+                },
+                overflow: after.overflow,
+                overflowX: after.overflowX,
+                overflowY: after.overflowY,
+                issueType: determineIssueType(hasHorizontalIssue, hasVerticalIssue),
+            });
+        }
+    });
+    return issues;
+}
+/**
+ * Run the text spacing check against the current page, write the result JSON
+ * (and optionally a screenshot), and return the parsed result.
+ */
+export async function runTextSpacingCheck(options) {
+    const { page, tolerance = TEXT_SPACING_CLIP_TOLERANCE, screenshot = false, ...location } = options;
+    const beforeMetrics = await page.evaluate(collectElementMetrics, {
+        checkSelector: TEXT_SPACING_CHECK_SELECTOR,
+        htmlSnippetMaxLength: HTML_SNIPPET_MAX_LENGTH,
+    });
+    const afterMetrics = await page.evaluate(injectSpacingAndCollect, {
+        css: TEXT_SPACING_CSS,
+        checkSelector: TEXT_SPACING_CHECK_SELECTOR,
+        htmlSnippetMaxLength: HTML_SNIPPET_MAX_LENGTH,
+    });
+    const clippedElements = detectClippingIssues(beforeMetrics, afterMetrics, tolerance);
+    const details = {
+        clippedElements,
+        totalElementsChecked: afterMetrics.length,
+    };
+    const result = buildAuditResult({
+        source: 'text-spacing-check',
+        url: page.url(),
+        details,
+        buckets: normalizeTextSpacingCheck(details),
+    });
+    logAuditHeader('Text Spacing Check Results', 'WCAG 1.4.12', result.url);
+    logSummary({
+        'Elements with overflow:hidden checked': details.totalElementsChecked,
+        'Elements with clipping issues': details.clippedElements.length,
+    });
+    logIssueList('Clipped Elements', details.clippedElements, (el, i) => [
+        `${i + 1}. <${el.tagName}> "${el.selector}"`,
+        `   Issue: ${el.issueType}`,
+        `   Before: ${el.beforeMetrics.scrollWidth}x${el.beforeMetrics.scrollHeight} in ${el.beforeMetrics.clientWidth}x${el.beforeMetrics.clientHeight}`,
+        `   After:  ${el.afterMetrics.scrollWidth}x${el.afterMetrics.scrollHeight} in ${el.afterMetrics.clientWidth}x${el.afterMetrics.clientHeight}`,
+    ]);
+    const resolvedPath = saveAuditResult(result, {
+        ...location,
+        defaultFile: DEFAULT_TEXT_SPACING_RESULT_FILE,
+    });
+    let screenshotPath;
+    if (screenshot) {
+        screenshotPath = await takeAuditScreenshot(page, {
+            path: resolveScreenshotPath(resolvedPath, DEFAULT_TEXT_SPACING_SCREENSHOT_FILE),
+        });
+    }
+    logOutputPaths(resolvedPath, screenshotPath);
+    return result;
+}

package/dist/playwright/runTimeLimitDetector.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Time Limit Detector — WCAG 2.2.1 (Timing Adjustable)
+ *
+ * Hooks setTimeout/setInterval (via an init script injected BEFORE navigation),
+ * checks meta refresh tags, and scans visible text for countdown/timeout
+ * keywords.
+ *
+ * Because the timer hook must be installed before page scripts run, this
+ * function OWNS navigation: pass an un-navigated `page` and a `targetUrl`
+ * (option → `TEST_PAGE` env → required). Unlike the focus check it does not
+ * need a fresh context per attempt, so it stays page-based.
+ */
+import type { Page } from '@playwright/test';
+import type { TimeLimitDetectorResult } from '../types.js';
+import { type OutputLocationOptions } from '../utils/test-harness.js';
+export interface RunTimeLimitDetectorOptions extends OutputLocationOptions {
+    /** An un-navigated page (this function navigates after installing the timer hook). */
+    page: Page;
+    /** Target URL. Falls back to the `TEST_PAGE` env var; required. */
+    targetUrl?: string;
+    /** Minimum timer delay to capture, ms (default: 10000). */
+    minMs?: number;
+    /** Maximum timer delay to capture, ms (default: 600000). */
+    maxMs?: number;
+    /** How long to wait after load for timers to register, ms (default: 2000). */
+    settleMs?: number;
+}
+/**
+ * Run the time limit detector, write the result JSON, and return the result.
+ */
+export declare function runTimeLimitDetector(options: RunTimeLimitDetectorOptions): Promise<TimeLimitDetectorResult>;

package/dist/playwright/runTimeLimitDetector.js

@@ -0,0 +1,219 @@
+/**
+ * Time Limit Detector — WCAG 2.2.1 (Timing Adjustable)
+ *
+ * Hooks setTimeout/setInterval (via an init script injected BEFORE navigation),
+ * checks meta refresh tags, and scans visible text for countdown/timeout
+ * keywords.
+ *
+ * Because the timer hook must be installed before page scripts run, this
+ * function OWNS navigation: pass an un-navigated `page` and a `targetUrl`
+ * (option → `TEST_PAGE` env → required). Unlike the focus check it does not
+ * need a fresh context per attempt, so it stays page-based.
+ */
+import { TIME_LIMIT_KEYWORDS, TIME_LIMIT_THRESHOLD_MS, TIME_LIMIT_MIN_MS, DEFAULT_TIME_LIMIT_RESULT_FILE, HTML_SNIPPET_MAX_LENGTH, } from '../constants.js';
+import { buildAuditResult, normalizeTimeLimitDetector, } from '../utils/axe-format.js';
+import { saveAuditResult, requireTargetUrl, logAuditHeader, logSummary, logIssueList, logOutputPaths, } from '../utils/test-harness.js';
+/** Timer hook injected before page load (browser context). */
+function createTimerHookScript(args) {
+    const { minMs, maxMs } = args;
+    const capturedTimers = [];
+    const originalSetTimeout = window.setTimeout;
+    const originalSetInterval = window.setInterval;
+    window.setTimeout = function (callback, delay, ...rest) {
+        const actualDelay = delay || 0;
+        if (actualDelay >= minMs && actualDelay <= maxMs) {
+            let callStack = null;
+            try {
+                throw new Error();
+            }
+            catch (e) {
+                callStack =
+                    e.stack?.split('\n').slice(2, 5).join('\n') || null;
+            }
+            capturedTimers.push({ type: 'setTimeout', delayMs: actualDelay, callStack });
+        }
+        return originalSetTimeout.apply(window, [
+            callback,
+            delay,
+            ...rest,
+        ]);
+    };
+    window.setInterval = function (callback, delay, ...rest) {
+        const actualDelay = delay || 0;
+        if (actualDelay >= minMs && actualDelay <= maxMs) {
+            let callStack = null;
+            try {
+                throw new Error();
+            }
+            catch (e) {
+                callStack =
+                    e.stack?.split('\n').slice(2, 5).join('\n') || null;
+            }
+            capturedTimers.push({ type: 'setInterval', delayMs: actualDelay, callStack });
+        }
+        return originalSetInterval.apply(window, [
+            callback,
+            delay,
+            ...rest,
+        ]);
+    };
+    window.__capturedTimers = capturedTimers;
+}
+/** Detect meta refresh + countdown indicators (browser context). */
+function detectTimeLimitIndicators(args) {
+    const { keywords, htmlSnippetMaxLength } = args;
+    function getHtmlSnippet(element) {
+        let html = '';
+        try {
+            html = element.outerHTML || '';
+        }
+        catch {
+            html = '';
+        }
+        if (!html) {
+            return { html: `<${element.tagName.toLowerCase()}>`, htmlTruncated: false };
+        }
+        if (html.length > htmlSnippetMaxLength) {
+            return { html: html.slice(0, htmlSnippetMaxLength), htmlTruncated: true };
+        }
+        return { html, htmlTruncated: false };
+    }
+    function getUniqueSelector(element, elementIndex) {
+        if (element.id) {
+            return `#${element.id}`;
+        }
+        const path = [];
+        let current = element;
+        while (current && current !== document.body) {
+            let selector = current.tagName.toLowerCase();
+            const parent = current.parentElement;
+            if (parent) {
+                const childIndex = Array.from(parent.children).indexOf(current) + 1;
+                selector += `:nth-child(${childIndex})`;
+            }
+            path.unshift(selector);
+            current = parent;
+        }
+        return path.length > 0 ? path.join(' > ') : `[data-index="${elementIndex}"]`;
+    }
+    const metaRefresh = [];
+    const metaTags = document.querySelectorAll('meta[http-equiv="refresh"]');
+    metaTags.forEach((meta) => {
+        const content = meta.getAttribute('content');
+        if (content) {
+            const trimmed = content.trim();
+            const match = trimmed.match(/^(\d+)\s*(?:;\s*url\s*=\s*(.+))?$/i);
+            if (match) {
+                metaRefresh.push({
+                    content,
+                    seconds: parseInt(match[1] ?? '0', 10),
+                    url: match[2]?.trim() || null,
+                    ...getHtmlSnippet(meta),
+                });
+            }
+        }
+    });
+    const countdownIndicators = [];
+    const visibleText = document.body.innerText || '';
+    const lowerText = visibleText.toLowerCase();
+    for (const keyword of keywords) {
+        if (!lowerText.includes(keyword.toLowerCase())) {
+            continue;
+        }
+        const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, null);
+        let node;
+        let elementIndex = 0;
+        while ((node = walker.nextNode())) {
+            if (node.textContent?.toLowerCase().includes(keyword.toLowerCase())) {
+                const parent = node.parentElement;
+                if (parent) {
+                    const fullText = parent.textContent?.trim().slice(0, 150) || '';
+                    const alreadyAdded = countdownIndicators.some((c) => c.text === fullText);
+                    if (!alreadyAdded && fullText.length > 0) {
+                        countdownIndicators.push({
+                            selector: getUniqueSelector(parent, elementIndex),
+                            text: fullText,
+                            tagName: parent.tagName.toLowerCase(),
+                            ...getHtmlSnippet(parent),
+                        });
+                    }
+                }
+            }
+            elementIndex++;
+        }
+    }
+    return { metaRefresh, countdownIndicators };
+}
+/**
+ * Run the time limit detector, write the result JSON, and return the result.
+ */
+export async function runTimeLimitDetector(options) {
+    const { page, targetUrl: targetUrlOption, minMs = TIME_LIMIT_MIN_MS, maxMs = TIME_LIMIT_THRESHOLD_MS, settleMs = 2000, ...location } = options;
+    const targetUrl = requireTargetUrl(targetUrlOption);
+    await page.addInitScript(createTimerHookScript, { minMs, maxMs });
+    await page.goto(targetUrl, { waitUntil: 'networkidle' });
+    await page.waitForTimeout(settleMs);
+    const timers = await page.evaluate(() => {
+        return (window.__capturedTimers || []);
+    });
+    const indicators = await page.evaluate(detectTimeLimitIndicators, {
+        keywords: [...TIME_LIMIT_KEYWORDS],
+        htmlSnippetMaxLength: HTML_SNIPPET_MAX_LENGTH,
+    });
+    const hasTimeLimits = indicators.metaRefresh.length > 0 ||
+        timers.length > 0 ||
+        indicators.countdownIndicators.length > 0;
+    const details = {
+        metaRefresh: indicators.metaRefresh,
+        timers,
+        countdownIndicators: indicators.countdownIndicators,
+        hasTimeLimits,
+    };
+    const result = buildAuditResult({
+        source: 'time-limit-detector',
+        url: page.url(),
+        details,
+        buckets: normalizeTimeLimitDetector(details),
+    });
+    logAuditHeader('Time Limit Detection Results', 'WCAG 2.2.1', result.url);
+    logSummary({
+        'Meta refresh tags': details.metaRefresh.length,
+        [`Timers detected (${minMs / 1000}s - ${maxMs / 1000}s)`]: details.timers.length,
+        'Countdown text indicators': details.countdownIndicators.length,
+        'Time limits detected': details.hasTimeLimits,
+    });
+    logIssueList('Meta Refresh', details.metaRefresh, (meta, i) => {
+        const lines = [
+            `${i + 1}. content="${meta.content}"`,
+            `   Refresh in ${meta.seconds} seconds`,
+        ];
+        if (meta.url) {
+            lines.push(`   Redirects to: ${meta.url}`);
+        }
+        return lines;
+    });
+    logIssueList('Detected Timers', details.timers, (timer, i) => {
+        const lines = [
+            `${i + 1}. ${timer.type} - ${timer.delayMs}ms (${(timer.delayMs / 1000).toFixed(1)}s)`,
+        ];
+        if (timer.callStack) {
+            lines.push(`   Stack: ${timer.callStack.split('\n')[0]}`);
+        }
+        return lines;
+    });
+    logIssueList('Countdown Indicators', details.countdownIndicators, (indicator, i) => {
+        const truncatedText = indicator.text.length > 80
+            ? indicator.text.slice(0, 80) + '...'
+            : indicator.text;
+        return [
+            `${i + 1}. <${indicator.tagName}> "${indicator.selector}"`,
+            `   Text: "${truncatedText}"`,
+        ];
+    }, 5);
+    const resolvedPath = saveAuditResult(result, {
+        ...location,
+        defaultFile: DEFAULT_TIME_LIMIT_RESULT_FILE,
+    });
+    logOutputPaths(resolvedPath);
+    return result;
+}

package/dist/playwright/runZoomCheck.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Zoom 200% Check — WCAG 1.4.4 (Resize Text)
+ *
+ * Sets a standard viewport (default 1280x720), applies 200% zoom via the CSS
+ * `zoom` property, then detects horizontal scrolling and elements whose content
+ * becomes clipped (overflow:hidden) under zoom.
+ *
+ * If a `targetUrl` (or the `TEST_PAGE` env var) is available, this function
+ * owns navigation: it sets the base viewport BEFORE navigating (matching the
+ * legacy script, so pages that read the viewport at load time behave the same).
+ * Otherwise it operates on the already-navigated page (just sets the viewport).
+ *
+ * Limitations:
+ * - CSS zoom is engine-specific; actual browser zoom may behave differently
+ * - Does not verify responsive breakpoint behavior
+ * - Manual verification needed for complex interactions at zoom
+ */
+import type { Page } from '@playwright/test';
+import type { ZoomCheckResult } from '../types.js';
+import { type OutputLocationOptions } from '../utils/test-harness.js';
+export interface RunZoomCheckOptions extends OutputLocationOptions {
+    /** Page to run the check on (navigated by this function if `targetUrl`/`TEST_PAGE` is set). */
+    page: Page;
+    /**
+     * Target URL. If provided (or `TEST_PAGE` is set), the function sets the base
+     * viewport then navigates, for results identical to the legacy script. If
+     * omitted, the page is assumed already navigated.
+     */
+    targetUrl?: string;
+    /** Base viewport applied before zoom (default: 1280x720). */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Whether to capture a screenshot next to the result file (default: false). */
+    screenshot?: boolean;
+}
+/**
+ * Run the zoom 200% check against the current page, write the result JSON
+ * (and optionally a screenshot), and return the parsed result.
+ */
+export declare function runZoomCheck(options: RunZoomCheckOptions): Promise<ZoomCheckResult>;