EUI 屏幕阅读器测试矩阵Screen Reader Testing Matrix分级策略、组合覆盖与实操指南【免费下载链接】euiElastic UI Framework 项目地址: https://gitcode.com/GitHub_Trending/eu/eui本文以 Elastic UIEUI框架的 screen-reader-testing-matrix.md 文档为核心系统讲解 EUI 贡献者在开发组件时如何用「分级测试 组合矩阵」的方式开展屏幕阅读器人工可访问性测试。读者读完将掌握 T1/T2/T3 测试分级规则、桌面端与移动端六种主流屏幕阅读器的浏览器/设备组合优先级以及如何与仓库内的 axe 自动化测试、Cypress 组件测试相衔接形成「自动打底 人工分级」的完整可访问性保障流程。一、文档背景测试优先级的决策依据该矩阵文档基于2022 年 7 月汇总的匿名分析数据编制数据反映 Elastic Cloud 用户中最常见的浏览器、屏幕分辨率与操作系统组合。需要明确的是数据匿名收集仅用于指导测试优先级排序不涉及任何用户身份信息矩阵的目标不是让开发者穷举所有环境组合而是把有限的测试人力集中在真实用户占比最高的场景上避免无差别的全量人工回归。因此该矩阵不是必须全部通过的清单而是一份资源分配策略——它明确回答了在哪个浏览器 哪款屏幕阅读器上必须测、在哪些组合上可以适当放行这一工程实践问题。二、三级测试分级T1 / T2 / T3矩阵采用三档优先级直接决定了一次变更需要投入多大的人工验证成本级别含义适用场景Tier 1 (T1)必须测试所有新组件或重大体验更新significant experience updatesTier 2 (T2)常规 PR 评审周期内时间允许时测试普通变更在走常规代码评审时的补充验证Tier 3 (T3)按需测试由客户或团队成员提出请求时进行从源码实践看EUI 的测试文档体系与这一分级互为补充testing/README.md 明确所有组件至少应具备每个 prop 的单元测试而屏幕阅读器矩阵处理的是单元测试、甚至自动化 axe 测试都覆盖不到的人工听觉验证部分。换言之T1 是硬性门槛T2 是锦上添花T3 是点单式服务。三、完整测试矩阵浏览器 × 屏幕阅读器组合以下是文档给出的原始矩阵逐格继承未做删减JAWS(Win)NVDA(Win)VoiceOver(MacOS)Orca(Linux)iOS VoiceOver(Apple devices)TalkBack(Android devices)ChromeT1T1❌T3❌T3FirefoxT2T1T2T3❌❌EdgeT2T2❌❌❌❌Safari❌❌T1❌T3❌3.1 桌面端核心结论Chrome JAWST1与Chrome NVDAT1是 Windows 生态下唯二的两条硬性门槛所有新组件与重大改版都必须在这两个组合上人工验证Firefox NVDAT1同样列入硬性门槛说明矩阵对 NVDA 跨浏览器的覆盖给予了最高权重Firefox VoiceOverT2、Edge JAWS/NVDAT2属于常规评审周期内的次级验证组合Chrome OrcaT3、Firefox OrcaT3是 Linux 桌面唯一的按需入口Safari 仅与 VoiceOver 配对T1其余组合全部标记 ❌符合 macOS 生态浏览器-读屏强绑定的现实。3.2 移动端核心结论iOS VoiceOverT3与TalkBackT3在 Android 上均按需测试且只与 Chrome 配对移动端整体处于请求驱动级别反映了桌面端仍是 EUI 组件可访问性验证的主战场。四、自动化测试如何与人工矩阵衔接人工屏幕阅读器测试成本高、且依赖测试者经验因此 EUI 的实践是先用自动化工具打底再把人工矩阵用在自动化覆盖不到的地方。4.1 自动化基线axe-core CypressEUI 的可访问性自动化测试构建在 axe-core自动化测试大约能覆盖可访问性需求的 30%但能捕获约 60% 的可访问性缺陷。因此自动化无法替代人工测试却是所有组件的基线。在 defaultAxeConfig.ts 中可以看到默认规则集的具体构成const defaultContext: string div[data-cy-root]; const defaultAxeConfig: RunOptions { runOnly: { type: tag, values: [section508, wcag2a, wcag2aa, wcag21a, wcag21aa], }, rules: { color-contrast: { enabled: false, }, }, };关键点默认同时启用section508、WCAG 2.0A/AA与 WCAG 2.1A/AA标签帮助 EUI 满足美国与欧洲的可访问性法规要求源码注释原文即为此意图color-contrast规则被显式关闭因为 EUI 有经过充分测试的调色板且在 Cypress 中该规则存在误报可能见 defaultAxeConfig.ts 顶部注释引用了 cypress-axe 的 issue #98默认上下文是 Cypress 挂载容器div[data-cy-root]将检测范围限定在当前组件的挂载节点。4.2 违规上报与错误信息解读checkAxe.ts 将 axe 返回的违规对象转换为可读数组并支持两种上报模式logViolationsAndThrow默认打印违规明细并使测试失败logViolationsToConsoleOnlyreport-only 模式仅打印报告、不中断测试通过skipFailures开关启用。违规表格的结构来自 automated-accessibility-testing.mdindexidimpactdescriptionnodes0aria-valid-attr-valuecriticalARIA attributes must conform to valid values11nested-interactiveseriousNested interactive elements are not announced by screen readers3字段含义index页面上可访问性违规的 0 起始序号id对应 axe-core 规则描述可链接到 Deque University 的详细文档impact该违规对用户体验的阻断或降级程度description对问题的一句话说明nodes该类型违规在页面上的出现次数。任何违规都应在 axe 浏览器插件Chrome / Firefox / Edge 可用中复核确认插件通常比 CI 中的规则更严格因此在 CI 里看到的违规一定能在插件中复现。4.3 如何运行 a11y 测试从 package.json 与 test-cypress.js 可以看到实际命令链路yarn test-cypress-a11y等价于yarn test-cypress --a11y无头运行全部 a11y 用例在脚本内部--a11y会把 Cypress 的 spec 切换为--spec./src/**/*.a11y.tsx普通组件测试则匹配*.spec.tsx并以 Chrome 无头组件测试模式执行。a11y 测试文件的命名约定为{component name}.a11y.tsx与组件同目录写法示例// accordion.a11y.tsx describe(Automated accessibility check, () { it(has zero violations when expanded, () { cy.mount( EuiAccordion {...noArrowProps} EuiPanel colorsubdued Any content inside of strongEuiAccordion/strong will appear here. We will include a href#a link/a to confirm focus. /EuiPanel /EuiAccordion ); cy.get(button.euiAccordion__button).click(); cy.checkAxe(); }); });cy.checkAxe()支持四个可选参数详见 cypress-testing.mdskipFailures置true进入 report-only 模式只出报告、不提前失败context检测范围默认div#__cy_rootaxeConfig透传 axe.run API可增删元素、单条规则或整个规则集callback自定义违规回调用于附加副作用或改变上报结构。扩展默认规则集的典型做法是合并defaultAxeConfig后追加标签import { defaultAxeConfig } from ../../cypress/support/a11y/axeCheck; const customAxeConfig { ...defaultAxeConfig, runOnly: { type: tag, // 在既有规则集上追加 best-practices values: [...defaultAxeConfig.runOnly.values, best-practices], }, }; cy.checkAxe(false, customAxeConfig);4.4 真实键盘事件Cypress Real Eventscypress-testing.md 还提到EUI 借助 Cypress Real Events基于 Chrome Devtools Protocol发送真实浏览器事件以验证键盘焦点与屏幕阅读器状态随用户操作的变化例如cy.realMount(TestComponent /); cy.get([data-test-subjsubmitButton]).realPress(Enter); cy.focused().invoke(attr, aria-expanded).should(equal, true);这为人工矩阵补充了键盘交互状态的可重复自动化验证进一步收窄了人工测试的验证范围。五、EUI 测试栈全景人工矩阵在整个体系中的位置从 testing/README.md 可以定位屏幕阅读器矩阵在整个测试体系中的坐标Jest 单元测试unit-testing.md每个组件的必备项新测试使用 React Testing Library 编写Cypress 组件测试cypress-testing.md用于复杂组件、真实 DOM 交互其中*.a11y.tsx专门承载 axe 自动化检测Storybook 视觉回归测试visual-regression-testing.mdPlaywright jest-image-snapshot屏幕阅读器人工测试矩阵本文主题在上述自动化全部通过之后按 T1/T2/T3 分级进行人工听觉验证。关系可以概括为自动化axe/Cypress负责基线正确人工矩阵负责真实读屏体验。自动化能稳定捕获结构性问题如 ARIA 属性非法、嵌套交互元素但朗读顺序、焦点游走、语境播报等体验性问题只能靠人工矩阵中的 T1 组合来兜底。六、按矩阵执行人工测试的实操建议结合分级规则与真实工作流一次完整的人工验证可以按以下顺序推进改动发生时先跑自动化执行yarn test-cypress-a11y确认 axe 违规为零若有违规先修复并用 axe 浏览器插件复核T1 组合逐一过筛新组件或重大改版至少在 ChromeJAWS、ChromeNVDA、FirefoxNVDA桌面以及 SafariVoiceOver 上走一遍完整交互流程重点听朗读顺序是否自然、焦点是否可见且可达、动态内容如手风琴展开、弹窗触发是否有提示T2 组合按时间补充FirefoxVoiceOver、EdgeJAWS、EdgeNVDA 等组合在常规 PR 评审周期内尽量覆盖T3 组合按需响应遇到客户或团队成员明确提出的环境诉求如 Linux 上的 Orca、移动端 TalkBack再专门排期验证。七、相关资源桌面端屏幕阅读器Using JAWS to Evaluate Web AccessibilityKeyboard shortcuts for JAWSUsing NVDA to Evaluate Web AccessibilityKeyboard Shortcuts for NVDAUsing VoiceOver to Evaluate Web Accessibility移动端屏幕阅读器VoiceOver on MobileUsing TalkBack to Evaluate Web Accessibility仓库内延伸阅读automated-accessibility-testing.md —— axe 自动化检测的完整说明与错误信息解读cypress-testing.md —— Cypress 组件测试、a11y 用例写法与 Real EventscheckAxe.ts ——cy.checkAxe()命令的实现违规上报与 report-only 模式defaultAxeConfig.ts —— 默认规则集与 color-contrast 规则关闭原因test-cypress.js —— a11y spec 匹配逻辑与运行参数testing/README.md —— EUI 整体测试栈概览与代码覆盖率说明【免费下载链接】euiElastic UI Framework 项目地址: https://gitcode.com/GitHub_Trending/eu/eui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 EUI 屏幕阅读器测试矩阵（Screen Reader Testing Matrix）：分级策略、组合覆盖与实操指南
EUI 屏幕阅读器测试矩阵Screen Reader Testing Matrix分级策略、组合覆盖与实操指南【免费下载链接】euiElastic UI Framework 项目地址: https://gitcode.com/GitHub_Trending/eu/eui本文以 Elastic UIEUI框架的 screen-reader-testing-matrix.md 文档为核心系统讲解 EUI 贡献者在开发组件时如何用「分级测试 组合矩阵」的方式开展屏幕阅读器人工可访问性测试。读者读完将掌握 T1/T2/T3 测试分级规则、桌面端与移动端六种主流屏幕阅读器的浏览器/设备组合优先级以及如何与仓库内的 axe 自动化测试、Cypress 组件测试相衔接形成「自动打底 人工分级」的完整可访问性保障流程。一、文档背景测试优先级的决策依据该矩阵文档基于2022 年 7 月汇总的匿名分析数据编制数据反映 Elastic Cloud 用户中最常见的浏览器、屏幕分辨率与操作系统组合。需要明确的是数据匿名收集仅用于指导测试优先级排序不涉及任何用户身份信息矩阵的目标不是让开发者穷举所有环境组合而是把有限的测试人力集中在真实用户占比最高的场景上避免无差别的全量人工回归。因此该矩阵不是必须全部通过的清单而是一份资源分配策略——它明确回答了在哪个浏览器 哪款屏幕阅读器上必须测、在哪些组合上可以适当放行这一工程实践问题。二、三级测试分级T1 / T2 / T3矩阵采用三档优先级直接决定了一次变更需要投入多大的人工验证成本级别含义适用场景Tier 1 (T1)必须测试所有新组件或重大体验更新significant experience updatesTier 2 (T2)常规 PR 评审周期内时间允许时测试普通变更在走常规代码评审时的补充验证Tier 3 (T3)按需测试由客户或团队成员提出请求时进行从源码实践看EUI 的测试文档体系与这一分级互为补充testing/README.md 明确所有组件至少应具备每个 prop 的单元测试而屏幕阅读器矩阵处理的是单元测试、甚至自动化 axe 测试都覆盖不到的人工听觉验证部分。换言之T1 是硬性门槛T2 是锦上添花T3 是点单式服务。三、完整测试矩阵浏览器 × 屏幕阅读器组合以下是文档给出的原始矩阵逐格继承未做删减JAWS(Win)NVDA(Win)VoiceOver(MacOS)Orca(Linux)iOS VoiceOver(Apple devices)TalkBack(Android devices)ChromeT1T1❌T3❌T3FirefoxT2T1T2T3❌❌EdgeT2T2❌❌❌❌Safari❌❌T1❌T3❌3.1 桌面端核心结论Chrome JAWST1与Chrome NVDAT1是 Windows 生态下唯二的两条硬性门槛所有新组件与重大改版都必须在这两个组合上人工验证Firefox NVDAT1同样列入硬性门槛说明矩阵对 NVDA 跨浏览器的覆盖给予了最高权重Firefox VoiceOverT2、Edge JAWS/NVDAT2属于常规评审周期内的次级验证组合Chrome OrcaT3、Firefox OrcaT3是 Linux 桌面唯一的按需入口Safari 仅与 VoiceOver 配对T1其余组合全部标记 ❌符合 macOS 生态浏览器-读屏强绑定的现实。3.2 移动端核心结论iOS VoiceOverT3与TalkBackT3在 Android 上均按需测试且只与 Chrome 配对移动端整体处于请求驱动级别反映了桌面端仍是 EUI 组件可访问性验证的主战场。四、自动化测试如何与人工矩阵衔接人工屏幕阅读器测试成本高、且依赖测试者经验因此 EUI 的实践是先用自动化工具打底再把人工矩阵用在自动化覆盖不到的地方。4.1 自动化基线axe-core CypressEUI 的可访问性自动化测试构建在 axe-core自动化测试大约能覆盖可访问性需求的 30%但能捕获约 60% 的可访问性缺陷。因此自动化无法替代人工测试却是所有组件的基线。在 defaultAxeConfig.ts 中可以看到默认规则集的具体构成const defaultContext: string div[data-cy-root]; const defaultAxeConfig: RunOptions { runOnly: { type: tag, values: [section508, wcag2a, wcag2aa, wcag21a, wcag21aa], }, rules: { color-contrast: { enabled: false, }, }, };关键点默认同时启用section508、WCAG 2.0A/AA与 WCAG 2.1A/AA标签帮助 EUI 满足美国与欧洲的可访问性法规要求源码注释原文即为此意图color-contrast规则被显式关闭因为 EUI 有经过充分测试的调色板且在 Cypress 中该规则存在误报可能见 defaultAxeConfig.ts 顶部注释引用了 cypress-axe 的 issue #98默认上下文是 Cypress 挂载容器div[data-cy-root]将检测范围限定在当前组件的挂载节点。4.2 违规上报与错误信息解读checkAxe.ts 将 axe 返回的违规对象转换为可读数组并支持两种上报模式logViolationsAndThrow默认打印违规明细并使测试失败logViolationsToConsoleOnlyreport-only 模式仅打印报告、不中断测试通过skipFailures开关启用。违规表格的结构来自 automated-accessibility-testing.mdindexidimpactdescriptionnodes0aria-valid-attr-valuecriticalARIA attributes must conform to valid values11nested-interactiveseriousNested interactive elements are not announced by screen readers3字段含义index页面上可访问性违规的 0 起始序号id对应 axe-core 规则描述可链接到 Deque University 的详细文档impact该违规对用户体验的阻断或降级程度description对问题的一句话说明nodes该类型违规在页面上的出现次数。任何违规都应在 axe 浏览器插件Chrome / Firefox / Edge 可用中复核确认插件通常比 CI 中的规则更严格因此在 CI 里看到的违规一定能在插件中复现。4.3 如何运行 a11y 测试从 package.json 与 test-cypress.js 可以看到实际命令链路yarn test-cypress-a11y等价于yarn test-cypress --a11y无头运行全部 a11y 用例在脚本内部--a11y会把 Cypress 的 spec 切换为--spec./src/**/*.a11y.tsx普通组件测试则匹配*.spec.tsx并以 Chrome 无头组件测试模式执行。a11y 测试文件的命名约定为{component name}.a11y.tsx与组件同目录写法示例// accordion.a11y.tsx describe(Automated accessibility check, () { it(has zero violations when expanded, () { cy.mount( EuiAccordion {...noArrowProps} EuiPanel colorsubdued Any content inside of strongEuiAccordion/strong will appear here. We will include a href#a link/a to confirm focus. /EuiPanel /EuiAccordion ); cy.get(button.euiAccordion__button).click(); cy.checkAxe(); }); });cy.checkAxe()支持四个可选参数详见 cypress-testing.mdskipFailures置true进入 report-only 模式只出报告、不提前失败context检测范围默认div#__cy_rootaxeConfig透传 axe.run API可增删元素、单条规则或整个规则集callback自定义违规回调用于附加副作用或改变上报结构。扩展默认规则集的典型做法是合并defaultAxeConfig后追加标签import { defaultAxeConfig } from ../../cypress/support/a11y/axeCheck; const customAxeConfig { ...defaultAxeConfig, runOnly: { type: tag, // 在既有规则集上追加 best-practices values: [...defaultAxeConfig.runOnly.values, best-practices], }, }; cy.checkAxe(false, customAxeConfig);4.4 真实键盘事件Cypress Real Eventscypress-testing.md 还提到EUI 借助 Cypress Real Events基于 Chrome Devtools Protocol发送真实浏览器事件以验证键盘焦点与屏幕阅读器状态随用户操作的变化例如cy.realMount(TestComponent /); cy.get([data-test-subjsubmitButton]).realPress(Enter); cy.focused().invoke(attr, aria-expanded).should(equal, true);这为人工矩阵补充了键盘交互状态的可重复自动化验证进一步收窄了人工测试的验证范围。五、EUI 测试栈全景人工矩阵在整个体系中的位置从 testing/README.md 可以定位屏幕阅读器矩阵在整个测试体系中的坐标Jest 单元测试unit-testing.md每个组件的必备项新测试使用 React Testing Library 编写Cypress 组件测试cypress-testing.md用于复杂组件、真实 DOM 交互其中*.a11y.tsx专门承载 axe 自动化检测Storybook 视觉回归测试visual-regression-testing.mdPlaywright jest-image-snapshot屏幕阅读器人工测试矩阵本文主题在上述自动化全部通过之后按 T1/T2/T3 分级进行人工听觉验证。关系可以概括为自动化axe/Cypress负责基线正确人工矩阵负责真实读屏体验。自动化能稳定捕获结构性问题如 ARIA 属性非法、嵌套交互元素但朗读顺序、焦点游走、语境播报等体验性问题只能靠人工矩阵中的 T1 组合来兜底。六、按矩阵执行人工测试的实操建议结合分级规则与真实工作流一次完整的人工验证可以按以下顺序推进改动发生时先跑自动化执行yarn test-cypress-a11y确认 axe 违规为零若有违规先修复并用 axe 浏览器插件复核T1 组合逐一过筛新组件或重大改版至少在 ChromeJAWS、ChromeNVDA、FirefoxNVDA桌面以及 SafariVoiceOver 上走一遍完整交互流程重点听朗读顺序是否自然、焦点是否可见且可达、动态内容如手风琴展开、弹窗触发是否有提示T2 组合按时间补充FirefoxVoiceOver、EdgeJAWS、EdgeNVDA 等组合在常规 PR 评审周期内尽量覆盖T3 组合按需响应遇到客户或团队成员明确提出的环境诉求如 Linux 上的 Orca、移动端 TalkBack再专门排期验证。七、相关资源桌面端屏幕阅读器Using JAWS to Evaluate Web AccessibilityKeyboard shortcuts for JAWSUsing NVDA to Evaluate Web AccessibilityKeyboard Shortcuts for NVDAUsing VoiceOver to Evaluate Web Accessibility移动端屏幕阅读器VoiceOver on MobileUsing TalkBack to Evaluate Web Accessibility仓库内延伸阅读automated-accessibility-testing.md —— axe 自动化检测的完整说明与错误信息解读cypress-testing.md —— Cypress 组件测试、a11y 用例写法与 Real EventscheckAxe.ts ——cy.checkAxe()命令的实现违规上报与 report-only 模式defaultAxeConfig.ts —— 默认规则集与 color-contrast 规则关闭原因test-cypress.js —— a11y spec 匹配逻辑与运行参数testing/README.md —— EUI 整体测试栈概览与代码覆盖率说明【免费下载链接】euiElastic UI Framework 项目地址: https://gitcode.com/GitHub_Trending/eu/eui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考