Agent Skills
返回列表
💻

Playwright无障碍审计运行器

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中：

请根据 https://skillhub.cn/install/skillhub.md 安装 @user_3c6cb52e/playwright-accessibility-audit-runner。

技能介绍

你要解决什么问题

当前端页面在Chrome里看起来一切正常时，键盘用户可能根本无法完成登录，屏幕阅读器也读不出<button>的实际角色。这类缺陷不会出现在页面崩溃日志里，却会直接把一部分用户挡在门外。更麻烦的是，人工检查每个表单控件和弹窗要花大量时间，而且很容易漏掉边界情况，比如动态渲染的下拉菜单、焦点陷阱模态框、未声明的aria-expanded状态。

Playwright 无障碍审计运行器把这件事变成可重复执行的命令行流程。

它是怎么工作的

技能基于 Playwright 驱动真实浏览器环境，整合 axe-core 注入页面并执行自动化扫描。关键步骤如下：

  • 用 Playwright 打开目标 URL，等待页面就绪，必要时可指定设备尺寸、视口和用户代理
  • 将 axe-core 注入当前文档，对 DOM 树执行 WCAG 2.1 AA / AAA 规则集检查
  • 收集违规节点信息，包括命中元素的 CSS 选择器、ARIA role 属性分析结果，以及对应的修复建议
  • 输出结构化审计报告，可直接接入 CI 流程做回归防护

因为跑在真实浏览器里，它检查的是渲染后的实际 DOM，而不是源码字符串。这一点对SPA尤其重要——组件切换、异步加载的内容都能被正确审计。

适用边界与注意点

  • 扫描范围由 axe-core 规则集决定，它覆盖大量常见场景，但不是所有 WCAG 条款的逐条映射，复杂语义仍需人工复核
  • 动态内容需要在合理等待后才会稳定；异步加载的面板如果审计时尚未渲染，不会被纳入检查
  • 它识别的是技术违规，不判断视觉设计是否真正易用；颜色对比度之外的主观可用性问题，不在报告范围内
  • Playwright 本身也提供 Python、.NET、Java 绑定，可根据项目技术栈选择对应运行时
  • 报告中的修复建议是通用性的，具体到业务组件的语义，仍需开发者结合上下文调整

使用场景

  • 编写前端项目 CI 脚本时，需要对 PR 触发的页面执行自动化检查并拦截不合规改动。
  • 对 SPA 做自动化检查，确保异步渲染的表单组件在真实浏览器里的 ARIA 语义无违规。
  • 编写端到端测试脚本，顺便通过注入 axe-core 为关键页面生成 WCAG 违规详情和 CSS 定位。
  • 存量项目改造无障碍特性，需要快速定位动态下拉菜单或焦点陷阱弹窗的键盘导航缺陷。

适合人员

  • 前端工程师：编写自动化测试时，希望直接获取违规元素的 CSS 选择器和修复建议，快速定位组件问题。
  • QA 测试人员：负责无障碍回归测试，需要把 WCAG AA/AAA 规则集嵌入 CI 流程，拦截每次代码变更引入的新缺陷。
  • 全栈开发者：使用 Python 或 Java 后端做全栈开发，希望复用同一套 Playwright 审计能力来检查渲染后的页面 DOM。
  • 开源库作者：维护 UI 组件库，要在发布前对大量动态渲染控件做批量的 ARIA 角色和键盘可访问性检查。