|
| 1 | +/* |
| 2 | + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one |
| 3 | + * or more contributor license agreements. Licensed under the "Elastic License |
| 4 | + * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side |
| 5 | + * Public License v 1"; you may not use this file except in compliance with, at |
| 6 | + * your election, the "Elastic License 2.0", the "GNU Affero General Public |
| 7 | + * License v3.0 only", or the "Server Side Public License, v 1". |
| 8 | + */ |
| 9 | + |
| 10 | +import type { Page } from '@playwright/test'; |
| 11 | +import type { Result } from 'axe-core'; |
| 12 | +import AxeBuilder from '@axe-core/playwright'; |
| 13 | +import { AXE_OPTIONS, AXE_IMPACT_LEVELS } from '@kbn/axe-config'; |
| 14 | + |
| 15 | +export interface RunA11yScanOptions { |
| 16 | + /** Optional CSS selectors to include in analysis */ |
| 17 | + include?: string[]; |
| 18 | + /** Optional CSS selectors to exclude from analysis */ |
| 19 | + exclude?: string[]; |
| 20 | + /** Timeout in ms for the scan (defaults 10000) */ |
| 21 | + timeoutMs?: number; |
| 22 | +} |
| 23 | + |
| 24 | +/** |
| 25 | + * Runs an Axe accessibility scan |
| 26 | + * |
| 27 | + * Failure modes: |
| 28 | + * - Timeout: Can occur on large or complex DOMs. The scan rejects with a timeout Error; tests should |
| 29 | + * be made more isolated by narrowing scope via the `include` option. |
| 30 | + * - Axe/Playwright errors: Underlying errors propagate and indicate a failed scan. |
| 31 | + */ |
| 32 | +const runA11yScan = async ( |
| 33 | + page: Page, |
| 34 | + { include = [], exclude = [], timeoutMs = 10000 }: RunA11yScanOptions = {} |
| 35 | +) => { |
| 36 | + const builder = new AxeBuilder({ page }); |
| 37 | + builder.options(AXE_OPTIONS); |
| 38 | + |
| 39 | + for (const selector of include) { |
| 40 | + builder.include(selector); |
| 41 | + } |
| 42 | + |
| 43 | + for (const selector of exclude) { |
| 44 | + builder.exclude(selector); |
| 45 | + } |
| 46 | + |
| 47 | + const analysisPromise = builder.analyze(); |
| 48 | + let timeoutId: ReturnType<typeof setTimeout> | undefined; |
| 49 | + |
| 50 | + const result = await Promise.race([ |
| 51 | + analysisPromise, |
| 52 | + new Promise<never>((_, reject) => { |
| 53 | + timeoutId = setTimeout( |
| 54 | + () => reject(new Error(`Axe accessibility scan timed out after ${timeoutMs}ms`)), |
| 55 | + timeoutMs |
| 56 | + ); |
| 57 | + }), |
| 58 | + ]); |
| 59 | + |
| 60 | + if (timeoutId) { |
| 61 | + clearTimeout(timeoutId); |
| 62 | + } |
| 63 | + |
| 64 | + let violations: Result[] = result.violations; |
| 65 | + |
| 66 | + if (AXE_IMPACT_LEVELS?.length) { |
| 67 | + violations = violations.filter((v) => v.impact && AXE_IMPACT_LEVELS.includes(v.impact)); |
| 68 | + } |
| 69 | + |
| 70 | + return { violations }; |
| 71 | +}; |
| 72 | + |
| 73 | +export const checkA11y = async (page: Page, options?: RunA11yScanOptions) => { |
| 74 | + const { violations } = await runA11yScan(page, options); |
| 75 | + |
| 76 | + const formatA11yViolation = (v: Result): string => { |
| 77 | + const nodesSection = v.nodes |
| 78 | + .map((n, idx) => { |
| 79 | + const selectors = `${n.target.join(', ')}(xpath: ${n.xpath})`; |
| 80 | + const failure = n.failureSummary?.trim() || 'No failure summary provided'; |
| 81 | + return ` ${idx + 1}. Selectors: ${selectors}\n Failure: ${failure}`; |
| 82 | + }) |
| 83 | + .join('\n'); |
| 84 | + |
| 85 | + return [ |
| 86 | + `\nAccessibility violation detected!\n`, |
| 87 | + ` Rule: ${v.id}. Impact: (${v.impact ?? 'impact unknown'})`, |
| 88 | + ` Description: ${v.description}`, |
| 89 | + ` Help: ${v.help}. See more: ${v.helpUrl}`, |
| 90 | + ` Page: ${page.url()}`, |
| 91 | + ` Nodes:\n${nodesSection}`, |
| 92 | + ] |
| 93 | + .join('\n') |
| 94 | + .trim(); |
| 95 | + }; |
| 96 | + |
| 97 | + return { |
| 98 | + violations: violations.map((v) => formatA11yViolation(v)), |
| 99 | + }; |
| 100 | +}; |
0 commit comments