测试【免费下载链接】axe-coreAccessibility engine for automated Web UI testing项目地址https://gitcode.com/gh_mirrors/ax/axe-core点击查看免费下载axe-coreAccessibility engine for automated Web UI testing自动化 Web UI 无障碍测试引擎在 doc/examples/pr-review-patterns.md 中沉淀了一套代码审查经验哪些问题会被审查者点名、哪些做法能让审查者满意、以及 PR 提交中最常见的失误。本指南以这份文档为骨架结合仓库内 doc/pull-request-checklist.md、doc/code-submission-guidelines.md 以及lib/、test/下的真实源码与测试逐条展开讲解。读完你可以完整掌握为 axe-core 贡献代码时应遵守的测试、提交信息、导入、代码风格、性能、结果完整性与无障碍边界规范并直接套用文末的提交前自检清单。一、这份文档在仓库中的定位doc/examples/pr-review-patterns.md是 axe-core 维护者内部沉淀的代码审查备忘它与另外两份规范文档互为补充doc/pull-request-checklist.md可勾选的 PR 提交清单按 Code / Tests / Formatting Build / Commits / Docs 分类是本文所有点名项的可执行化版本doc/code-submission-guidelines.md完整的代码与提交规范包含 Return Early 模式的前后对比示例、DocBlock 注释示例、Angular 提交格式、集成测试编写方法与 PR 合并流程。阅读顺序建议先通读本文的模式总览再对照 checklist 逐项自检遇到具体写法要求时翻看 submission guidelines 的完整示例。二、审查中被点名的七类问题原文档将审查中最常被指出、最典型的反模式归纳为七类。下面逐一展开并给出仓库内的实际证据。1. 缺失测试要点任何改变行为的代码改动都需要单元测试规则rule改动需要集成测试HTML JSON 配对相关检查check/规则只要涉及 Shadow DOM 就必须有对应测试覆盖。在 axe-core 中一条无障碍规则由规则定义 JSON 匹配器 检查check组成因此测试也分层单元测试针对检查的 evaluate 函数与 commons 工具位于 test/checks 与 test/commons集成测试规则改动必须在 test/integration/rules 下新增或更新一个 HTML JSON 配对。HTML 文件中放置被测代码JSON 文件声明期望结果。以aria-roles规则为例aria-roles.html 中每个待测元素都有唯一id如div rolecommand idfail1fail/div而 aria-roles.json 把 id 分门别类加入violations与passes数组{ description: aria-roles tests, rule: aria-roles, violations: [[#fail1], [#fail2], [#fail3]], passes: [[#pass1], [#pass2]] }注意violations/passes中的元素本身是数组——这是 axe-core 的选择器selector格式单个字符串是 CSS 选择器多个字符串时最后一个字符串是最终选择器其余表示文档内 iframe 的嵌套结构Shadow DOM 覆盖checklist 明确要求Shadow DOM test case added where relevant。这并非空话——检查层对 Shadow DOM 场景做了专门的语义区分例如 aria-valid-attr-value.json 中针对 ID 引用提供了noId与noIdShadow两个不同的 incomplete 消息变体后者专门描述ID 存在于页面但属于不同 shadow 树的情况测试自然要覆盖到。2. 提交信息格式违规要点类型/范围写错、未使用祈使句现在时、主题过长或首字母大写、footer 缺少 issue 引用。axe-core 采用 Angular 提交规范见 doc/code-submission-guidelines.md 的 Git Commits 一节提交信息由 header、body、footer 三部分组成type(scope): subject 空行 body 空行 footertype必须是以下之一feat新功能、fix缺陷修复、docs仅文档、style不影响语义的格式改动、refactor既非修复也非新功能的代码调整、perf性能改进、test补充测试、chore构建过程或辅助工具、ciCI 配置scope指明改动在代码库中的位置例如feat(rule)或test(commons/aria)rule作为 scope 会在 changelog 中被特别标注scope 过宽时也可以省略括号只写 typesubject使用祈使句现在时change 而非 changed/changes、首字母小写、结尾无句号整个 header 控制在 100 字符以内便于在各种 git 工具中阅读body同样使用祈使句现在时重点说明改动动机motivation以及与改动前行为的对比footer引用本提交解决的 issue。仓库的实际做法是不自动关闭 issue由 QA 团队验证后再关闭因此使用Closes issue #123或完整 URL 来关联而非关闭。规范示例来自 submission guidelinesperf(rule): improve speed of color contrast rules Use async process to compare elements without UI lockup Closes issue #13. 导入违规要点core/utils禁止导入commons必须使用直接文件路径导入而非 index 导入node 模块只能通过core/imports导入。这三条限制对应 axe-core 的分层架构core/utils处于核心层若反向依赖commons会造成层级循环依赖。checklist 原文是 Imports follow directory restrictions — especially nocommonsfromcore/utils直接用文件路径导入避免引入整个 index 的循环依赖风险也让构建产物更精简仓库将 Node 环境依赖集中隔离在 lib/core/imports 目录——实际只包含 index.js 与 polyfills.js。新增 node 模块依赖时必须放到该目录并由它统一转发防止浏览器构建产物被 Node API 污染。4. 代码风格问题要点未使用 return early 模式、default export 未放在文件顶部、可以用提前 return 却写嵌套条件、缺少 JSDoc 注释。Return Early / Happy Path Coding主执行流应保持在左侧单列用if主要处理错误与边界情况允许函数出现多个return。submission guidelines 给出了同一函数的两种写法对比。嵌套版把校验层层包在if/else里可读性差return early 版先处理空路径、再处理非绝对路径、逐个 try 解析文件与 JSON最后校验results?.testRunner?.name ! axe并返回校验结果主流程一眼可读Default export 置于顶部default export应紧跟 import 语句和模块级变量之后打开文件第一眼就能看到主代码路径。遇到仓库中不符合此约定的旧文件应顺手修正JSDocDocBlock注释用于描述函数行为、签名与输入尤其公共/导出 API 必须有。submission guidelines 的示例/** * Calculate the distance between two points. * param {number[]} pointA The first point represented by the array [x,y] * param {number[]} pointB The second point represented by the array [x,y] * return {number} */ function distance(pointA, pointB) { return Math.hypot(pointA[0] - pointB[0], pointA[1] - pointB[1]); }5. 性能隐患要点循环中不必要的 DOM 查询、不缓存 Virtual Node 属性、同一值重复计算而不存储。无障碍引擎需要在整棵 DOM 树上逐节点执行检查性能直接决定对大型页面的可用性因此审查者会格外在意不要在遍历节点的循环内反复querySelector虚拟节点Virtual Node的可计算属性应缓存同一值如字号、字体粗细、对比度只算一次。color-contrast-evaluate.js 是很好的正面教材fontSize、fontWeight在函数开头用getComputedStyle各取一次之后计算 pt 字号、判断粗细、写入this.data()时反复复用而不是每次使用都重新查询对比度结果还用Math.floor(contrast * 100) / 100截断后一次性写入 data。commons 层同样以缓存为导向例如颜色对比相关的incompleteData状态对象避免重复计算。6. 不完整结果要点检查无法得出结论时必须返回undefined检查 JSON 中缺失 incomplete 消息变体incomplete 场景未设置合适的this.data()。axe-core 的检查check返回值有三种语义true通过、false失败、undefined表示无法确定后者会进入incompleteneeds review结果。审查者要求能确定就返回布尔值不能确定就如实返回undefined并配齐 JSON 中的 incomplete 消息。以 color-contrast.json 为例metadata.messages.incomplete下声明了bgImage、bgGradient、imgNode、bgOverlap、complexTextShadows、fgAlpha、elmPartiallyObscured、elmPartiallyObscuring、outsideViewport、equalRatio、shortTextContent、emptyValue、nonBmp、pseudoContent、colorParse等十余种变体对应无法判定对比度的各种真实场景。实现侧 color-contrast-evaluate.js 展示了返回undefined的典型路径文本全部是 emoji 且配置了ignoreUnicode时this.data({ messageKey: nonBmp })后return undefined第 39-41 行存在伪元素遮挡时写入pseudoContent消息键、关联伪元素节点后return undefined第 63-72 行文字阴影过于复杂无法解析时写入complexTextShadows后return undefined第 80-82 行前景色或背景色缺失、对比度等于 1、内容过短等情况第 169-181 行统一在this.data()中设置messageKey并调用this.relatedNodes(bgNodes)关联背景节点后return undefined。这些代码正是返回undefined 设置this.data() 补齐 incomplete 消息变体三要素的标准实现可作为编写新检查的模板。7. 无障碍边界情况要点未考虑全部 ARIA 状态、隐藏元素边界情况缺失、Shadow DOM 处理不当。axe-core 的检查必须覆盖元素的各种 ARIA 状态与属性组合隐藏元素hidden、aria-hidden、display:none 等是否该被检查、是否返回隐藏专用消息如 color-contrast 的hidden消息键以及 Shadow DOM 中跨树引用的判定——例如 aria-valid-attr-value.json 中noIdShadow专门处理ID 在另一个 shadow 树中的情形。新增或修改检查时应把 ARIA 规范里的每个相关状态、每个隐藏方式、shadow 边界情况都枚举成测试用例。三、审查者欣赏的品质原文档总结了六条审查者真正看重的品质可以反向理解为理想 PR 的样子包含边界情况的全面测试覆盖不仅测主路径还要测 null、空值、隐藏、shadow 等边界。单元测试覆盖所有代码路径checklist 指出仅公共 API 函数需要显式测试 null/undefined 输入处理清晰详尽的提交信息subject 之外body 说明动机为什么改footer 关联 issue解释为什么而非仅是什么的 JSDoc公共 API 的 DocBlock 应说明设计意图注重性能并合理缓存的代码避免循环内 DOM 查询、避免重复计算参见上文第 5 点遵循同类文件的既有模式新检查/新规则应模仿同目录下已有文件的写法如lib/checks/*的 evaluate JSON 结构、lib/rules/*的规则定义同时覆盖通过与失败用例的集成测试集成测试不仅要断言违规元素被报告violations也要断言合规元素不被误报passes。四、常见 PR 错误原文档列出了八个最高频的 PR 失误逐条说明如下推送前未在本地运行测试。仓库脚本定义在 package.json当前以 pnpm 作为包管理器packageManager: pnpm11.17.0。对应原文档提到的npm test本仓库实际执行pnpm test单元测试此外还有pnpm run test:integrationChrome 集成测试、test:virtual-rules、test:act、test:apg、test:examples、test:node、test:jsdom、test:locales等针对不同场景的测试入口未将自动生成的locales/_template.json与消息源改动放在同一 commit。locales/_template.json是构建阶段由消息源checks/rules 的 JSON 元数据自动生成的跟踪文件postbuild脚本会对其执行 prettier消息文案一旦变化就必须与源码同 commit 提交否则仓库处于不一致状态一个 PR 混入多个无关改动。重构与功能开发应拆分为不同 PRchecklist 明确refactoring 与 feature work 分开便于审查、回滚与 changelog 生成改变规则行为后未更新集成测试。规则行为变化必然牵动 test/integration/rules 下对应 HTML/JSON 配对必须同步增删violations/passes条目提交了console.log。调试输出不得入库checklist 的 Code 部分列为必检项lint-staged 与 eslint 也会拦截未优雅处理null/undefined。evaluate 函数对可能为空的输入如缺失属性、空字符串、解析失败的节点要显式处理而不是假设其存在硬编码应来自standards/数据的字符串。ARIA 角色、属性、HTML 元素规范集中在 lib/standards通过 lib/commons/standards 的查询函数如get-element-spec、get-global-aria-attrs、get-aria-roles-by-type获取。代码中不得手写 ARIA/HTML 清单否则规范更新时规则会失真checklist 原文No hardcoded ARIA/HTML lists — queried fromstandards/viacommons/standards修改公共 API 却未在 footer 标注BREAKING CHANGE。破坏性变更必须显式声明供 changelog 生成迁移指南。规范写法feat(rules): remove deprecated rules BREAKING CHANGE: remove rules: th-has-headers, checkboxgroup, radiogroup若可避免破坏checklist 建议优先同时兼容新旧格式无法避免时除 footer 标注外还需更新 doc/API.md、axe.d.ts、CHANGELOG.md及locales/_template.json。五、提交前自检清单将上述模式汇总为提交前逐项检查的速查表完整可勾选版本见 doc/pull-request-checklist.md维度检查项代码default export 位于文件顶部、紧跟 importreturn early 模式无可用提前返回却嵌套的条件公共 API 有 DocBlock无console.log无硬编码 ARIA/HTML 清单导入遵守目录限制core/utils不导入commonsnode 模块只走core/imports测试单元测试覆盖所有代码路径规则改动有集成测试 HTML JSON 配对相关规则更新虚拟规则测试virtual-rules涉及处补充 Shadow DOM 用例pnpm run build后本地通过pnpm test、test:integration、test:virtual-rules、test:act、test:apg、test:examples、test:node、test:jsdom格式与构建pnpm run fmtPrettier通过pnpm run eslint通过pnpm run build生成的跟踪文件如locales/_template.json、doc/rule-descriptions.md与源码同 commit提交信息Angular 格式type(scope): subject祈使句现在时、小写开头、无结尾句号、≤100 字符body 说明动机footer 含Closes issue: #123或完整 URL破坏性变更标注BREAKING CHANGE:文档新规则确保doc/rule-descriptions.md由构建正确再生成API 变更同步更新doc/API.md与axe.d.ts消息变更同步locales/_template.json破坏性变更在CHANGELOG.md提供迁移指南结语PR Review Patterns 这份文档的价值在于把多年审查经验浓缩成会点名什么、欣赏什么、常错什么三个维度。真正吃透它意味着你的每个 PR 都能一次性通过测试、格式、提交信息与架构约束四道关卡测试覆盖到边界与 Shadow DOM提交信息遵循 Angular 规范并说明动机导入遵守分层约束检查函数在无法判定时如实返回undefined并配齐 incomplete 消息性能上避免重复计算数据全部取自standards/。对照本文第五节的速查表逐项勾选再配合 doc/code-submission-guidelines.md 中的完整示例即可稳定产出符合 axe-core 社区标准的贡献。赞分享测试【免费下载链接】axe-coreAccessibility engine for automated Web UI testing项目地址https://gitcode.com/gh_mirrors/ax/axe-core点击查看免费下载相关推荐Thunderbird for Android 代码审查指南PR 作者与审查者的完整协作规范Thunderbird for Android 代码审查指南PR 作者与审查者的完整协作规范 本文是基于 Thunderbird for Android前身移动开发企业应用Presto PR 代码审查指南基于 review-presto-pr 技能的完整审查流程与规范Presto PR 代码审查指南基于 review presto pr 技能的完整审查流程与规范 导读 本文基于 Presto 官方仓库 prestodb/大数据数据库后端AtomCode AI 代码审查实战/review 命令与深度审查模式完整指南AtomCode AI 代码审查实战/review 命令与深度审查模式完整指南 AtomCode 是一款用 Rust 构建的开源 AI 代码审查工具也是 C人工智能AI Agent代码智能体自主智能体MCP ClientsCLI上一篇BCQ算法代码精读VAE生成模型与扰动Actor如何重塑动作分布下一篇ComponentName 组件规范创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考