自定义 cypress-axe 违规报告:violationCallback 搭配 cy.task 输出终端表格的完整教程

自定义 cypress-axe 违规报告:violationCallback 搭配 cy.task 输出终端表格的完整教程

【免费下载链接】cypress-axeTest accessibility with axe-core in Cypress项目地址: https://gitcode.com/gh_mirrors/cy/cypress-axe

cypress-axe 是一款在 Cypress 中用 axe-core 做可访问性（无障碍）自动化测试的开源插件。默认情况下，它只会在 Cypress 命令日志里标记 "A11Y ERROR!"，在 CI 无头运行时终端只看到一句断言失败，违规详情却难以快速定位。本教程将完整演示如何利用 cypress-axe 的 violationCallback 回调参数搭配 cy.task 命令，把违规结果以清晰的终端表格打印出来，几步代码即可上手。 🎯

🎯 为什么需要自定义 cypress-axe 违规报告

cypress-axe 的核心是cy.checkA11y()命令，它在当前页面运行 axe-core 扫描。检测到违规时，默认行为有两点：

• 每种违规在命令日志中插入一条 "A11Y ERROR!" 条目，测试随即断言失败；
• 终端里只有一句accessibility violation was detected，看不到具体是哪些规则、影响了多少个节点。

而cy.checkA11y()的第三个参数violationCallback正是为"自定义副作用"设计的：你可以拿到完整的违规数组，把它打印到终端、推送到告警工具，或写入缺陷系统。本教程演示最实用的用法——终端表格。

📦 快速安装与项目准备（3 步）

1️⃣ 克隆项目（想阅读源码的话）：

git clone https://gitcode.com/gh_mirrors/cy/cypress-axe

2️⃣ 安装 cypress-axe 及依赖：

npm install --save-dev axe-core cypress cypress-axe

3️⃣ 在 Cypress 支持文件中引入命令（Cypress v10+ 为cypress/support/e2e.js），本项目中的引入方式见 cypress/support/e2e.js：

import 'cypress-axe'

💡 TypeScript 用户记得在 tsconfig.json 中加入"types": ["cypress", "cypress-axe"]，即可获得完整的类型提示。

📝 第 1 步:在 Plugins 文件中注册 log 与 table 任务

关键点：cy.task运行在 Node.js 侧，因此可以直接使用console.table这类终端 API。在 Cypress 插件文件中注册两个任务log（打印普通日志）和table（打印表格），本仓库的任务注册位置参考 cypress/plugins/index.js：

module.exports = (on, config) => { on('task', { log(message) { console.log(message) return null }, table(message) { console.table(message) return null } }) }

🔁 第 2 步:编写 violationCallback 回调函数

回调会收到 axe-core 返回的违规数组，每条记录包含id（规则名）、impact（影响级别）、description（规则描述）、nodes（受影响节点列表）等字段。为了让表格更易读，只抽取 4 个关键字段：

function terminalLog(violations) { cy.task( 'log', `${violations.length} accessibility violation${ violations.length === 1 ? '' : 's' } ${violations.length === 1 ? 'was' : 'were'} detected` ) // 只挑关键字段,保持表格简洁易读 const violationData = violations.map( ({ id, impact, description, nodes }) => ({ id, impact, description, nodes: nodes.length }) ) cy.task('table', violationData) }

这段函数建议定义在 spec 文件顶部，或抽成独立工具模块供所有测试复用。

⚡ 第 3 步:一行代码接入 cy.checkA11y

cy.checkA11y的参数顺序为(context, options, violationCallback, skipFailures)，把上一步的函数作为第 3 个参数传入即可：

it('Logs violations to the terminal', () => { cy.checkA11y(null, null, terminalLog) })

两个细节值得注意：

• 回调遵循includedImpacts过滤器——如果你用includedImpacts限制了影响级别，回调只会收到被保留的违规；
• 回调在断言之前执行，所以无论测试最终是否失败，终端都能看到报告。

📊 终端表格输出效果

运行测试后，执行 Cypress 的终端会先打印一行汇总，再输出对齐的违规表格，规则名、影响级别、描述、节点数一目了然：

8 accessibility violations were detected (index) id impact nodes 0 'color-contrast' 'serious' 75 1 'heading-order' 'moderate' 2 2 'image-alt' 'critical' 23

🧪 对照默认标准输出:命令日志与 Console 详情

自定义终端报告不改变 cypress-axe 的默认行为——命令日志中仍会逐条出现 "a11y error!" 记录，点击后 DevTools Console 会展开该违规的完整上下文（Id、Impact、Tags、Nodes 等）：

也就是说，终端表格负责"快速概览"，命令日志负责"逐条深挖"，两者互补。

🛠 进阶技巧:三个高频选项组合

• 按影响级别过滤：cy.checkA11y(null, { includedImpacts: ['critical'] })，回调与断言都只看 critical 违规，适合老旧项目逐步治理；
• 只报告不失败：cy.checkA11y(null, null, terminalLog, true)将skipFailures设为true，测试通过但终端照常输出表格，是接入存量项目的过渡方案；
• 动态内容重试：{ retries: 3, interval: 1000 }让检查在发现违规后自动重试，避免异步渲染未完成导致的误报。

📌 小结

通过「插件文件注册log/table任务 + spec 中定义terminalLog回调 +cy.checkA11y第三参数接入」三步，就能为 cypress-axe 定制出终端违规表格报告。相比默认的命令日志输出，它让 CI 日志从"一行报错"升级为"可读的违规清单"，帮助团队更快地定位和修复可访问性问题。更多用法可参考项目 README.md，核心实现位于 src/index.ts。

【免费下载链接】cypress-axeTest accessibility with axe-core in Cypress项目地址: https://gitcode.com/gh_mirrors/cy/cypress-axe