axe-core

axe-core - 快速参考

不适用此技能的情况

• 手动 WCAG 合规性审计 - 使用 wcag 技能了解指南并进行手动测试
• 屏幕阅读器测试 - axe-core 不能替代手动屏幕阅读器验证
• 复杂的 ARIA 模式实现 - 使用 wcag 技能了解 ARIA 编写实践
• 无障碍策略规划 - 此技能用于测试自动化，而非无障碍咨询

深入了解：使用 mcp__documentation__fetch_docs，并将 technology 设为 axe-core，获取有关规则、配置和集成的完整文档。

基础设置

npm install -D @axe-core/react  # For React
npm install -D axe-core         # Core library

基本模式

React DevTools 集成

import React from 'react';
import ReactDOM from 'react-dom/client';

if (process.env.NODE_ENV !== 'production') {
  import('@axe-core/react').then(axe => {
    axe.default(React, ReactDOM, 1000);
  });
}

Jest/Vitest 集成

import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

test('should have no accessibility violations', async () => {
  const { container } = render(<MyComponent />);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

Playwright 集成

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('should not have accessibility issues', async ({ page }) => {
  await page.goto('/');

  const accessibilityScanResults = await new AxeBuilder({ page }).analyze();

  expect(accessibilityScanResults.violations).toEqual([]);
});

// With specific rules
test('should pass WCAG AA', async ({ page }) => {
  await page.goto('/');

  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa'])
    .analyze();

  expect(results.violations).toEqual([]);
});

Cypress 集成

// cypress/support/commands.ts
import 'cypress-axe';

// In test
describe('Accessibility', () => {
  it('has no violations', () => {
    cy.visit('/');
    cy.injectAxe();
    cy.checkA11y();
  });
});

编程式用法

import axe from 'axe-core';

async function checkAccessibility() {
  const results = await axe.run();

  if (results.violations.length > 0) {
    console.log('Violations:', results.violations);
  }
}

反模式

反模式	错误原因	正确做法
在空状态或加载状态下运行 axe	测试的 DOM 不完整，可能产生假阴性	等待内容加载后再运行 axe
忽略所有违规项	违背了自动化测试的目的	修复违规项，或说明例外情况及其理由
只测试主页	大多数无障碍问题出现在复杂交互中	测试所有关键用户流程和组件
不配置 WCAG 级别	会针对所有规则进行测试，要求可能过于严格	使用 withTags(['wcag2a', 'wcag2aa']) 设置目标级别
在循环中同步运行 axe	测试执行缓慢	使用 Promise.all() 并行执行
将违规项提交到 CI	无法发现回归问题	对新增违规项执行构建失败处理
测试隐藏或非活动组件	axe 会不必要地测试不可见元素	使用 exclude 参数排除隐藏区域
旧代码没有基线	所有违规项都会阻碍进度	创建基线，逐步跟踪改进情况

快速故障排查

问题	诊断	解决方案
axe 未发现违规项，但页面无法访问	自动化工具只能发现约 30-40% 的问题	补充手动键盘和屏幕阅读器测试
显示“无违规项”，但表单存在问题	axe 不会测试表单逻辑或流程	手动测试表单提交和错误处理
Playwright axe 测试超时	页面规模较大或结构复杂，耗时过长	增加超时时间，或分析特定区域
自定义组件出现误报	axe 规则无法识别该模式	使用 disableRules，或添加正确的 ARIA 来修复
第三方小组件存在违规项	无法修改外部代码	记录例外情况、联系供应商或替换小组件
不同浏览器中的结果不同	浏览器特定的渲染差异	在多个浏览器中运行 axe，并使用跨浏览器测试套件
CI 失败，但本地通过	环境差异（时序、内容）	确保测试数据和等待条件一致
违规项过多，无法一次性修复	旧代码库中存在大量问题	创建基线，并使用 --save 标志跟踪改进情况