DRAFT feat: integration with nuxt/test-utils

build.config.test-utils.ts

@@ -0,0 +1,18 @@
+import { defineBuildConfig } from 'unbuild'
+
+export default defineBuildConfig({
+  entries: [
+    'src/test-utils/index',
+    'src/test-utils/setup',
+    'src/test-utils/browser',
+  ],
+  outDir: 'dist',
+  clean: false,
+  declaration: 'node16',
+  externals: [
+    'vitest',
+    'playwright-core',
+    'axe-core',
+    'linkedom',
+  ],
+})

build.config.ts

@@ -0,0 +1,13 @@
+import { defineBuildConfig } from 'unbuild'
+
+export default defineBuildConfig({
+  hooks: {
+    'build:done'(ctx) {
+      for (const warning of ctx.warnings) {
+        if (warning.includes('test-utils')) {
+          ctx.warnings.delete(warning)
+        }
+      }
+    },
+  },
+})

package.json

@@ -10,21 +10,43 @@
     ".": {
       "types": "./dist/types.d.mts",
       "import": "./dist/module.mjs"
+    },
+    "./test-utils": {
+      "types": "./dist/test-utils/index.d.mts",
+      "import": "./dist/test-utils/index.mjs"
+    },
+    "./test-utils/setup": {
+      "types": "./dist/test-utils/setup.d.mts",
+      "import": "./dist/test-utils/setup.mjs"
+    },
+    "./test-utils/browser": {
+      "types": "./dist/test-utils/browser.d.mts",
+      "import": "./dist/test-utils/browser.mjs"
     }
   },
   "main": "./dist/module.mjs",
   "typesVersions": {
     "*": {
       ".": [
         "./dist/types.d.mts"
+      ],
+      "test-utils": [
+        "./dist/test-utils/index.d.mts"
+      ],
+      "test-utils/setup": [
+        "./dist/test-utils/setup.d.mts"
+      ],
+      "test-utils/browser": [
+        "./dist/test-utils/browser.d.mts"
       ]
     }
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt-module-build build && npm run client:build",
+    "build": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt-module-build build && npm run build:test-utils && npm run client:build",
+    "build:test-utils": "unbuild --config build.config.test-utils",
     "client:build": "nuxt generate client",
     "client:dev": "nuxt dev client --port 3030",
     "dev": "npm run play:dev",
@@ -45,6 +67,18 @@
     "linkedom": "^0.18.12",
     "sirv": "^3.0.2"
   },
+  "peerDependencies": {
+    "vitest": ">=1.0.0",
+    "playwright-core": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    },
+    "playwright-core": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@iconify-json/carbon": "^1.2.18",
     "@nuxt/devtools": "latest",
@@ -62,6 +96,7 @@
     "pkg-pr-new": "0.0.63",
     "playwright-core": "1.58.2",
     "typescript": "~5.9.3",
+    "unbuild": "^3.6.1",
     "vite": "7.3.1",
     "vitest": "4.0.18",
     "vue-tsc": "3.2.5"

src/test-utils/auto-scan.ts

@@ -0,0 +1,113 @@
+import type { AutoScanOptions, ScanResult } from './types'
+import { runA11yScan } from './index'
+
+/**
+ * Create a multi-route auto-scan utility that accumulates accessibility
+ * scan results across multiple pages and supports threshold-based failure.
+ *
+ * @param options - Configuration for route exclusion and violation threshold
+ * @returns An object with methods to scan HTML, retrieve results, and check thresholds
+ *
+ * @example
+ * ```ts
+ * import { $fetch } from '@nuxt/test-utils'
+ * import { createAutoScan } from '@nuxt/a11y/test-utils'
+ *
+ * const autoScan = createAutoScan({ threshold: 10, exclude: ['/admin'] })
+ *
+ * for (const route of ['/', '/about', '/contact']) {
+ *   const html = await $fetch<string>(route, { responseType: 'text' })
+ *   await autoScan.scanFetchedHtml(route, html)
+ * }
+ *
+ * const results = autoScan.getResults()
+ * if (autoScan.exceedsThreshold()) {
+ *   console.error('Too many accessibility violations!')
+ * }
+ * ```
+ */
+export function createAutoScan(options: AutoScanOptions = {}) {
+  const { exclude = [], threshold = 0 } = options
+  const results = new Map<string, ScanResult>()
+
+  function normalizeUrl(url: string): string {
+    try {
+      const parsed = new URL(url, 'http://nuxt-a11y.local')
+      return `${parsed.pathname}${parsed.search}`
+    }
+    catch {
+      return url
+    }
+  }
+
+  function isExcluded(url: string): boolean {
+    const normalizedUrl = normalizeUrl(url)
+    return exclude.some(pattern =>
+      typeof pattern === 'string' ? normalizedUrl.includes(pattern) : pattern.test(normalizedUrl),
+    )
+  }
+
+  function mergeResult(url: string, result: ScanResult): void {
+    const key = normalizeUrl(url)
+    const existing = results.get(key)
+    if (!existing) {
+      results.set(key, result)
+      return
+    }
+
+    results.set(key, {
+      ...result,
+      violations: [...existing.violations, ...result.violations],
+      violationCount: existing.violationCount + result.violationCount,
+      getByImpact: level => [...existing.violations, ...result.violations].filter(v => v.impact === level),
+      getByRule: ruleId => [...existing.violations, ...result.violations].filter(v => v.id === ruleId),
+      getByTag: tag => [...existing.violations, ...result.violations].filter(v => v.tags.includes(tag)),
+    })
+  }
+
+  return {
+    /**
+     * Scan fetched HTML for a given URL and accumulate results.
+     * Excluded URLs are silently skipped.
+     *
+     * @param url - The route URL being scanned
+     * @param html - The HTML content to scan
+     */
+    async scanFetchedHtml(url: string, html: string): Promise<void> {
+      if (isExcluded(url))
+        return
+
+      const normalizedUrl = normalizeUrl(url)
+      const result = await runA11yScan(html, { route: normalizedUrl })
+      mergeResult(normalizedUrl, result)
+    },
+
+    addResult(url: string, result: ScanResult): void {
+      if (isExcluded(url))
+        return
+      mergeResult(url, result)
+    },
+
+    /**
+     * Get all accumulated scan results keyed by URL.
+     *
+     * @returns A record mapping URLs to their scan results
+     */
+    getResults(): Record<string, ScanResult> {
+      return Object.fromEntries(results)
+    },
+
+    /**
+     * Check if the total violation count exceeds the configured threshold.
+     *
+     * @returns `true` if total violations exceed the threshold, `false` otherwise
+     */
+    exceedsThreshold(): boolean {
+      let total = 0
+      for (const result of results.values()) {
+        total += result.violationCount
+      }
+      return total > threshold
+    },
+  }
+}