@masup9/a11y-audit 0.1.0

package/dist/playwright/runAxeAudit.js

@@ -0,0 +1,89 @@
+/**
+ * Axe-core Accessibility Audit (broad WCAG coverage)
+ *
+ * Runs axe-core automated accessibility testing on the *current* page. The
+ * caller is responsible for navigating the page (e.g. `await page.goto(url)`)
+ * before calling this function.
+ *
+ * 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 { saveAuditResult, logAuditHeader, logSummary, logOutputPaths, } from '../utils/test-harness.js';
+/**
+ * Run an axe-core audit against the current page, write the result JSON, and
+ * return the parsed result.
+ */
+export async function runAxeAudit(options) {
+    const { page, tags = DEFAULT_AXE_TAGS, rules, ...location } = options;
+    let builder = new AxeBuilder({ page }).withTags([...tags]);
+    if (rules) {
+        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,
+    };
+    // 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,
+    });
+    if (result.violations.length > 0) {
+        console.log('\n--- Violations ---');
+        result.violations.forEach((v, i) => {
+            console.log(`\n  ${i + 1}. [${v.impact?.toUpperCase() || 'UNKNOWN'}] ${v.id}`);
+            console.log(`     ${v.help}`);
+            console.log(`     Affected: ${v.nodes.length} element(s)`);
+            console.log(`     Tags: ${v.tags.filter((t) => t.startsWith('wcag')).join(', ')}`);
+            // Show first 3 affected elements
+            v.nodes.slice(0, 3).forEach((n, j) => {
+                const htmlPreview = n.html.length > 80 ? n.html.substring(0, 80) + '...' : n.html;
+                console.log(`       ${j + 1}. ${htmlPreview}`);
+            });
+            if (v.nodes.length > 3) {
+                console.log(`       ... and ${v.nodes.length - 3} more`);
+            }
+        });
+    }
+    console.log(`\n--- Summary ---`);
+    if (result.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)`);
+    }
+    // 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

@@ -0,0 +1,30 @@
+/**
+ * Focus Indicator Visibility Check
+ *
+ * WCAG 2.4.7 (Focus Visible) / 2.4.12 (Focus Not Obscured) / 3.2.1 (On Focus)
+ *
+ * Unlike the other checks, this one owns its `BrowserContext`: it tabs through
+ * every focusable element and, when focus triggers a navigation (3.2.1), it
+ * restarts in a fresh context with the offending element skipped. For that
+ * reason it accepts a `browser` (not a `page`) and navigates internally.
+ *
+ * The context this function creates is closed before it returns.
+ */
+import type { Browser, BrowserContextOptions } from '@playwright/test';
+import type { FocusCheckResult } from '../types.js';
+import { type OutputLocationOptions } from '../utils/test-harness.js';
+export interface RunFocusIndicatorCheckOptions extends OutputLocationOptions {
+    /** The browser to create audit contexts in. */
+    browser: Browser;
+    /** Target URL. Falls back to the `TEST_PAGE` env var; required. */
+    targetUrl?: string;
+    /** Whether to capture a screenshot (default: false). */
+    screenshot?: boolean;
+    /** Options forwarded to `browser.newContext()` (locale, viewport, storageState, ...). */
+    contextOptions?: BrowserContextOptions;
+}
+/**
+ * Run the focus indicator check, write the result JSON (and optionally a
+ * screenshot), and return the parsed result.
+ */
+export declare function runFocusIndicatorCheck(options: RunFocusIndicatorCheckOptions): Promise<FocusCheckResult>;