如何为pa11y axe runner添加并运行自定义检测规则

pa11y没有直接暴露axe的checks配置传递入口，你需要通过注入脚本的方式，在页面上下文中直接对axe实例做自定义配置，即可正常运行自定义规则。

具体操作 #

1. 封装自定义规则注入脚本 #

将你的axe自定义规则、checks配置封装为可在页面上下文执行的脚本，确保所有逻辑不依赖Node.js环境的外部变量。

2. 配置pa11y注入脚本 #

通过pa11y的beforeScript配置项，将自定义配置脚本注入到测试页面，同时在pa11y的rules配置中启用你的自定义规则，参考代码如下：

const pa11y = require('pa11y');

// 自定义axe规则的注入脚本
const injectAxeCustomConfig = `
window.addEventListener('load', function() {
  // 等待页面内axe实例加载完成后执行配置
  if (window.axe) {
    axe.configure({
      disableOtherRules: true,
      rules: [
        {
          id: 'my-cool-rule',
          enabled: true,
          all: ['auto-fail'],
        },
      ],
      checks: [
        {
          id: 'auto-fail',
          metadata: {
            impact: 'critical',
            messages: {
              pass: 'Surprise! This test passed!',
              fail: 'This test did not pass, sadly.',
            },
          },
          evaluate: function () {
            return false;
          },
        },
      ]
    });
  }
});
`;

// 执行pa11y检测
(async () => {
  const testResults = await pa11y('替换为你的测试页面URL', {
    runner: 'axe',
    // 注入自定义配置脚本
    beforeScript: injectAxeCustomConfig,
    // 启用自定义规则
    rules: {
      'my-cool-rule': true
    }
  });
  // 输出检测到的问题
  console.log(testResults.issues);
})();

注意事项 #

• 若不需要关闭所有内置axe规则，删除配置中的disableOtherRules: true即可。
• 自定义规则、check的id不要和axe内置规则id重复，避免出现冲突。
• 若注入后规则未生效，可将配置逻辑放到pa11y的actions队列中执行，确保在axe检测运行前完成配置。

内容的提问来源于stack exchange，提问作者calebtr