使用 Playwright 进行无障碍性测试：理解与实践替代方案-js教程-PHP中文网

使用 Playwright 进行无障碍性测试：理解与实践替代方案

碧海醫心

发布： 2025-12-04 12:02:02

原创

740人浏览过

使用 Playwright 进行无障碍性测试：理解与实践替代方案

本文旨在探讨如何使用 playwright 进行无障碍性（accessibility）测试。我们将解析 playwright 内置无障碍性快照功能的局限性及其弃用状态，并重点推荐使用行业标准工具 `@axe-core/playwright` 作为获取和验证网页无障碍性树（accessibility tree）的有效替代方案，提供详细的使用指南和最佳实践。

理解无障碍性树与 Playwright 的交互

无障碍性树（Accessibility Tree, AT）是浏览器根据文档对象模型（DOM）构建的一个简化版本，专为辅助技术（如屏幕阅读器）提供信息。它只包含那些对用户交互和内容描述至关重要的元素，例如交互式元素（如 <input>, <button>) 和描述性元素（如 <span>, <label> 与交互元素关联）。Playwright 能够通过其选择器引擎（如 getByRole）与无障碍性树进行交互，这表明它确实可以访问这些无障碍性信息。

开发者有时会尝试直接提取浏览器生成的完整、层级化的无障碍性树，以进行详细分析。Playwright 曾提供 page.accessibility.snapshot() 方法来尝试获取这些信息。以下是一个示例：

const { chromium } = require('playwright');

async function getAccessibilitySnapshot(url) {
  const browser = await chromium.launch({ headless: true });
  const context = await browser.newContext();
  const page = await context.newPage();

  await page.goto(url);

  // 尝试获取无障碍性快照
  const snapshot = await page.accessibility.snapshot();
  console.log(JSON.stringify(snapshot, null, 2));

  await browser.close();
}

// 示例用法
// getAccessibilitySnapshot("https://www.example.com");

登录后复制

然而，page.accessibility.snapshot() 方法返回的结果通常是一个扁平的元素列表，缺乏预期的父子关系和层级结构，这与 Chrome 开发者工具中展示的详细无障碍性树存在显著差异，难以满足深度分析的需求。

Playwright 内置无障碍性功能的局限性与弃用

根据 Playwright 官方文档和社区反馈，page.accessibility.snapshot() 这一内置的无障碍性功能已被弃用。这意味着它不再是获取精确、层级化无障碍性树的推荐方法，并且其输出的格式和内容可能无法满足开发者对完整无障碍性对象模型（AOM）的期望。

直接从浏览器获取一个完全等同于开发者工具中展示的层级化无障碍性树，在自动化测试框架中通常较为复杂且并非其主要设计目标。Playwright 更侧重于模拟用户行为和进行端到端测试，而无障碍性测试的深度分析则更适合专业的无障碍性工具。

推荐的无障碍性测试方案：使用 @axe-core/playwright

鉴于 Playwright 内置功能的局限性与弃用，对于需要进行全面、专业的无障碍性测试的场景，强烈推荐集成行业标准的无障碍性检测工具。其中，@axe-core/playwright 是一个优秀的解决方案。它结合了 Deque Systems 的 Axe-core 引擎与 Playwright 的自动化能力，能够识别出网页中常见的无障碍性问题，并提供详细的报告。

蚂蚁PPT

AI在线智能生成PPT

113

查看详情

@axe-core/playwright 的优势

行业标准： Axe-core 是广受认可的无障碍性规则引擎，遵循 WCAG (Web Content Accessibility Guidelines) 标准。
全面检测： 能够发现数百种常见的无障碍性违规行为。
详细报告： 提供清晰的错误描述、解决方案建议和相关 WCAG 指南链接。
易于集成： 与 Playwright 测试流程无缝结合，可以在 CI/CD 管道中自动化运行。

使用 @axe-core/playwright

以下是使用 @axe-core/playwright 进行无障碍性测试的基本步骤：

安装依赖： 首先，在你的项目中安装 @axe-core/playwright 包：
```
npm install @axe-core/playwright
# 或者 yarn add @axe-core/playwright
```
登录后复制

编写测试代码： 在 Playwright 测试脚本中，你可以导入并使用 injectAxe 和 checkA11y 函数来执行无障碍性检查。

const { chromium } = require('playwright');
const { injectAxe, checkA11y } = require('axe-core-playwright');

async function runAccessibilityTest(url) {
  const browser = await chromium.launch({ headless: true });
  const context = await browser.newContext();
  const page = await context.newPage();

  await page.goto(url, { waitUntil: 'networkidle' });

  // 1. 将 Axe-core 引擎注入到页面中
  await injectAxe(page);

  // 2. 运行无障碍性检查
  // 可以传入配置对象，例如指定要检查的规则集或排除特定元素
  const results = await checkA11y(page, null, {
    // 配置选项示例
    // rules: {
    //   'color-contrast': { enabled: true },
    //   'html-has-lang': { enabled: false }
    // },
    // runOnly: {
    //   type: 'tag',
    //   values: ['wcag2a', 'wcag2aa']
    // }
  });

  // 3. 处理检查结果
  if (results.violations.length > 0) {
    console.error(`在 ${url} 发现无障碍性违规：`);
    results.violations.forEach((violation) => {
      console.error(`  - ${violation.help} (${violation.id})`);
      console.error(`    影响元素：${violation.nodes.map(node => node.html).join(', ')}`);
      console.error(`    更多信息：${violation.helpUrl}`);
    });
    // 根据需要，你可以抛出错误使测试失败
    // throw new Error(`Accessibility violations found on ${url}`);
  } else {
    console.log(`页面 ${url} 通过无障碍性检查。`);
  }

  await browser.close();
}

// 示例用法
runAccessibilityTest("https://www.google.com");
// runAccessibilityTest("https://your-test-website.com");

登录后复制

上述代码首先导航到目标页面，然后使用 injectAxe(page) 将 Axe-core 脚本注入到页面上下文中。接着，checkA11y(page) 函数会执行无障碍性扫描，并返回一个包含违规信息的结果对象。你可以遍历 results.violations 数组来获取详细的错误报告。

注意事项

测试范围： 确保你的测试覆盖了应用程序的关键流程和页面。
配置选项： checkA11y 方法接受一个配置对象，允许你自定义检查规则、排除特定元素或只运行特定的规则集。这对于减少误报和聚焦特定问题非常有用。
持续集成： 将无障碍性测试集成到你的 CI/CD 管道中，确保每次代码提交或部署都能自动进行无障碍性检查。
人工审核： 自动化工具无法检测所有无障碍性问题。对于复杂的交互和用户体验，仍需要进行人工无障碍性审核。

总结与最佳实践

虽然 Playwright 内置的 page.accessibility.snapshot() 功能已被弃用且无法提供预期的层级化无障碍性树，但这并不意味着 Playwright 无法用于无障碍性测试。相反，通过集成专业的第三方工具如 @axe-core/playwright，开发者可以高效、准确地识别和解决网页的无障碍性问题。

最佳实践是：