@techsio/storybook-a11y-reporter 0.0.1

package/README.md

@@ -0,0 +1,65 @@
+# @techsio/storybook-a11y-reporter
+
+CLI/CI reporter that captures Storybook a11y results (including APCA) and writes JSON/JUnit summaries.
+
+## Usage
+1) Configure Storybook test-runner to use this reporter.
+2) Run the test-runner in CI.
+
+Example `.storybook/test-runner.ts`:
+```ts
+import { createA11yReporter } from '@techsio/storybook-a11y-reporter';
+
+export default createA11yReporter({
+  outputDir: 'a11y-report',
+  failOnViolations: true,
+  writeJUnit: true,
+});
+```
+
+Run:
+```bash
+storybook test --config-dir .storybook
+```
+
+Outputs:
+- `a11y-report/report.json`
+- `a11y-report/junit.xml`
+- Console summary
+
+## CI / PR reporting (GitHub Actions)
+The reporter fails the run by default when violations are found. You can override with
+`failOnViolations: false` or `A11Y_REPORT_FAIL_ON_VIOLATIONS=false`.
+
+Example workflow snippet that posts a PR comment and a check:
+```yaml
+jobs:
+  a11y:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      checks: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm storybook test --config-dir .storybook
+
+      - name: Publish check (JUnit)
+        uses: dorny/test-reporter@v1
+        with:
+          name: Storybook A11y
+          path: a11y-report/junit.xml
+          reporter: java-junit
+
+      - name: PR comment summary
+        run: |
+          npx --yes @techsio/storybook-a11y-reporter --input a11y-report/report.json --fail-on-violations false > a11y-summary.md
+      - uses: peter-evans/create-or-update-comment@v4
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          body-path: a11y-summary.md
+```

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import node_path from "node:path";
+import fs_extra from "fs-extra";
+import "@storybook/test-runner";
+function countViolations(results) {
+    if (!results) return 0;
+    return Array.isArray(results.violations) ? results.violations.length : 0;
+}
+function countApcaViolations(results) {
+    if (!results || !Array.isArray(results.violations)) return 0;
+    return results.violations.filter((violation)=>violation?.id === 'apca-contrast').length;
+}
+function formatSummary(entries) {
+    const total = entries.length;
+    const withViolations = entries.filter((entry)=>countViolations(entry.results) > 0);
+    const totalViolations = withViolations.reduce((sum, entry)=>sum + countViolations(entry.results), 0);
+    const apcaViolations = withViolations.reduce((sum, entry)=>sum + countApcaViolations(entry.results), 0);
+    const lines = [];
+    lines.push('# Storybook A11y Report');
+    lines.push('');
+    lines.push(`- Total stories: ${total}`);
+    lines.push(`- Stories with violations: ${withViolations.length}`);
+    lines.push(`- Total violations: ${totalViolations}`);
+    lines.push(`- APCA violations: ${apcaViolations}`);
+    lines.push('');
+    lines.push('| Story | Violations | APCA |');
+    lines.push('| --- | --- | --- |');
+    for (const entry of entries){
+        const violations = countViolations(entry.results);
+        const apca = countApcaViolations(entry.results);
+        const name = `${entry.title} / ${entry.name}`;
+        lines.push(`| ${name} | ${violations} | ${apca} |`);
+    }
+    return lines.join('\n');
+}
+function readReport(filePath = 'a11y-report/report.json') {
+    const resolvedPath = node_path.resolve(process.cwd(), filePath);
+    return fs_extra.readJSONSync(resolvedPath);
+}
+function printSummary(entries) {
+    return formatSummary(entries);
+}
+const args = process.argv.slice(2);
+const inputIndex = args.indexOf('--input');
+const failIndex = args.indexOf('--fail-on-violations');
+const input = inputIndex >= 0 ? args[inputIndex + 1] : void 0;
+const fail = failIndex >= 0 ? 'false' !== args[failIndex + 1] : true;
+try {
+    const entries = readReport(input);
+    const summary = printSummary(entries);
+    console.log(summary);
+    const violations = entries.reduce((sum, entry)=>{
+        const count = Array.isArray(entry.results?.violations) ? entry.results.violations.length : 0;
+        return sum + count;
+    }, 0);
+    if (fail && violations > 0) process.exit(1);
+} catch (error) {
+    console.error(error);
+    process.exit(1);
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { type TestRunnerConfig } from '@storybook/test-runner';
+export interface ReporterOptions {
+    outputDir?: string;
+    failOnViolations?: boolean;
+    writeJUnit?: boolean;
+    waitForResultsMs?: number;
+}
+export interface StoryReportEntry {
+    storyId: string;
+    title: string;
+    name: string;
+    url: string;
+    parameters?: Record<string, unknown> | null;
+    results: any | null;
+}
+export declare function createA11yReporter(options?: ReporterOptions): TestRunnerConfig;
+export declare function readReport(filePath?: string): StoryReportEntry[];
+export declare function printSummary(entries: StoryReportEntry[]): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAEhF,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5C,OAAO,EAAE,GAAG,GAAG,IAAI,CAAC;CACrB;AAgHD,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,gBAAgB,CAkC9E;AAED,wBAAgB,UAAU,CAAC,QAAQ,SAA4B,GAAG,gBAAgB,EAAE,CAGnF;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,MAAM,CAEhE"}

package/dist/index.js

@@ -0,0 +1,125 @@
+import node_path from "node:path";
+import fs_extra from "fs-extra";
+import { getStoryContext } from "@storybook/test-runner";
+const DEFAULT_OPTIONS = {
+    outputDir: 'a11y-report',
+    failOnViolations: true,
+    writeJUnit: true,
+    waitForResultsMs: 8000
+};
+function resolveOptions(options) {
+    const envOutputDir = process.env.A11Y_REPORT_OUTPUT_DIR;
+    const envFail = process.env.A11Y_REPORT_FAIL_ON_VIOLATIONS;
+    const envJUnit = process.env.A11Y_REPORT_JUNIT;
+    const envWait = process.env.A11Y_REPORT_WAIT_MS;
+    return {
+        ...DEFAULT_OPTIONS,
+        ...options,
+        outputDir: envOutputDir || options?.outputDir || DEFAULT_OPTIONS.outputDir,
+        failOnViolations: void 0 !== envFail ? 'false' !== envFail : options?.failOnViolations ?? DEFAULT_OPTIONS.failOnViolations,
+        writeJUnit: void 0 !== envJUnit ? 'false' !== envJUnit : options?.writeJUnit ?? DEFAULT_OPTIONS.writeJUnit,
+        waitForResultsMs: envWait ? Number(envWait) : options?.waitForResultsMs ?? DEFAULT_OPTIONS.waitForResultsMs
+    };
+}
+function countViolations(results) {
+    if (!results) return 0;
+    return Array.isArray(results.violations) ? results.violations.length : 0;
+}
+function countApcaViolations(results) {
+    if (!results || !Array.isArray(results.violations)) return 0;
+    return results.violations.filter((violation)=>violation?.id === 'apca-contrast').length;
+}
+function escapeXml(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+}
+function formatSummary(entries) {
+    const total = entries.length;
+    const withViolations = entries.filter((entry)=>countViolations(entry.results) > 0);
+    const totalViolations = withViolations.reduce((sum, entry)=>sum + countViolations(entry.results), 0);
+    const apcaViolations = withViolations.reduce((sum, entry)=>sum + countApcaViolations(entry.results), 0);
+    const lines = [];
+    lines.push('# Storybook A11y Report');
+    lines.push('');
+    lines.push(`- Total stories: ${total}`);
+    lines.push(`- Stories with violations: ${withViolations.length}`);
+    lines.push(`- Total violations: ${totalViolations}`);
+    lines.push(`- APCA violations: ${apcaViolations}`);
+    lines.push('');
+    lines.push('| Story | Violations | APCA |');
+    lines.push('| --- | --- | --- |');
+    for (const entry of entries){
+        const violations = countViolations(entry.results);
+        const apca = countApcaViolations(entry.results);
+        const name = `${entry.title} / ${entry.name}`;
+        lines.push(`| ${name} | ${violations} | ${apca} |`);
+    }
+    return lines.join('\n');
+}
+function formatJUnit(entries) {
+    const testcases = entries.map((entry)=>{
+        const violations = countViolations(entry.results);
+        const name = `${entry.title} / ${entry.name}`;
+        const className = entry.title;
+        if (violations > 0) {
+            const message = `${violations} accessibility violation(s)`;
+            return `  <testcase classname="${escapeXml(className)}" name="${escapeXml(name)}">\n    <failure message="${escapeXml(message)}" />\n  </testcase>`;
+        }
+        return `  <testcase classname="${escapeXml(className)}" name="${escapeXml(name)}" />`;
+    });
+    const failures = entries.filter((entry)=>countViolations(entry.results) > 0).length;
+    const tests = entries.length;
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        `<testsuite name="storybook-a11y" tests="${tests}" failures="${failures}">`,
+        ...testcases,
+        '</testsuite>',
+        ''
+    ].join('\n');
+}
+async function writeReports(entries, options) {
+    const outputDir = node_path.resolve(process.cwd(), options.outputDir);
+    await fs_extra.ensureDir(outputDir);
+    const reportPath = node_path.join(outputDir, 'report.json');
+    await fs_extra.writeJSON(reportPath, entries, {
+        spaces: 2
+    });
+    const summaryPath = node_path.join(outputDir, 'summary.md');
+    await fs_extra.writeFile(summaryPath, formatSummary(entries));
+    if (options.writeJUnit) {
+        const junitPath = node_path.join(outputDir, 'junit.xml');
+        await fs_extra.writeFile(junitPath, formatJUnit(entries));
+    }
+}
+function createA11yReporter(options) {
+    const resolved = resolveOptions(options);
+    const entries = [];
+    return {
+        async postVisit (page, context) {
+            const storyId = context.id;
+            const storyContext = await getStoryContext(page, context).catch(()=>null);
+            await page.waitForFunction((id)=>window.__TECHSIO_A11Y_RESULTS__?.storyId === id, storyId, {
+                timeout: resolved.waitForResultsMs
+            });
+            const pageResults = await page.evaluate(()=>window.__TECHSIO_A11Y_RESULTS__ ?? null);
+            const entry = {
+                storyId,
+                title: context.title,
+                name: context.name,
+                url: page.url(),
+                parameters: storyContext?.parameters?.a11y ?? null,
+                results: pageResults?.results ?? null
+            };
+            entries.push(entry);
+            await writeReports(entries, resolved);
+            if (resolved.failOnViolations && countViolations(entry.results) > 0) throw new Error(`A11y violations detected in ${context.title} / ${context.name}`);
+        }
+    };
+}
+function readReport(filePath = 'a11y-report/report.json') {
+    const resolvedPath = node_path.resolve(process.cwd(), filePath);
+    return fs_extra.readJSONSync(resolvedPath);
+}
+function printSummary(entries) {
+    return formatSummary(entries);
+}
+export { createA11yReporter, printSummary, readReport };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@techsio/storybook-a11y-reporter",
+  "version": "0.0.1",
+  "description": "Storybook a11y reporter with APCA support for CI/CLI",
+  "type": "module",
+  "bin": {
+    "storybook-a11y-report": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rslib build",
+    "lint": "eslint .",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "fs-extra": "^11.3.2"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@storybook/test-runner": "^0.24.2"
+  },
+  "peerDependencies": {
+    "@storybook/test-runner": ">=0.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}