Cypress-axe插件无障碍测试触发page-has-heading-one规则假阳性报错

核心根因 #

这个假阳性不是插件扫描bug，是DOM上显式ARIA属性直接覆盖了原生HTML的默认语义，导致axe规则判定逻辑错位：

• page-has-heading-one规则的判定逻辑，从来不是匹配DOM原生的<h1>标签元素，而是识别页面中具备**一级标题语义（ARIA角色为heading，且显式/隐式aria-level=1）**的元素
• 对照你当前的涉事DOM结构，存在两处明确的语义覆盖问题：

<!-- 存在语义冲突的原始DOM结构 -->
<div role="main" class="example-slider">
  <!-- 硬加的role="banner"覆盖了h1的原生标题语义 -->
  <h1 role="banner">Slider</h1>
  <!-- 硬加的role="contentinfo"覆盖了滑块的控件语义 -->
  <mat-slider 
    min="1"
    max="50"
    step="0.5"
    themePalette="primary"
    id="slide"
    value="1.5"
    aria-label="slider"
    role="contentinfo"
  >
  </mat-slider>
</div>

• 根据ARIA规范，显式声明的role优先级远高于原生HTML的默认语义，上面h1标签的role="banner"会直接把元素原本自带的role=heading、隐式aria-level=1的语义完全替换成banner（页面横幅地标角色）。axe扫描到这个元素时，只会把它判定为顶部横幅区域，根本识别不到它的一级标题属性，自然会抛出“页面缺失一级标题”的报错，哪怕页面里实打实存在原生h1元素
• 其中mat-slider标签上的role="contentinfo"（页脚信息地标角色），和滑块控件本身的交互语义存在直接冲突，后续还会触发更多规则误判

具体修复方案 #

• 移除<h1>标签上冗余的role="banner"属性
  • 保留原生h1的默认语义，即可被axe正确识别为一级标题，通过page-has-heading-one规则校验
  • 如果业务确实需要为页面添加banner地标角色，不要把role加在标题元素上，直接把role="banner"声明在页面最外层的根容器上，避免覆盖核心元素的语义
• 移除<mat-slider>标签上冗余的role="contentinfo"属性
  • Angular Material的滑块组件本身已经内置了符合规范的滑块控件无障碍语义，硬叠加地标类role会直接覆盖控件本身的交互语义，引发后续的规则误判
• 针对当前测试环境（Cypress 6.1 + Storybook + cypress-axe 0.12.0）的适配调整
  • 不要为了消报错直接全局禁用page-has-heading-one规则，修正上述语义冲突后，规则会正常识别页面中的h1元素
  • 由于Storybook的预览容器本身是隔离的iframe结构，可临时给预览区的根元素补充role="main"地标声明，避免axe扫描时因地标层级缺失，出现标题语义判定错位的问题

内容的提问来源于stack exchange，提问作者r.wadera