cypress-axe a11y 无障碍测试是如何工作的?剖析 src/index.ts 注入、重试与断言核心源码

cypress-axe a11y 无障碍测试是如何工作的?剖析 src/index.ts 注入、重试与断言核心源码【免费下载链接】cypress-axeTest accessibility with axe-core in Cypress项目地址: https://gitcode.com/gh_mirrors/cy/cypress-axecypress-axe 是一个在 Cypress 中做无障碍测试a11y 测试的插件它把 axe-core 注入被测页面检测违规、自动重试并在发现问题时让测试直接失败。全文源码只有 151 行全部集中在 src/index.ts这篇文章带你逐段读懂它的三大核心机制注入、重试、断言。cypress-axe 无障碍测试的 3 个命令一览整个插件对外只暴露 3 个 Cypress 自定义命令都在文件末尾统一注册src/index.ts第 147-151 行命令作用源码位置cy.injectAxe()把 axe-core 运行时注入页面第 30-41 行cy.configureAxe()自定义 axe 规则配置第 43-47 行cy.checkA11y()执行检测、重试并断言第 67-145 行文件开头第 11-17 行通过 TypeScript 全局声明把这 3 个方法挂到Cypress.Chainable上所以你才能以cy.xxx()的形式调用它们。第一步injectAxe 如何把 axe-core 注入页面cy.injectAxe()必须放在cy.visit()之后执行。它的核心逻辑分两步第 31-40 行1. 三级降级定位 axe-core 文件const fileName injectOptions?.axeCorePath || (typeof require?.resolve function ? require.resolve(axe-core/axe.min.js) : node_modules/axe-core/axe.min.js)优先用用户传入的axeCorePath其次用require.resolve解析最后兜底到node_modules/axe-core/axe.min.js。2. 读取文件并在页面里执行cy.readFilestring(fileName).then((source) cy.window({ log: false }).then((window) { window.eval(source) }) )window.eval(source)是关键一笔它让 axe-core 的代码直接在浏览器页面上下文运行从而把全局window.axe挂到页面上第 3-7 行的类型声明正是为此服务。第二步configureAxe 一行代码自定义规则第 43-47 行只有短短几行拿到页面 window 后直接调用win.axe.configure(configurationOptions)。你可以用它注册自定义规则、修改品牌信息等。注意它和checkA11y的 options 的区别configureAxe是永久性配置而checkA11y的 options 只对单次检测生效。第三步checkA11y 的重试与断言核心checkA11y是全文最复杂的部分第 67-145 行可以分为四个环节。清洗空参数拆解重试选项第 75-86 行先用isEmptyObjectorNull第 49-54 行的小工具函数把{}、null统一归一为undefined然后从 options 中拆出includedImpacts、interval、retries剩下的才透传给axe.runconst { includedImpacts, interval, retries, ...axeOptions } options || {}summarizeResults第 56-65 行会根据includedImpacts数组过滤违规项比如只关心[critical, serious]级别的无障碍问题。retries interval面向动态内容的重试机制这是 cypress-axe 最实用的设计。核心递归逻辑第 87-101 行const results summarizeResults(includedImpacts, violations) if (results.length 0 remainingRetries 0) { remainingRetries-- return new Promise((resolve) { setTimeout(resolve, interval || 1000) }).then(runAxeCheck) } else { return results }翻译成人话如果检测到违规且还有重试次数就等interval毫秒默认 1000ms后重新跑一次完整检测重试次数耗尽或没有违规才返回结果。这解决了页面动态内容AJAX 请求、懒加载还没渲染完就误报的问题。项目自带的测试用例 cypress/e2e/test.cy.js 就是这么用的cy.checkA11y(undefined, { retries: 20, interval: 10 })违规如何展示Cypress.log 命令日志第 104-126 行每条违规都会调用Cypress.log$el指向违规元素、name显示a11y error!、点击后 DevTools 控制台会输出完整详情consoleProps最后用cy.wrap(violations)把结果传给下一环节。最终断言让测试一步失败第 127-144 行是裁判环节if (!skipFailures) { assert.equal( violations.length, 0, ${violations.length} accessibility violation(s) detected ) }只要存在违规断言立即失败测试随之标红。而skipFailures true时只记录日志不失败——非常适合在旧项目里先观测、后治理逐步收紧无障碍测试标准。跑一个最小 cypress-axe a11y 测试的完整步骤安装依赖peer 依赖包含axe-core和cypress见 package.jsonnpm install --save-dev axe-core cypress cypress-axe在 cypress/support/e2e.js 中引入插件一行import即可完成注册在测试中按visit → injectAxe → checkA11y的顺序调用即上面展示的最小组合如果想 clone 仓库亲手跑一遍仓库地址是https://gitcode.com/gh_mirrors/cy/cypress-axe本地执行npm install后运行npm run cypress即可打开 Cypress 查看效果。小结151 行源码的 3 个精髓注入window.eval一行代码把 axe-core 跑进页面上下文三级路径降级保证兼容性重试retries interval递归重跑检测对动态内容友好避免误报断言assert.equal(violations.length, 0, ...)一步失败skipFailures提供渐进式治理的退路读懂 src/index.ts你就掌握了在 Cypress 中做无障碍自动化测试的全部原理。✅【免费下载链接】cypress-axeTest accessibility with axe-core in Cypress项目地址: https://gitcode.com/gh_mirrors/cy/cypress-axe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考