experience-lwc-accessibility-jest-run

运行 LWC 无障碍 Jest 测试

在 Lightning Web Components 上运行 Sa11y 无障碍单元测试，选择以下任一方式：

• Core（Bazel） — 存在 WORKSPACE 文件时。
• Standalone（Jest） — 不存在 WORKSPACE 文件时。

Selenium 级别的复现、GUS A11yBug 导入以及其他仅限 Salesforce 内部的流程不在本技能的范围内。如需在不运行测试的情况下进行源代码级 WCAG 审查，请参阅 experience-accessibility-validate。

何时使用此技能

• 用户希望在推送修复前，在本地运行无障碍单元测试（Sa11y Jest）。
• 用户已知失败的测试文件路径（例如来自 A11yBug 的 Test_Names__c），希望直接指定该文件。
• 用户正在迭代无障碍修复，需要尽快获得通过或失败的结果。

前置条件

• 对于 Bazel Jest 测试：需要 Salesforce Core 构建环境（存在 WORKSPACE 文件）。
• 对于独立 Jest 测试：需要安装并配置 @sa11y/jest。

工作流

根据环境选择合适的方式。如果当前环境不是 Salesforce Core 构建环境，请勿提及 Core 工作流。

Core（Bazel）

存在 WORKSPACE 文件时使用此模式。基础命令如下：

{coreRootPath}/tools/bazel test [TARGET] --test_output=streamed --test_env=SA11Y_AUTO=1 --test_env=SA11Y_ENABLE_DOM_MUTATION_OBSERVER=1

将 {coreRootPath} 替换为 Core 仓库根目录，将 {moduleName} 替换为模块名称，将 {relativePath} 替换为不带 .test.js 扩展名的测试文件路径。

查找目标和路径：

find {coreRootPath}/{moduleName} -name "*.test.js" -type f
{coreRootPath}/tools/bazel query "tests(//{moduleName}:*)"

组件测试通常位于 modules/{componentDir}/{componentName}/__tests__/ 下。

已知失败测试路径时，优先使用单文件目标：

{coreRootPath}/tools/bazel test //{moduleName}:{relativePath} --test_output=streamed --test_env=SA11Y_AUTO=1 --test_env=SA11Y_ENABLE_DOM_MUTATION_OBSERVER=1

不确定具体测试时，运行模块中的所有 Sa11y Jest 测试：

{coreRootPath}/tools/bazel test //{moduleName}:sa11y_jest_test --test_output=streamed --test_env=SA11Y_AUTO=1 --test_env=SA11Y_ENABLE_DOM_MUTATION_OBSERVER=1

同一条命令可以指定多个模块目标。若要筛选模块内的测试，请添加 --test_arg=--testMatch="**/{modulePath}/**"。

实用选项：

• 更新快照：--test_arg="--updateSnapshot"
• 禁用缓存测试结果：--cache_test_results=no
• 保存渲染后的 HTML： --test_env=SA11Y_ENABLE_RENDERED_DOM_SAVE=1 --test_env=SA11Y_RENDERED_DOM_SAVE_PATH=sfdc-test/unit/javascript/htdocs/sa11y/jest

将 sfdc-test/unit/javascript/htdocs/sa11y/jest 用作渲染后的 DOM 保存路径，以避免 EPERM 错误。

Standalone（Jest）

不存在 WORKSPACE 文件时使用此模式。运行所有无障碍测试：

独立模式下不要添加 SA11Y_* 环境变量前缀；@sa11y/jest 会通过项目的 Jest 配置文件启用。

npm test -- --testMatch="**/*.accessibility.test.js"

或者指定某个文件：

npm test -- src/components/MyComponent/__tests__/MyComponent.accessibility.test.js

使用用户提供的文件名或路径。如果指定的测试位于当前目录中，请保留单独的文件名，不要凭空添加路径。

其他实用选项包括 --coverage、--updateSnapshot、--watch 和 --verbose。若要指定某个测试名称，请使用 npm test -- --testNamePattern="MyComponent accessibility"。

确保 Jest 使用 jsdom 环境并加载项目的 @sa11y/jest 配置文件。将捆绑的 assets/jest.config.js 模板复制或调整后用于项目的 Jest 配置，并将 assets/sa11y-jest-setup.js 复制到 test/setup/sa11y-setup.js。如果项目已有 Jest 配置，请合并相关设置，不要覆盖无关配置。

上面显示的 SA11Y_* 变量仅适用于 Core/Bazel；Bazel 命令已包含这些变量。

回复范围

只回答用户提出的问题。给出所需的命令以及相关退出代码的含义。除非用户提出要求，否则不要添加监视、覆盖率、更新快照、保存 HTML 或其他变体。

预期退出代码

• Bazel：0 表示所有测试均通过，3 表示测试失败，1 表示构建或命令失败。
• Jest：0 表示所有测试均通过，1 表示测试失败或发生错误。

验证清单

• Sa11y Jest 运行已完成，并明确显示通过/失败信号（Bazel 的退出码为 0 或 3；Jest 的退出码为 0 或 1）。
• 如果有意更新了快照，新快照已与修复一同提交。

故障排查

• Bazel 测试“未找到” — 目标路径有误。请记得从 {relativePath} 中移除 .test.js 扩展名。
• 保存 HTML 时失败并出现 EPERM — 请使用规定的保存路径 sfdc-test/unit/javascript/htdocs/sa11y/jest。
• 独立测试无法运行 — 请检查测试命名模式、Jest 配置、@sa11y/jest 依赖项和 jsdom 环境。