axe-core 无障碍测试引擎实战把 WCAG 检查变成一条可重复执行的代码流水线【免费下载链接】axe-coreAccessibility engine for automated Web UI testing项目地址: https://gitcode.com/gh_mirrors/ax/axe-core当让所有人无障碍使用产品从道德倡议变成法律底线想想 ADA 诉讼与 WCAG 2.2 的合规要求前端团队最头疼的往往不是改代码而是怎么证明我改好了。axe-core 正是为解决这个难题而生的开源自动化无障碍测试引擎由 Deque 团队持续维护它能把 WCAG 规范翻译成一条条可编程的检查指令官方统计显示平均能帮你定位约 57% 的 WCAG 问题——在人工审计介入之前机器已经替你扫掉了大半雷区。一、先回答一个问题人工无障碍审计到底哪里不行很多团队的第一反应是找咨询公司做一次全面审计不就行了。但现实往往是这样时效性差审计报告是一张静态快照页面一改版、组件一重构结论立刻过期。成本高昂资深无障碍专家的工时费不菲不可能每周跑一遍。标准难记WCAG 有几十条准则连资深开发者都未必能背全每条的成功标准。这就像给身体做体检——你可以每年去一次医院但真正能防患于未然的是家里那台血压计。axe-core 扮演的正是血压计的角色把是否达标这个问题变成每轮构建、每次提交都能自动回答的确定性检查。二、从安装到第一份报告全程只需十几分钟上手 axe-core 远比想象中简单。它既可以作为浏览器里的独立脚本运行也可以作为 Node 模块被测试框架调用。克隆仓库并安装依赖git clone https://gitcode.com/gh_mirrors/ax/axe-core cd axe-core npm install随后构建出浏览器可直接引用的产物并启动监听模式方便边改边看效果npm run build # 生成 axe.js npm run develop # 文件变化时自动重新构建最基础的使用方式是加载构建产物后在页面里调用axe.runimport axe from axe-core; const results await axe.run(document, { runOnly: { type: tag, values: [wcag2a, wcag2aa] } }); console.table(results.violations);runOnly参数允许你只跑某几类规则比如只关心 WCAG A 级与 AA 级返回结果里会清晰列出违规节点、影响等级和修复建议。就这样一次全页面扫描完成了——不需要任何人工判断。三、读懂裁判系统规则如何驱动检查axe-core 的源码目录结构本身就在讲一个故事。打开lib/rules/你会看到上百个以 JSON 结尾的规则定义每个规则都描述了什么元素该被检查、用什么标准检查而lib/checks/里则存放着真正执行判断的检查器lib/commons/提供被反复复用的通用工具函数取文本、查角色、算对比度等lib/core/则是统筹执行与结果汇总的引擎。一条规则与多个检查之间的关系可以用一句大白话概括规则是考卷检查是考题。以lib/rules/button-name.json为例它要求按钮必须拥有可感知的名称于是罗列了aria-label、aria-labelledby、non-empty-title、implicit-label等一组检查作为备选答案。而这组答案如何决定最终判定靠的是规则 JSON 里的三个数组any任一通过即通过只要其中一个检查放行该元素就判定为通过。按钮只要有一个可访问名称来源就算合格用any再合适不过。all全部通过才通过所有检查都必须满足缺一不可。none全部拒绝才通过任何一项命中即失败用于禁止性检查比如不应使用会触发放大的 meta viewport。这种组合判定的设计极其优雅新规则不必从零发明逻辑而是像搭积木一样复用已有的检查器复杂的判定关系被拆解成可单元测试的最小单元。四、手写一条检查规则从想法到落地理解了上面的机制写一条自定义规则就顺理成章了。假设我想检查所有链接的 aria-label 不能为空分两步走。第一步在lib/checks/下定义检查器的判定函数。它接收节点、选项和虚拟节点三个参数返回布尔值表示是否通过// lib/checks/shared/aria-label-evaluate.js import { sanitize } from ../../commons/text; import { arialabelText } from ../../commons/aria; function ariaLabelEvaluate(node, options, virtualNode) { return !!sanitize(arialabelText(virtualNode)); } export default ariaLabelEvaluate;第二步用 JSON 声明这个检查的元信息——包括它在规则里对应的判定函数、影响等级以及通过/失败时展示给用户的消息模板{ id: aria-label, evaluate: aria-label-evaluate, metadata: { impact: serious, messages: { pass: aria-label attribute exists and is not empty, fail: aria-label attribute does not exist or is empty } } }之后把检查 id 挂到某个规则的any或all数组中即可生效。项目内部正是这样运转的上百条规则、数百个检查器全部通过这套声明式机制组合起来。规则的tags字段还能标注它对应哪些标准wcag2a、section508、ACT等方便按合规场景批量筛选。五、四条结果路径别再把没报错当通过了跑完扫描如何解读结果axe-core 把每个元素的检查结论收敛成四种状态定义在lib/core/constants.js中状态含义出现在PASS检查通过passes 列表FAIL检查失败violations 列表CANTTELL无法判定需人工确认incomplete 列表NA规则不适用于该元素inapplicable 列表这里最容易踩的坑是incomplete它不代表通过而是证据不足。比如颜色对比度检查遇到背景是 CSS 渐变或图片时引擎无法精确计算前景色与背景色的对比值就会标记为待人工确认。严谨的团队会把violations清零当作硬性门槛把incomplete当作必须人工复核的待办事项。六、把扫描塞进现有测试体系axe-core 真正强大之处在于它天然适配各种测试场景仓库的doc/examples/目录就是一本现成的集成手册Puppeteer在无头浏览器里对页面执行axe.run把结果断言为零违规jest react借助 jsdom 渲染组件后直接跑规则实现组件级无障碍单测Jasmine / Mocha / QUnit都能通过对应的 runner 插件无缝接入Chrome DevTools 协议直接驱动真实浏览器适合集成环境。一个典型的 CI 场景是每次提交触发构建构建完成后用 Puppeteer 对关键页面跑一遍扫描一旦出现violations立即中断流水线。这样无障碍回归从季度人工抽检升级为每次提交自动把关。七、引擎自身的高质量从何而来一个给无障碍挑刺的工具如果自己质量不过关显然没有说服力。axe-core 在这方面堪称行业标杆测试金字塔完备lib/checks、lib/commons、lib/core都配有专属单元测试目录运行npm test即可全量执行对齐 ACT 规则test/act-rules/下按 W3C ACT 规则编号逐一验证例如按钮可访问名称对应97a4e1确保实现与标准严格一致支持 Shadow DOM对现代前端框架的 Web Components 场景引擎能穿透开放影子根节点进行虚拟节点分析多语言报告locales/目录内置包括中文在内的二十余种语言包报告可直接面向非技术团队。这意味着你可以放心把它当作权威裁判而不是另一个需要反复校准的玩具脚本。八、写在最后把无障碍变成工程能力回到开头的比喻无障碍审计不该是一年一次的年检而该是随时代跑的血压监测。axe-core 的价值不在于帮你做一次漂亮的合规报告而在于把无障碍这件模糊的、依赖个人经验的事变成可量化、可回归、可自动化的工程能力。下一次产品经理来问无障碍这块我们做得怎么样你不再需要翻聊天记录找上次的审计 PDF——你只需要跑一遍流水线然后心平气和地打开那份实时报告。现在就去克隆仓库、跑一次构建让你手头最核心的那个页面先接受一次体检。你会发现让技术为所有人服务其实可以是一件很日常的事。【免费下载链接】axe-coreAccessibility engine for automated Web UI testing项目地址: https://gitcode.com/gh_mirrors/ax/axe-core创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考