用途:当 UI 重构保住视觉却破坏无障碍语义时,用契约测试锁定辅助技术依赖的语义。核心原则是把无障碍语义当作可测试契约,而非审计清单。
主要能力:锁定角色(按用户遇到的角色查询 dialog、button、menuitem、combobox、tab、tabpanel、status,避免查实现包装器)、可访问名称(断言用户听到的标签)、状态(aria-expanded、aria-selected、aria-checked、选中项、禁用、校验错误文本)、焦点与键盘路径、辅助技术可见性。可与 axe 类审计互补,审计查宽泛违规,契约测试查产品特有回归。
使用方式:用 role+name 查询,如 getByRole('dialog', { name: /delete project/i })(Playwright / Testing Library),一次定位同时断言角色、名称与可见性。可写哨兵测试文件,遍历应用内所有弹窗或重复控件,断言各自通过语义契约解析。菜单按钮、组合框/列表框、标签页等非对话框控件各保留一个正常路径加最易回归的语义状态断言。
对话框最低要求:容器暴露 role="dialog" 或 alertdialog;仅当真正模态时才加 aria-modal="true";必须有可访问名称(aria-label 或指向可见标题的 aria-labelledby);纯装饰遮罩与定位外壳不加交互角色;打开时焦点进入,关闭时默认回到触发元素。
适用场景:对话框、菜单、组合框、标签页、虚拟化列表/表格、动画后焦点移动等无障碍回归场景。
限制:lint 等静态分析只能查属性级错误,需这些测试验证最终可访问树;role+name 查询硬编码文案,本地化应用需从消息 ID 或固定数据驱动期望名称;可编辑/自动补全组合框可能无 aria-selected,应断言输入值;虚拟化本身不是缺陷,需测用户实际收到的渲染契约;仅当动画影响无障碍契约时才纳入本技能。完整资料还给出常见缺陷与 PR 准入判断,要求发现须满足用户可操作界面、渲染契约确实损坏、有可先失败后通过的小回归测试。