@a11y-skills/audit 0.2.0 → 0.3.1

package/dist/playwright/runAxeAudit.js

@@ -5,11 +5,16 @@
  * caller is responsible for navigating the page (e.g. `await page.goto(url)`)
  * before calling this function.
  *
+ * The normalized buckets are built from the RAW axe results (violations and
+ * incomplete keep their nodes; passes/inapplicable keep rule metadata only),
+ * and `details` records the execution configuration.
+ *
  * Axe-core cannot detect all accessibility issues — manual testing and the
  * other checks in this package are still needed for complete coverage.
  */
 import { AxeBuilder } from '@axe-core/playwright';
-import { AUDIT_DISCLAIMER, DEFAULT_AXE_TAGS, DEFAULT_AXE_RESULT_FILE, } from '../constants.js';
+import { DEFAULT_AXE_TAGS, DEFAULT_AXE_RESULT_FILE } from '../constants.js';
+import { buildAuditResult, normalizeAxeResults } from '../utils/axe-format.js';
 import { saveAuditResult, logAuditHeader, logSummary, logOutputPaths, } from '../utils/test-harness.js';
 /**
  * Run an axe-core audit against the current page, write the result JSON, and
@@ -22,36 +27,29 @@ export async function runAxeAudit(options) {
         builder = builder.options({ rules });
     }
     const axeResults = await builder.analyze();
-    const result = {
-        url: page.url(),
-        timestamp: new Date().toISOString(),
-        violations: axeResults.violations.map((v) => ({
-            id: v.id,
-            impact: v.impact ?? null,
-            description: v.description,
-            help: v.help,
-            helpUrl: v.helpUrl,
-            tags: v.tags,
-            nodes: v.nodes.map((n) => ({
-                html: n.html,
-                target: n.target,
-                failureSummary: n.failureSummary,
-            })),
-        })),
-        passes: axeResults.passes.length,
-        incomplete: axeResults.incomplete.length,
-        inapplicable: axeResults.inapplicable.length,
-        violationCount: axeResults.violations.length,
-        disclaimer: AUDIT_DISCLAIMER,
+    const buckets = normalizeAxeResults(axeResults);
+    const details = {
+        tagsRun: [...tags],
+        rulesOverride: rules ?? null,
+        violationRuleCount: axeResults.violations.length,
+        passRuleCount: axeResults.passes.length,
+        incompleteRuleCount: axeResults.incomplete.length,
+        inapplicableRuleCount: axeResults.inapplicable.length,
     };
+    const result = buildAuditResult({
+        source: 'axe-audit',
+        url: page.url(),
+        details,
+        buckets,
+    });
     // Output results
     logAuditHeader('Axe-core Accessibility Audit Results', 'axe-core', result.url);
     logSummary({
         Timestamp: result.timestamp,
-        Violations: result.violationCount,
-        Passes: result.passes,
-        'Incomplete (needs review)': result.incomplete,
-        Inapplicable: result.inapplicable,
+        Violations: result.summary.violationCount,
+        Passes: result.summary.passCount,
+        'Incomplete (needs review)': result.summary.incompleteCount,
+        Inapplicable: result.inapplicable.length,
     });
     if (result.violations.length > 0) {
         console.log('\n--- Violations ---');
@@ -71,18 +69,16 @@ export async function runAxeAudit(options) {
         });
     }
     console.log(`\n--- Summary ---`);
-    if (result.violationCount === 0) {
+    if (result.summary.violationCount === 0) {
         console.log('No violations detected by axe-core');
     }
     else {
         const totalElements = result.violations.reduce((sum, v) => sum + v.nodes.length, 0);
-        console.log(`Found ${result.violationCount} violation type(s) affecting ${totalElements} element(s)`);
+        console.log(`Found ${result.summary.violationCount} violation type(s) affecting ${totalElements} element(s)`);
     }
-    // axe results already carry the disclaimer field; don't append it again.
     const resolvedPath = saveAuditResult(result, {
         ...location,
         defaultFile: DEFAULT_AXE_RESULT_FILE,
-        includeDisclaimer: false,
     });
     logOutputPaths(resolvedPath);
     return result;

package/dist/playwright/runFocusIndicatorCheck.d.ts

@@ -22,6 +22,13 @@ export interface RunFocusIndicatorCheckOptions extends OutputLocationOptions {
     screenshot?: boolean;
     /** Options forwarded to `browser.newContext()` (locale, viewport, storageState, ...). */
     contextOptions?: BrowserContextOptions;
+    /**
+     * Milliseconds to wait after each Tab press for a focus-triggered navigation
+     * to surface (default: 50). A navigation that fires after this window may be
+     * missed or attributed to a neighboring element — raise this value when
+     * auditing pages with debounced or otherwise delayed focus handlers.
+     */
+    navigationSettleMs?: number;
 }
 /**
  * Run the focus indicator check, write the result JSON (and optionally a

package/dist/playwright/runFocusIndicatorCheck.js

@@ -10,7 +10,8 @@
  *
  * The context this function creates is closed before it returns.
  */
-import { FOCUSABLE_SELECTOR, FOCUS_STYLE_PROPERTIES, EXTRA_TAB_ITERATIONS, DEFAULT_FOCUS_RESULT_FILE, DEFAULT_FOCUS_SCREENSHOT_FILE, FOCUS_OBSCURED_MIN_OVERLAP_RATIO, FOCUS_OBSCURED_MIN_OVERLAP_PX, FOCUS_OBSCURED_EXCLUDE_SELECTORS, } from '../constants.js';
+import { FOCUSABLE_SELECTOR, FOCUS_STYLE_PROPERTIES, EXTRA_TAB_ITERATIONS, DEFAULT_NAVIGATION_SETTLE_MS, DEFAULT_FOCUS_RESULT_FILE, DEFAULT_FOCUS_SCREENSHOT_FILE, FOCUS_OBSCURED_MIN_OVERLAP_RATIO, FOCUS_OBSCURED_MIN_OVERLAP_PX, FOCUS_OBSCURED_EXCLUDE_SELECTORS, HTML_SNIPPET_MAX_LENGTH, } from '../constants.js';
+import { buildAuditResult, normalizeFocusCheck } from '../utils/axe-format.js';
 import { resolveOutputPath, resolveScreenshotPath, saveAuditResult, takeAuditScreenshot, requireTargetUrl, logAuditHeader, logOutputPaths, } from '../utils/test-harness.js';
 // =============================================================================
 // Browser-injected styles for marking elements
@@ -72,7 +73,7 @@ const MAX_RETRIES = 5;
  * screenshot), and return the parsed result.
  */
 export async function runFocusIndicatorCheck(options) {
-    const { browser, targetUrl: targetUrlOption, screenshot = false, contextOptions, ...location } = options;
+    const { browser, targetUrl: targetUrlOption, screenshot = false, contextOptions, navigationSettleMs = DEFAULT_NAVIGATION_SETTLE_MS, ...location } = options;
     const targetUrl = requireTargetUrl(targetUrlOption);
     const resolvedResultPath = resolveOutputPath({
         ...location,
@@ -94,6 +95,18 @@ export async function runFocusIndicatorCheck(options) {
             // Create a fresh context for each attempt to reset init scripts
             context = await browser.newContext(contextOptions);
             const page = await context.newPage();
+            // Track main-frame navigations (WCAG 3.2.1). Catches URL changes that
+            // commit and revert within a single settle window (which the before/after
+            // URL diff alone would miss). A navigation landing between iterations is
+            // absorbed into the next urlBeforeTab and is NOT caught by this listener —
+            // raise navigationSettleMs for pages with slow focus-triggered handlers.
+            // Reset after the initial goto; checked alongside the URL diff.
+            let lateNavigationUrl = null;
+            page.on('framenavigated', (frame) => {
+                if (frame === page.mainFrame()) {
+                    lateNavigationUrl = frame.url();
+                }
+            });
             const focusHistory = [];
             let lastFocusedElement = null;
             let navigationDetected = false;
@@ -106,6 +119,8 @@ export async function runFocusIndicatorCheck(options) {
                     name: data.name,
                     selector: data.selector ||
                         `${data.tag.toLowerCase()}:nth-of-type(${data.id + 1})`,
+                    html: data.html,
+                    htmlTruncated: data.htmlTruncated,
                 };
             });
             // Expose function to receive focus obscured reports (WCAG 2.4.12)
@@ -118,6 +133,7 @@ export async function runFocusIndicatorCheck(options) {
                 styleProperties: [...FOCUS_STYLE_PROPERTIES],
                 warningStyles: WARNING_STYLES,
                 skipSelectors: [...skipSelectors],
+                htmlSnippetMaxLength: HTML_SNIPPET_MAX_LENGTH,
                 obscuredConfig: {
                     minOverlapRatio: FOCUS_OBSCURED_MIN_OVERLAP_RATIO,
                     minOverlapPx: FOCUS_OBSCURED_MIN_OVERLAP_PX,
@@ -156,6 +172,9 @@ export async function runFocusIndicatorCheck(options) {
                     });
                 }, skipSelectors);
             }
+            // Reset the late-navigation flag so the initial goto and skip-element
+            // setup above don't produce false positives in the Tab loop.
+            lateNavigationUrl = null;
             // Tab through all elements with navigation detection
             for (let i = 0; i < count + EXTRA_TAB_ITERATIONS; i++) {
                 const urlBeforeTab = page.url();
@@ -163,7 +182,7 @@ export async function runFocusIndicatorCheck(options) {
                 // Get currently focused element IMMEDIATELY after Tab
                 let currentFocusedElement = null;
                 try {
-                    currentFocusedElement = await page.evaluate(() => {
+                    currentFocusedElement = await page.evaluate((htmlSnippetMaxLength) => {
                         const el = document.activeElement;
                         if (!el || el === document.body)
                             return null;
@@ -180,6 +199,17 @@ export async function runFocusIndicatorCheck(options) {
                             const index = siblings.indexOf(element) + 1;
                             return `${getSelector(parent)} > ${tag}:nth-of-type(${index})`;
                         };
+                        let html = '';
+                        try {
+                            html = el.outerHTML || '';
+                        }
+                        catch {
+                            html = '';
+                        }
+                        if (!html) {
+                            html = `<${el.tagName.toLowerCase()}>`;
+                        }
+                        const htmlTruncated = html.length > htmlSnippetMaxLength;
                         return {
                             tag: el.tagName,
                             role: el.getAttribute('role'),
@@ -187,26 +217,34 @@ export async function runFocusIndicatorCheck(options) {
                                 el.textContent?.slice(0, 30) ||
                                 '',
                             selector: getSelector(el),
+                            html: htmlTruncated
+                                ? html.slice(0, htmlSnippetMaxLength)
+                                : html,
+                            htmlTruncated,
                         };
-                    });
+                    }, HTML_SNIPPET_MAX_LENGTH);
                 }
                 catch {
                     // Page might have navigated, use lastFocusedElement as fallback
                     currentFocusedElement = lastFocusedElement;
                 }
                 // Small wait to allow any navigation to start
-                await page.waitForTimeout(50);
-                // Check if navigation occurred
+                await page.waitForTimeout(navigationSettleMs);
+                // Check if navigation occurred (either within the settle window or late)
                 const urlAfterTab = page.url();
-                if (urlAfterTab !== urlBeforeTab) {
+                const lateNav = lateNavigationUrl !== null && lateNavigationUrl !== urlBeforeTab;
+                if (urlAfterTab !== urlBeforeTab || lateNav) {
                     // 3.2.1 violation detected!
                     navigationDetected = true;
                     const culprit = currentFocusedElement || lastFocusedElement;
                     if (culprit && !skipSelectors.includes(culprit.selector)) {
+                        const toUrl = urlAfterTab !== urlBeforeTab
+                            ? urlAfterTab
+                            : (lateNavigationUrl ?? urlAfterTab);
                         onFocusViolations.push({
                             element: culprit,
                             fromUrl: urlBeforeTab,
-                            toUrl: urlAfterTab,
+                            toUrl,
                             changeType: 'navigation',
                         });
                         skipSelectors.push(culprit.selector);
@@ -214,9 +252,10 @@ export async function runFocusIndicatorCheck(options) {
                         console.warn(`    Element: <${culprit.tag}> "${culprit.name}"`);
                         console.warn(`    Selector: ${culprit.selector}`);
                         console.warn(`    From: ${urlBeforeTab}`);
-                        console.warn(`    To: ${urlAfterTab}`);
+                        console.warn(`    To: ${toUrl}`);
                         console.warn(`    Restarting test with this element skipped...`);
                     }
+                    lateNavigationUrl = null;
                     break;
                 }
             }
@@ -248,8 +287,7 @@ export async function runFocusIndicatorCheck(options) {
             console.warn('Elements without visible focus indicator:', elementsWithoutFocusStyle);
         }
         // Build result
-        const result = {
-            url: finalPage.url(),
+        const details = {
             totalFocusableElements: finalFocusHistory.length,
             elementsWithFocusStyle: finalFocusHistory.length - elementsWithoutFocusStyle.length,
             elementsWithoutFocusStyle: elementsWithoutFocusStyle.length,
@@ -257,6 +295,9 @@ export async function runFocusIndicatorCheck(options) {
                 tag: el.tag,
                 role: el.role,
                 name: el.name,
+                selector: el.selector,
+                html: el.html,
+                htmlTruncated: el.htmlTruncated,
             })),
             onFocusViolations,
             focusObscuredIssues,
@@ -265,12 +306,18 @@ export async function runFocusIndicatorCheck(options) {
             interrupted: false,
             screenshotPath: screenshot ? resolvedScreenshotPath : '',
         };
+        const result = buildAuditResult({
+            source: 'focus-indicator-check',
+            url: finalPage.url(),
+            details,
+            buckets: normalizeFocusCheck(details),
+        });
         // Output results
-        logAuditHeader('Focus Indicator Check Results', 'WCAG 2.4.7 / 2.4.12 / 3.2.1', result.url);
-        console.log(`Total focusable elements: ${result.totalFocusableElements}`);
-        console.log(`Elements with focus style: ${result.elementsWithFocusStyle}`);
-        console.log(`Elements WITHOUT focus style: ${result.elementsWithoutFocusStyle}`);
-        console.log(`Elements with OBSCURED focus: ${result.elementsWithObscuredFocus}`);
+        logAuditHeader('Focus Indicator Check Results', 'WCAG 2.4.7 / 2.4.11 / 3.2.1', result.url);
+        console.log(`Total focusable elements: ${details.totalFocusableElements}`);
+        console.log(`Elements with focus style: ${details.elementsWithFocusStyle}`);
+        console.log(`Elements WITHOUT focus style: ${details.elementsWithoutFocusStyle}`);
+        console.log(`Elements with OBSCURED focus: ${details.elementsWithObscuredFocus}`);
         if (retryCount > 0) {
             console.log(`\nTest restarted ${retryCount} time(s) due to navigation violations`);
         }
@@ -328,7 +375,23 @@ export async function runFocusIndicatorCheck(options) {
 // Browser-injected script factory
 // =============================================================================
 function createFocusTrackerScript(args) {
-    const { focusableSelector, styleProperties, warningStyles, skipSelectors, obscuredConfig } = args;
+    const { focusableSelector, styleProperties, warningStyles, skipSelectors, htmlSnippetMaxLength, obscuredConfig, } = args;
+    const getHtmlSnippet = (el) => {
+        let html = '';
+        try {
+            html = el.outerHTML || '';
+        }
+        catch {
+            html = '';
+        }
+        if (!html) {
+            return { html: `<${el.tagName.toLowerCase()}>`, htmlTruncated: false };
+        }
+        if (html.length > htmlSnippetMaxLength) {
+            return { html: html.slice(0, htmlSnippetMaxLength), htmlTruncated: true };
+        }
+        return { html, htmlTruncated: false };
+    };
     // Add warning styles
     const styleSheet = new CSSStyleSheet();
     document.adoptedStyleSheets = [...document.adoptedStyleSheets, styleSheet];
@@ -646,7 +709,8 @@ function createFocusTrackerScript(args) {
         // Clamp ratio to max 1.0 to handle overlapping obscurers covering same region
         const obscuredRatio = Math.min(totalOverlapArea / focusedArea, 1.0);
         // Only report if obscured ratio exceeds threshold
-        if (obscuredRatio >= obscuredConfig.minOverlapRatio && overlaps.length > 0) {
+        if (obscuredRatio >= obscuredConfig.minOverlapRatio &&
+            overlaps.length > 0) {
             // Add visual annotation
             addAnnotationBox(focusedEl, `⚠ 2.4.12 Obscured (${(obscuredRatio * 100).toFixed(0)}%)`, 'focus-obscured');
             // Report to test
@@ -658,6 +722,7 @@ function createFocusTrackerScript(args) {
                         focusedEl.textContent?.slice(0, 30) ||
                         '',
                     selector: getSelector(focusedEl),
+                    ...getHtmlSnippet(focusedEl),
                 },
                 elementRect: {
                     left: focusedRect.left,
@@ -673,18 +738,19 @@ function createFocusTrackerScript(args) {
     /**
      * Initialize focus tracker - called after page load
      */
-    window.initFocusTracker = () => {
-        // Create overlay container
-        createOverlay();
-        const elements = [...document.querySelectorAll(focusableSelector)]
-            .filter(isVisible)
-            .filter((el) => !shouldSkip(el));
-        elements.forEach((el) => {
-            baseStyles.set(el, captureStyle(el));
-            elementSelectors.set(el, getSelector(el));
-        });
-        return elements.length;
-    };
+    window.initFocusTracker =
+        () => {
+            // Create overlay container
+            createOverlay();
+            const elements = [...document.querySelectorAll(focusableSelector)]
+                .filter(isVisible)
+                .filter((el) => !shouldSkip(el));
+            elements.forEach((el) => {
+                baseStyles.set(el, captureStyle(el));
+                elementSelectors.set(el, getSelector(el));
+            });
+            return elements.length;
+        };
     /**
      * Handle focus events
      */
@@ -729,10 +795,11 @@ function createFocusTrackerScript(args) {
             id,
             tag: el.tagName,
             role: el.getAttribute('role'),
-            name: el.getAttribute('aria-label') || el.textContent?.slice(0, 30),
+            name: el.getAttribute('aria-label') || el.textContent?.slice(0, 30) || '',
             hasFocusStyle,
             diff,
             selector: elementSelectors.get(el) || getSelector(el),
+            ...getHtmlSnippet(el),
         });
         // Check for WCAG 2.4.12 - focus obscured by fixed/sticky elements
         checkFocusObscured(el);

package/dist/playwright/runOrientationCheck.js

@@ -16,6 +16,7 @@
  * - 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) {
@@ -137,20 +138,25 @@ export async function runOrientationCheck(options) {
     const landscapeHasLock = landscapeState.lockMessageFound || landscapeState.mainContentHidden;
     const hasOrientationLock = portraitHasLock || landscapeHasLock;
     const lockDetectedIn = determineLockLocation(portraitHasLock, landscapeHasLock);
-    const result = {
-        url: page.url(),
+    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, result.portrait);
-    logOrientationState('Landscape', ORIENTATION_VIEWPORTS.landscape, result.landscape);
-    console.log(`\nOrientation lock detected: ${result.hasOrientationLock ? 'YES' : 'No'}`);
-    if (result.hasOrientationLock) {
-        console.log(`Lock detected in: ${result.lockDetectedIn}`);
+    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,

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
@@ -22,33 +23,42 @@ import { saveAuditResult, takeAuditScreenshot, resolveScreenshotPath, logAuditHe
  */
 export async function runReflowCheck(options) {
     const { page, viewport = REFLOW_VIEWPORT, overflowTolerance = REFLOW_OVERFLOW_TOLERANCE, screenshot = false, ...location } = options;
-    await page.setViewportSize({ width: viewport.width, height: viewport.height });
+    await page.setViewportSize({
+        width: viewport.width,
+        height: viewport.height,
+    });
     const layoutResult = await page.evaluate(createLayoutChecker, {
         viewportWidth: viewport.width,
         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,34 @@
  * - 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';
+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)}`;
@@ -41,7 +62,9 @@ function collectBasicTargetInfo(interactiveSelector) {
             path.unshift(selector);
             current = parent;
         }
-        return path.length > 0 ? path.join(' > ') : `[data-index="${elementIndex}"]`;
+        return path.length > 0
+            ? path.join(' > ')
+            : `[data-index="${elementIndex}"]`;
     }
     const targets = [];
     const elements = document.querySelectorAll(interactiveSelector);
@@ -72,6 +95,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 +271,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 +281,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 +305,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 +328,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 +341,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}"`,