@a11y-skills/audit 0.1.0 → 0.3.0

package/dist/playwright/runOrientationCheck.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Orientation Check — WCAG 1.3.4 (Orientation)
+ *
+ * Renders the page in portrait (375x667) and landscape (667x375), detecting
+ * "rotate device" messages/overlays and whether the main content is hidden in
+ * either orientation. Reports if the page restricts content to a specific
+ * orientation.
+ *
+ * This function OWNS navigation: it sets each viewport then navigates to the
+ * target URL for that orientation (two full navigations, not a reload), so the
+ * page lays out fresh for each orientation.
+ *
+ * Limitations:
+ * - Heuristics may miss CSS-only orientation restrictions
+ * - Cannot detect JavaScript-based orientation detection without visual indicators
+ * - Manual verification needed for exceptions (e.g., camera apps)
+ */
+import type { Page } from '@playwright/test';
+import type { OrientationCheckResult } from '../types.js';
+import { type OutputLocationOptions } from '../utils/test-harness.js';
+export interface RunOrientationCheckOptions extends OutputLocationOptions {
+    /**
+     * A page to drive. This check navigates the page itself (once per
+     * orientation), so the page does not need to be pre-navigated.
+     */
+    page: Page;
+    /** Target URL to audit. Falls back to the `TEST_PAGE` env var. */
+    targetUrl?: string;
+    /**
+     * Whether to capture portrait/landscape screenshots next to the result file
+     * (default: false).
+     */
+    screenshot?: boolean;
+}
+/**
+ * Run the orientation check, navigating the page in both portrait and landscape,
+ * write the result JSON (and optionally screenshots), and return the parsed
+ * result.
+ */
+export declare function runOrientationCheck(options: RunOrientationCheckOptions): Promise<OrientationCheckResult>;

package/dist/playwright/runOrientationCheck.js

@@ -0,0 +1,170 @@
+/**
+ * Orientation Check — WCAG 1.3.4 (Orientation)
+ *
+ * Renders the page in portrait (375x667) and landscape (667x375), detecting
+ * "rotate device" messages/overlays and whether the main content is hidden in
+ * either orientation. Reports if the page restricts content to a specific
+ * orientation.
+ *
+ * This function OWNS navigation: it sets each viewport then navigates to the
+ * target URL for that orientation (two full navigations, not a reload), so the
+ * page lays out fresh for each orientation.
+ *
+ * Limitations:
+ * - Heuristics may miss CSS-only orientation restrictions
+ * - Cannot detect JavaScript-based orientation detection without visual indicators
+ * - Manual verification needed for exceptions (e.g., camera apps)
+ */
+import { ORIENTATION_VIEWPORTS, ORIENTATION_LOCK_KEYWORDS, MAIN_CONTENT_SELECTORS, DEFAULT_ORIENTATION_RESULT_FILE, DEFAULT_ORIENTATION_PORTRAIT_SCREENSHOT_FILE, DEFAULT_ORIENTATION_LANDSCAPE_SCREENSHOT_FILE, } from '../constants.js';
+import { buildAuditResult, normalizeOrientationCheck, } from '../utils/axe-format.js';
+import { saveAuditResult, resolveOutputPath, takeAuditScreenshot, resolveScreenshotPath, requireTargetUrl, logAuditHeader, logOutputPaths, } from '../utils/test-harness.js';
+/** Capture orientation state in browser context. */
+function captureOrientationState(args) {
+    const { lockKeywords, mainContentSelectors } = args;
+    const bodyWidth = document.body.scrollWidth;
+    const bodyHeight = document.body.scrollHeight;
+    const visibleText = document.body.innerText || '';
+    const visibleTextLength = visibleText.length;
+    const lowerText = visibleText.toLowerCase();
+    // Search for lock message keywords
+    let lockMessageFound = false;
+    let lockMessageText = null;
+    for (const keyword of lockKeywords) {
+        if (lowerText.includes(keyword.toLowerCase())) {
+            lockMessageFound = true;
+            const allElements = document.querySelectorAll('*');
+            for (const el of allElements) {
+                const text = el.textContent?.toLowerCase() || '';
+                if (text.includes(keyword.toLowerCase()) && text.length < 200) {
+                    lockMessageText = el.textContent?.trim().slice(0, 100) || null;
+                    break;
+                }
+            }
+            break;
+        }
+    }
+    // Check if main content is hidden
+    let mainContentHidden = false;
+    for (const selector of mainContentSelectors) {
+        const mainEl = document.querySelector(selector);
+        if (mainEl) {
+            const style = window.getComputedStyle(mainEl);
+            const isHidden = style.display === 'none' ||
+                style.visibility === 'hidden' ||
+                parseFloat(style.opacity) === 0;
+            if (isHidden) {
+                mainContentHidden = true;
+                break;
+            }
+            const rect = mainEl.getBoundingClientRect();
+            if (rect.width < 50 || rect.height < 50) {
+                mainContentHidden = true;
+                break;
+            }
+        }
+    }
+    return {
+        lockMessageFound,
+        lockMessageText,
+        mainContentHidden,
+        bodyWidth,
+        bodyHeight,
+        visibleTextLength,
+    };
+}
+/** Determine where orientation lock was detected. */
+function determineLockLocation(portraitHasLock, landscapeHasLock) {
+    if (portraitHasLock && landscapeHasLock) {
+        return 'both';
+    }
+    if (portraitHasLock) {
+        return 'portrait';
+    }
+    if (landscapeHasLock) {
+        return 'landscape';
+    }
+    return 'none';
+}
+/** Log orientation state for a specific orientation. */
+function logOrientationState(label, viewport, state) {
+    console.log(`\n${label} (${viewport.width}x${viewport.height}):`);
+    console.log(`  Lock message found: ${state.lockMessageFound ? 'YES' : 'No'}`);
+    if (state.lockMessageText) {
+        console.log(`  Message: "${state.lockMessageText}"`);
+    }
+    console.log(`  Main content hidden: ${state.mainContentHidden ? 'YES' : 'No'}`);
+    console.log(`  Body size: ${state.bodyWidth}x${state.bodyHeight}`);
+}
+/**
+ * Run the orientation check, navigating the page in both portrait and landscape,
+ * write the result JSON (and optionally screenshots), and return the parsed
+ * result.
+ */
+export async function runOrientationCheck(options) {
+    const { page, targetUrl, screenshot = false, ...location } = options;
+    const url = requireTargetUrl(targetUrl);
+    const checkArgs = {
+        lockKeywords: [...ORIENTATION_LOCK_KEYWORDS],
+        mainContentSelectors: [...MAIN_CONTENT_SELECTORS],
+    };
+    // Resolve where the result will be written up front so screenshots can be
+    // placed next to it (mirrors saveAuditResult's resolution).
+    const resolvedPath = resolveOutputPath({
+        ...location,
+        defaultFile: DEFAULT_ORIENTATION_RESULT_FILE,
+    });
+    // Test portrait orientation
+    await page.setViewportSize(ORIENTATION_VIEWPORTS.portrait);
+    await page.goto(url, { waitUntil: 'networkidle' });
+    const portraitState = await page.evaluate(captureOrientationState, checkArgs);
+    let portraitScreenshotPath;
+    if (screenshot) {
+        portraitScreenshotPath = await takeAuditScreenshot(page, {
+            path: resolveScreenshotPath(resolvedPath, DEFAULT_ORIENTATION_PORTRAIT_SCREENSHOT_FILE),
+        });
+    }
+    // Test landscape orientation
+    await page.setViewportSize(ORIENTATION_VIEWPORTS.landscape);
+    await page.goto(url, { waitUntil: 'networkidle' });
+    const landscapeState = await page.evaluate(captureOrientationState, checkArgs);
+    let landscapeScreenshotPath;
+    if (screenshot) {
+        landscapeScreenshotPath = await takeAuditScreenshot(page, {
+            path: resolveScreenshotPath(resolvedPath, DEFAULT_ORIENTATION_LANDSCAPE_SCREENSHOT_FILE),
+        });
+    }
+    // Determine lock status
+    const portraitHasLock = portraitState.lockMessageFound || portraitState.mainContentHidden;
+    const landscapeHasLock = landscapeState.lockMessageFound || landscapeState.mainContentHidden;
+    const hasOrientationLock = portraitHasLock || landscapeHasLock;
+    const lockDetectedIn = determineLockLocation(portraitHasLock, landscapeHasLock);
+    const details = {
+        portrait: portraitState,
+        landscape: landscapeState,
+        hasOrientationLock,
+        lockDetectedIn,
+    };
+    const result = buildAuditResult({
+        source: 'orientation-check',
+        url: page.url(),
+        details,
+        buckets: normalizeOrientationCheck(details),
+    });
+    // Output results
+    logAuditHeader('Orientation Check Results', 'WCAG 1.3.4', result.url);
+    logOrientationState('Portrait', ORIENTATION_VIEWPORTS.portrait, details.portrait);
+    logOrientationState('Landscape', ORIENTATION_VIEWPORTS.landscape, details.landscape);
+    console.log(`\nOrientation lock detected: ${details.hasOrientationLock ? 'YES' : 'No'}`);
+    if (details.hasOrientationLock) {
+        console.log(`Lock detected in: ${details.lockDetectedIn}`);
+    }
+    const writtenPath = saveAuditResult(result, {
+        ...location,
+        defaultFile: DEFAULT_ORIENTATION_RESULT_FILE,
+    });
+    const screenshotPaths = [portraitScreenshotPath, landscapeScreenshotPath]
+        .filter((p) => p !== undefined)
+        .join(', ');
+    logOutputPaths(writtenPath, screenshotPaths || undefined);
+    return result;
+}

package/dist/playwright/runReflowCheck.js

@@ -13,8 +13,9 @@
  * - Cannot distinguish acceptable horizontal scroll (e.g., data tables)
  * - Does not verify functional reflow for complex widgets
  */
-import { REFLOW_VIEWPORT, REFLOW_OVERFLOW_TOLERANCE, REFLOW_CHECK_SELECTOR, REFLOW_ALLOWED_OVERFLOW_SELECTORS, DEFAULT_REFLOW_RESULT_FILE, DEFAULT_REFLOW_SCREENSHOT_FILE, } from '../constants.js';
+import { REFLOW_VIEWPORT, REFLOW_OVERFLOW_TOLERANCE, REFLOW_CHECK_SELECTOR, REFLOW_ALLOWED_OVERFLOW_SELECTORS, DEFAULT_REFLOW_RESULT_FILE, DEFAULT_REFLOW_SCREENSHOT_FILE, HTML_SNIPPET_MAX_LENGTH, } from '../constants.js';
 import { createLayoutChecker } from '../utils/layout.js';
+import { buildAuditResult, normalizeReflowCheck } from '../utils/axe-format.js';
 import { saveAuditResult, takeAuditScreenshot, resolveScreenshotPath, logAuditHeader, logSummary, logIssueList, logOutputPaths, } from '../utils/test-harness.js';
 /**
  * Run the reflow check against the current page, write the result JSON
@@ -28,27 +29,33 @@ export async function runReflowCheck(options) {
         overflowTolerance,
         checkSelector: REFLOW_CHECK_SELECTOR,
         allowedOverflowSelectors: [...REFLOW_ALLOWED_OVERFLOW_SELECTORS],
+        htmlSnippetMaxLength: HTML_SNIPPET_MAX_LENGTH,
     });
-    const result = {
-        url: page.url(),
+    const details = {
         viewport: { width: viewport.width, height: viewport.height },
         ...layoutResult,
     };
+    const result = buildAuditResult({
+        source: 'reflow-check',
+        url: page.url(),
+        details,
+        buckets: normalizeReflowCheck(details),
+    });
     // Output results
     logAuditHeader('Reflow Check Results', 'WCAG 1.4.10', result.url);
     logSummary({
-        Viewport: `${result.viewport.width}x${result.viewport.height}`,
-        'Document scroll width': `${result.documentScrollWidth}px`,
-        'Document client width': `${result.documentClientWidth}px`,
-        'Horizontal scroll': result.hasHorizontalScroll,
-        'Overflowing elements': result.overflowingElements.length,
-        'Clipped text elements': result.clippedTextElements.length,
+        Viewport: `${details.viewport.width}x${details.viewport.height}`,
+        'Document scroll width': `${details.documentScrollWidth}px`,
+        'Document client width': `${details.documentClientWidth}px`,
+        'Horizontal scroll': details.hasHorizontalScroll,
+        'Overflowing elements': details.overflowingElements.length,
+        'Clipped text elements': details.clippedTextElements.length,
     });
-    logIssueList('Overflowing Elements', result.overflowingElements, (el, i) => [
+    logIssueList('Overflowing Elements', details.overflowingElements, (el, i) => [
         `${i + 1}. <${el.tagName}> "${el.selector}"`,
         `   rect.right: ${el.rect.right}px (viewport: ${el.viewportWidth}px)`,
     ]);
-    logIssueList('Clipped Text Elements', result.clippedTextElements, (el, i) => [
+    logIssueList('Clipped Text Elements', details.clippedTextElements, (el, i) => [
         `${i + 1}. <${el.tagName}> "${el.selector}"`,
         `   scrollWidth: ${el.scrollWidth}px, clientWidth: ${el.clientWidth}px`,
         `   overflow: ${el.overflow}, overflowX: ${el.overflowX}`,

package/dist/playwright/runTargetSizeCheck.js

@@ -15,13 +15,31 @@
  * - Cannot detect all redundant target cases
  * - CSS transform may affect measurements
  */
-import { INTERACTIVE_SELECTOR, TARGET_SIZE_AA, TARGET_SIZE_AAA, INLINE_CONTEXT_TAGS, UA_CONTROLLED_INPUT_TYPES, INLINE_CONTEXT_MIN_TEXT, DEFAULT_TARGET_SIZE_RESULT_FILE, DEFAULT_TARGET_SIZE_SCREENSHOT_FILE, } from '../constants.js';
+import { INTERACTIVE_SELECTOR, TARGET_SIZE_AA, TARGET_SIZE_AAA, INLINE_CONTEXT_TAGS, UA_CONTROLLED_INPUT_TYPES, INLINE_CONTEXT_MIN_TEXT, DEFAULT_TARGET_SIZE_RESULT_FILE, DEFAULT_TARGET_SIZE_SCREENSHOT_FILE, HTML_SNIPPET_MAX_LENGTH, } from '../constants.js';
+import { buildAuditResult, normalizeTargetSizeCheck, } from '../utils/axe-format.js';
 import { saveAuditResult, takeAuditScreenshot, resolveScreenshotPath, logAuditHeader, logSummary, logIssueList, logOutputPaths, } from '../utils/test-harness.js';
 import { addPageAnnotations } from '../utils/annotations.js';
 /**
  * Collect basic target information from DOM (runs in browser context).
  */
-function collectBasicTargetInfo(interactiveSelector) {
+function collectBasicTargetInfo(args) {
+    const { interactiveSelector, 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 `#${CSS.escape(element.id)}`;
@@ -72,6 +90,7 @@ function collectBasicTargetInfo(interactiveSelector) {
         targets.push({
             selector: getUniqueSelector(element, index),
             tagName,
+            ...getHtmlSnippet(element),
             role,
             width: Math.round(rect.width * 100) / 100,
             height: Math.round(rect.height * 100) / 100,
@@ -247,6 +266,8 @@ function analyzeTargets(targets, aaThreshold, aaaThreshold) {
         const issue = {
             selector: target.selector,
             tagName: target.tagName,
+            html: target.html,
+            htmlTruncated: target.htmlTruncated,
             role: target.role,
             accessibleName: target.accessibleName,
             width: target.width,
@@ -255,6 +276,9 @@ function analyzeTargets(targets, aaThreshold, aaaThreshold) {
             level,
             exception,
             exceptionDetails,
+            // the heuristics can detect exceptions but can never rule out the
+            // essential exception, so findings are at best 'possible'/'not-assessed'.
+            exceptionAssessment: exception ? 'possible' : 'not-assessed',
             href: target.href,
         };
         if (exception) {
@@ -276,7 +300,10 @@ function analyzeTargets(targets, aaThreshold, aaaThreshold) {
 export async function runTargetSizeCheck(options) {
     const { page, aaThreshold = TARGET_SIZE_AA, aaaThreshold = TARGET_SIZE_AAA, screenshot = false, ...location } = options;
     // Collect basic target info from DOM
-    const basicTargets = await page.evaluate(collectBasicTargetInfo, INTERACTIVE_SELECTOR);
+    const basicTargets = await page.evaluate(collectBasicTargetInfo, {
+        interactiveSelector: INTERACTIVE_SELECTOR,
+        htmlSnippetMaxLength: HTML_SNIPPET_MAX_LENGTH,
+    });
     // Enhance with accessible names via ariaSnapshot()
     const targets = [];
     for (const basicTarget of basicTargets) {
@@ -296,8 +323,7 @@ export async function runTargetSizeCheck(options) {
     }
     // Analyze targets
     const { failAA, failAAAOnly, passCount, excepted } = analyzeTargets(targets, aaThreshold, aaaThreshold);
-    const result = {
-        url: page.url(),
+    const details = {
         totalTargetsChecked: targets.length,
         failAA,
         failAAAOnly,
@@ -310,16 +336,22 @@ export async function runTargetSizeCheck(options) {
             exceptedCount: excepted.length,
         },
     };
+    const result = buildAuditResult({
+        source: 'target-size-check',
+        url: page.url(),
+        details,
+        buckets: normalizeTargetSizeCheck(details),
+    });
     // Output results
     logAuditHeader('Target Size Check Results', 'WCAG 2.5.5 / 2.5.8', result.url);
     logSummary({
-        'Total targets checked': result.totalTargetsChecked,
+        'Total targets checked': details.totalTargetsChecked,
     });
     console.log('\nSummary:');
-    console.log(`  Pass (>= ${aaaThreshold}px): ${result.summary.passCount}`);
-    console.log(`  Fail AAA only (${aaThreshold}-${aaaThreshold - 1}px): ${result.summary.failAAAOnlyCount}`);
-    console.log(`  Fail AA (< ${aaThreshold}px): ${result.summary.failAACount}`);
-    console.log(`  Possible exceptions: ${result.summary.exceptedCount}`);
+    console.log(`  Pass (>= ${aaaThreshold}px): ${details.summary.passCount}`);
+    console.log(`  Fail AAA only (${aaThreshold}-${aaaThreshold - 1}px): ${details.summary.failAAAOnlyCount}`);
+    console.log(`  Fail AA (< ${aaThreshold}px): ${details.summary.failAACount}`);
+    console.log(`  Possible exceptions: ${details.summary.exceptedCount}`);
     logIssueList(`Fail AA (< ${aaThreshold}px) - Requires Fix`, failAA, (el, i) => {
         const lines = [
             `${i + 1}. <${el.tagName}> "${el.selector}"`,

package/dist/playwright/runTextSpacingCheck.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 type { Page } from '@playwright/test';
+import type { TextSpacingCheckResult } from '../types.js';
+import { type OutputLocationOptions } from '../utils/test-harness.js';
+export interface RunTextSpacingCheckOptions extends OutputLocationOptions {
+    /** A page already navigated to the target URL. */
+    page: Page;
+    /** Tolerance in pixels for clip detection (default: 2). */
+    tolerance?: number;
+    /** Whether to capture a screenshot next to the result file (default: false). */
+    screenshot?: boolean;
+}
+/**
+ * Run the text spacing check against the current page, write the result JSON
+ * (and optionally a screenshot), and return the parsed result.
+ */
+export declare function runTextSpacingCheck(options: RunTextSpacingCheckOptions): Promise<TextSpacingCheckResult>;