本文探讨了使用 playwright 提取浏览器可访问性树（accessibility tree）的挑战，并指出 `page.accessibility.snapshot()` 方法的局限性及其已弃用状态。针对现代 web 可访问性测试需求，文章推荐并详细介绍了如何利用 `@axe-core/playwright` 库进行高效、专业的自动化可访问性检测，从而确保网页符合无障碍标准。
引言：理解可访问性树与自动化测试
Web 可访问性（Accessibility）旨在确保所有人，包括残障人士，都能平等地访问和使用网站内容。浏览器在渲染 DOM（文档对象模型）后，会构建一个称为“可访问性树”（Accessibility Tree, AT）或“可访问性对象模型”（Accessibility Object Model, AOM）的结构。这个树状结构只包含对辅助技术（如屏幕阅读器）有意义的交互式和描述性元素，例如 <input>、<button> 等交互元素，以及与它们关联的 <span>、<label> 等描述性元素。
开发者通常希望通过自动化测试工具（如 Playwright 或 Selenium）来提取或验证这个可访问性树，以确保其网站符合无障碍标准。Playwright 作为一个强大的端到端测试框架，提供了与浏览器深度交互的能力。然而，直接获取一个与 Chrome DevTools 中完全一致的、带有完整父子关系的原始可访问性树，并非其设计初衷，且其早期提供的相关 API 也存在局限性。
许多用户尝试使用 Playwright 的 page.accessibility.snapshot() 方法来获取可访问性信息，期望得到一个结构化的树。例如：
const { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch({ headless: true });
const context = await browser.newContext();
const page = await context.newPage();
await page.goto('https://www.example.com'); // 替换为你的目标URL
const snapshot = await page.accessibility.snapshot();
console.log(JSON.stringify(snapshot, null, 2));
await browser.close();
})();然而，此方法返回的结果通常是一个扁平的元素列表，而非带有明确父子关系的树状结构。这使得它难以用于深入分析元素的层级关系或进行精确的可访问性模型验证。
Playwright 原生可访问性快照的局限性与弃用
根据 Playwright 官方的更新，page.accessibility.snapshot() 方法已被标记为弃用。这意味着它不再是获取详细、结构化可访问性树的推荐方式，并且其功能可能在未来的版本中被移除或更改。该方法返回的“树”实际上是一个经过处理的、相对扁平的节点列表，主要用于辅助生成简单的可访问性报告，但无法提供像浏览器内部 DevTools 那样完整的 AOM 视图。
因此，如果你的目标是获取精确的、带有父子关系的原始可访问性树，page.accessibility.snapshot() 并非合适的工具。
现代可访问性测试方案：拥抱 @axe-core/playwright
对于现代 Web 可访问性测试，最佳实践是利用专门的自动化可访问性测试库。其中，@axe-core/playwright 是一个广泛推荐且功能强大的工具。它集成了 Deque Systems 的 axe-core 引擎，该引擎是行业领先的可访问性规则集，能够检测出大量常见的可访问性违规。
@axe-core/playwright 的核心价值在于它专注于识别和报告可访问性问题，而不是仅仅导出原始的可访问性树。它通过分析页面的 DOM 结构、CSS 样式和运行时行为来发现潜在的违规，并提供详细的报告，包括违规类型、影响程度、受影响的元素以及修复建议。
1. 安装与配置
首先，你需要将 @axe-core/playwright 添加到你的项目中：
npm install @axe-core/playwright # 或者 yarn add @axe-core/playwright
2. 基本使用示例
集成 @axe-core/playwright 到你的 Playwright 测试流程非常直接。以下是一个基本示例，展示如何在页面加载后运行可访问性检查：
const { chromium } = require('playwright');
const { injectAxe, get } = require('@axe-core/playwright'); // 注意：这里是 getResult 还是 checkA11y，取决于版本和使用方式
(async () => {
const browser = await chromium.launch({ headless: true });
const context = await browser.newContext();
const page = await context.newPage();
await page.goto('https://www.example.com'); // 替换为你的目标URL
// 1. 将 axe-core 引擎注入到页面中
await injectAxe(page);
// 2. 运行可访问性检查
// 可以指定要检查的元素（如 'body'），或排除某些元素
const accessibilityScanResults = await page.checkA11y();
// 或者使用 getResult 方法获取更详细的原始结果
// const accessibilityScanResults = await page.evaluate(() => axe.run());
// 打印检测结果
if (accessibilityScanResults.violations.length > 0) {
console.error('发现可访问性违规：');
accessibilityScanResults.violations.forEach(violation => {
console.error(` 规则: ${violation.id}`);
console.error(` 描述: ${violation.description}`);
console.error(` 影响: ${violation.impact}`);
console.error(` 元素:`);
violation.nodes.forEach(node => {
console.error(` 选择器: ${node.target}`);
console.error(` HTML: ${node.html}`);
console.error(` 修复建议: ${node.failureSummary}`);
console.error(` 帮助链接: ${violation.helpUrl}`);
});
console.error('---');
});
} else {
console.log('未发现可访问性违规。');
}
await browser.close();
})();注意事项：
- injectAxe(page) 会将 axe-core 脚本注入到当前页面上下文中，使其可以在页面内执行。
- page.checkA11y() 是 @axe-core/playwright 提供的一个便利方法，用于运行 axe-core 并返回格式化的结果。你可以通过传递参数来限制检查的范围（例如，只检查某个特定的 DOM 节点）。
- accessibilityScanResults 对象包含了 violations（违规项）、passes（通过项）、incomplete（未完成项）等属性。violations 数组是你在自动化测试中最需要关注的部分。
3. 结果分析与报告
axe-core 的结果非常详细，每个违规项（violation）都包含以下关键信息：
- id: 违规规则的唯一标识符。
- description: 违规的简短描述。
- impact: 违规对用户的影响程度（如 critical, serious, moderate, minor）。
- nodes: 导致违规的 DOM 元素列表，每个节点包含其选择器（target）、原始 HTML（html）和具体的失败摘要（failureSummary）。
- helpUrl: 提供更多关于此违规规则的详细信息和修复建议的链接。
通过解析这些结果，你可以自动化地识别网站中的可访问性问题，并将其集成到 CI/CD 流程中，从而在开发早期发现并修复问题。
Playwright 官方可访问性文档的价值
除了使用像 @axe-core/playwright 这样的专业工具，强烈建议查阅 Playwright 官方的可访问性测试文档。官方文档会提供关于如何进行可访问性测试的最新指南、最佳实践以及可能更新的 API 信息。它能帮助你更好地理解 Playwright 在这一领域的支持范围，并结合第三方工具发挥最大效用。
总结
尽管 Playwright 原生的 page.accessibility.snapshot() 方法在获取详细的可访问性树方面存在局限性且已弃用，但通过结合 @axe-core/playwright 这样的专业库，开发者可以高效地进行自动化可访问性测试。@axe-core/playwright 专注于发现和报告可访问性违规，提供了丰富的检测规则和详细的报告，是确保 Web 应用符合无障碍标准的首选工具。通过将这些工具集成到开发和测试流程中，我们可以构建更具包容性和用户友好的网站。
