跳到主要内容

辅助功能测试

简介​

Playwright 可以用于测试您的应用程序是否存在多种类型的辅助功能问题。

它可以捕获的一些问题示例包括

  • 由于与背景的颜色对比度差，视力障碍用户难以阅读的文本
  • 没有标签的 UI 控件和表单元素，屏幕阅读器无法识别
  • 具有重复 ID 的交互式元素，可能会使辅助技术感到困惑

以下示例依赖于 com.deque.html.axe-core/playwright Maven 包，该包添加了对运行 axe 辅助功能测试引擎 作为 Playwright 测试一部分的支持。

免责声明​

自动化辅助功能测试可以检测到一些常见的辅助功能问题，例如缺少或无效的属性。但许多辅助功能问题只能通过手动测试发现。我们建议结合使用自动化测试、手动辅助功能评估和包容性用户测试。

对于手动评估，我们推荐 Accessibility Insights for Web, 这是一个免费且开源的开发工具，可引导您评估网站的 WCAG 2.1 AA 覆盖率。

辅助功能测试示例​

辅助功能测试的工作方式与任何其他 Playwright 测试一样。您可以为它们创建单独的测试用例，或者将辅助功能扫描和断言集成到您现有的测试用例中。

以下示例演示了一些基本的辅助功能测试场景。

示例 1：扫描整个页面​

此示例演示如何测试整个页面是否存在可自动检测到的辅助功能违规行为。该测试

  1. 导入 com.deque.html.axe-core/playwright 包
  2. 使用普通的 JUnit 5 @Test 语法来定义测试用例
  3. 使用普通的 Playwright 语法来打开浏览器并导航到被测页面
  4. 调用 AxeBuilder.analyze() 来对页面运行辅助功能扫描
  5. 使用普通的 JUnit 5 测试断言来验证返回的扫描结果中没有违规行为
import com.deque.html.axecore.playwright.*; // 1
import com.deque.html.axecore.utilities.axeresults.*;

import org.junit.jupiter.api.*;
import com.microsoft.playwright.*;

import static org.junit.jupiter.api.Assertions.*;

public class HomepageTests {
  @Test // 2
  void shouldNotHaveAutomaticallyDetectableAccessibilityIssues() throws Exception {
    Playwright playwright = Playwright.create();
    Browser browser = playwright.chromium().launch();
    BrowserContext context = browser.newContext();
    Page page = context.newPage();

    page.navigate("https://your-site.com/"); // 3

    AxeResults accessibilityScanResults = new AxeBuilder(page).analyze(); // 4

    assertEquals(Collections.emptyList(), accessibilityScanResults.getViolations()); // 5
  }
}

示例 2：配置 axe 以扫描页面的特定部分​

com.deque.html.axe-core/playwright 支持 axe 的许多配置选项。您可以使用带有 AxeBuilder 类的 Builder 模式来指定这些选项。

例如，您可以使用 AxeBuilder.include() 将辅助功能扫描限制为仅针对页面的特定部分运行。

当您调用 AxeBuilder.analyze() 时，它将扫描 当前状态 下的页面。要扫描基于 UI 交互显示的页面部分，请在使用 analyze() 之前使用 定位器 与页面进行交互

public class HomepageTests {
  @Test
  void navigationMenuFlyoutShouldNotHaveAutomaticallyDetectableAccessibilityViolations() throws Exception {
    page.navigate("https://your-site.com/");

    page.locator("button[aria-label=\"Navigation Menu\"]").click();

    // It is important to waitFor() the page to be in the desired
    // state *before* running analyze(). Otherwise, axe might not
    // find all the elements your test expects it to scan.
    page.locator("#navigation-menu-flyout").waitFor();

    AxeResults accessibilityScanResults = new AxeBuilder(page)
      .include(Arrays.asList("#navigation-menu-flyout"))
      .analyze();

    assertEquals(Collections.emptyList(), accessibilityScanResults.getViolations());
  }
}

示例 3：扫描 WCAG 违规行为​

默认情况下，axe 会根据各种辅助功能规则进行检查。其中一些规则对应于 Web 内容辅助功能指南 (WCAG) 中的特定成功标准，而另一些规则是“最佳实践”规则，任何 WCAG 标准都没有明确要求。

您可以使用 AxeBuilder.withTags() 将辅助功能扫描限制为仅运行那些“标记”为对应于特定 WCAG 成功标准的规则。例如，Accessibility Insights for Web 的自动化检查 仅包含测试 WCAG A 和 AA 成功标准违规行为的 axe 规则；为了匹配该行为，您将使用标签 wcag2a、wcag2aa、wcag21a 和 wcag21aa。

请注意，自动化测试无法检测所有类型的 WCAG 违规行为。

AxeResults accessibilityScanResults = new AxeBuilder(page)
  .withTags(Arrays.asList("wcag2a", "wcag2aa", "wcag21a", "wcag21aa"))
  .analyze();

assertEquals(Collections.emptyList(), accessibilityScanResults.getViolations());

您可以在 axe API 文档的“Axe-core Tags”部分 中找到 axe-core 支持的规则标签的完整列表。

处理已知问题​

在向应用程序添加辅助功能测试时，一个常见的问题是“如何抑制已知的违规行为？” 以下示例演示了您可以使用的几种技术。

从扫描中排除个别元素​

如果您的应用程序包含一些具有已知问题的特定元素，您可以使用 AxeBuilder.exclude() 将它们从扫描中排除，直到您能够修复这些问题。

这通常是最简单的选择，但它有一些重要的缺点

  • exclude() 将排除指定的元素 及其所有后代。避免将其用于包含许多子组件的组件。
  • exclude() 将阻止 所有 规则针对指定的元素运行，而不仅仅是对应于已知问题的规则。

这是一个在一个特定测试中排除一个元素不被扫描的示例

AxeResults accessibilityScanResults = new AxeBuilder(page)
  .exclude(Arrays.asList("#element-with-known-issue"))
  .analyze();

assertEquals(Collections.emptyList(), accessibilityScanResults.getViolations());

如果所讨论的元素在许多页面中重复使用，请考虑 使用测试 fixture 以在多个测试中重用相同的 AxeBuilder 配置。

禁用个别扫描规则​

如果您的应用程序包含许多不同的预先存在的特定规则违规行为，您可以使用 AxeBuilder.disableRules() 暂时禁用个别规则，直到您能够修复这些问题。

您可以在要抑制的违规行为的 id 属性中找到要传递给 disableRules() 的规则 ID。在 axe-core 的文档 中可以找到完整的 axe 规则列表。

AxeResults accessibilityScanResults = new AxeBuilder(page)
  .disableRules(Arrays.asList("duplicate-id"))
  .analyze();

assertEquals(Collections.emptyList(), accessibilityScanResults.getViolations());

使用违规指纹来识别特定已知问题​

如果您想允许更细粒度地处理已知问题，可以使用以下模式

  1. 执行辅助功能扫描，预计会发现一些已知的违规行为
  2. 将违规行为转换为“违规指纹”对象
  3. 断言指纹集等同于预期的指纹集

这种方法避免了使用 AxeBuilder.exclude() 的缺点，但代价是稍微增加了复杂性和脆弱性。

这是一个仅使用规则 ID 和指向每个违规行为的“target”选择器来使用指纹的示例

public class HomepageTests {
  @Test
  shouldOnlyHaveAccessibilityViolationsMatchingKnownFingerprints() throws Exception {
    page.navigate("https://your-site.com/");

    AxeResults accessibilityScanResults = new AxeBuilder(page).analyze();

    List<ViolationFingerprint> violationFingerprints = fingerprintsFromScanResults(accessibilityScanResults);

    assertEquals(Arrays.asList(
      new ViolationFingerprint("aria-roles", "[span[role=\"invalid\"]]"),
      new ViolationFingerprint("color-contrast", "[li:nth-child(2) > span]"),
      new ViolationFingerprint("label", "[input]")
    ), violationFingerprints);
  }

  // You can make your "fingerprint" as specific as you like. This one considers a violation to be
  // "the same" if it corresponds the same Axe rule on the same element.
  //
  // Using a record type makes it easy to compare fingerprints with assertEquals
  public record ViolationFingerprint(String ruleId, String target) { }

  public List<ViolationFingerprint> fingerprintsFromScanResults(AxeResults results) {
    return results.getViolations().stream()
      // Each violation refers to one rule and multiple "nodes" which violate it
      .flatMap(violation -> violation.getNodes().stream()
        .map(node -> new ViolationFingerprint(
          violation.getId(),
          // Each node contains a "target", which is a CSS selector that uniquely identifies it
          // If the page involves iframes or shadow DOMs, it may be a chain of CSS selectors
          node.getTarget().toString()
        )))
      .collect(Collectors.toList());
  }
}

使用测试 fixture 进行通用的 axe 配置​

TestFixtures 类 是在多个测试之间共享通用 AxeBuilder 配置的好方法。一些可能有用场景包括

  • 在所有测试中使用一组通用的规则
  • 抑制在许多不同页面中出现的通用元素中的已知违规行为
  • 为多次扫描一致地附加独立的辅助功能报告

以下示例演示了如何从 测试运行器示例 扩展 TestFixtures 类，并使用包含一些通用 AxeBuilder 配置的新 fixture。

创建 fixture​

此示例 fixture 创建一个 AxeBuilder 对象，该对象已预先配置了共享的 withTags() 和 exclude() 配置。

class AxeTestFixtures extends TestFixtures {
 AxeBuilder makeAxeBuilder() {
   return new AxeBuilder(page)
     .withTags(new String[]{"wcag2a", "wcag2aa", "wcag21a", "wcag21aa"})
     .exclude("#commonly-reused-element-with-known-issue");
 }
}

使用 fixture​

要使用 fixture，请将前面示例的 new AxeBuilder(page) 替换为新定义的 makeAxeBuilder fixture

public class HomepageTests extends AxeTestFixtures {
  @Test
  void exampleUsingCustomFixture() throws Exception {
    page.navigate("https://your-site.com/");

    AxeResults accessibilityScanResults = makeAxeBuilder()
      // Automatically uses the shared AxeBuilder configuration,
      // but supports additional test-specific configuration too
      .include("#specific-element-under-test")
      .analyze();

    assertEquals(Collections.emptyList(), accessibilityScanResults.getViolations());
  }
}

请参阅实验性的 JUnit 集成 以自动初始化 Playwright 对象等。