自定义 cypress-axe 违规报告:violationCallback 搭配 cy.task 输出终端表格的完整教程【免费下载链接】cypress-axeTest accessibility with axe-core in Cypress项目地址: https://gitcode.com/gh_mirrors/cy/cypress-axecypress-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-axe2️⃣ 安装 cypress-axe 及依赖npm install --save-dev axe-core cypress cypress-axe3️⃣ 在 Cypress 支持文件中引入命令Cypress v10 为cypress/support/e2e.js本项目中的引入方式见 cypress/support/e2e.jsimport 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.jsmodule.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.checkA11ycy.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考