无障碍 Storybook 测试

Storybook 组件测试

我们使用 Storybook test-runner 和 axe-playwright 来自动测试 Vue 组件的无障碍违规问题。

这种方法让我们可以独立测试组件，并在开发早期发现无障碍问题。

前置条件

在运行 Storybook 无障碍测试之前，请确保你已：

1. 所有依赖已安装 (yarn install)
2. 一个已构建的 Storybook 实例正在运行

运行 Storybook 无障碍测试

要为 Vue 组件运行自动化的无障碍测试：

步骤 1：启动 Storybook

首先，启动 Storybook 开发服务器。你有两种选择：

# 选项 1：使用新的 fixtures 启动 Storybook
yarn storybook:start

# 选项 2：不更新 fixtures 启动 Storybook（后续运行更快）
yarn storybook:start:skip-fixtures-update

重要提示： 在整个测试会话期间，请保持 Storybook 服务器运行。测试正常运行需要 Storybook 已构建并可访问。

步骤 2：运行无障碍测试

在另一个终端中，从 GitLab 项目的根目录下，运行：

yarn storybook:dev:test

此命令将会：

1. 针对你正在运行的 Storybook 实例启动测试运行器。
2. 遍历所有 story。
3. 对每个 story 运行 axe-playwright 无障碍检查。
4. 报告发现的任何无障碍违规问题。

理解测试结果

测试运行器将输出：

• 通过的测试：符合无障碍标准且没有运行时错误的组件。
• 失败的测试：
  • 带有运行时错误的组件。
  • 带有无障碍违规的组件，包括：
    • 失败的具体无障碍规则
    • 导致违规的元素
    • 严重级别（严重、高危、中等、轻微）
    • 可用时的建议修复方案

测试运行的完整输出可以在 storybook/tmp/storybook-results.json 文件中找到。

Storybook 无障碍测试的最佳实践

1. 测试所有 story 变体：确保组件中的每个 story 都代表不同的状态和配置
2. 包含交互状态：创建展示 hover、focus、active 和 disabled 状态的 story
3. 使用不同数据进行测试：使用反映实际使用场景的真实数据
4. 立即处理违规问题：一旦发现问题，立即修复无障碍问题
5. 记录组件的无障碍性：在组件的 story 文档中包含无障碍性考量

与开发工作流的集成

考虑将 Storybook 无障碍测试集成到你的开发流程中：

1. 在组件开发期间：频繁运行测试以尽早发现问题
2. 在合并请求之前：确保所有新组件或修改过的组件都通过无障碍测试

故障排除

如果测试无法运行：

1. 检查 Storybook 是否正在运行：确保你的 Storybook 服务器可以在预期的 URL 访问
2. 验证依赖项：运行 yarn install 以确保所有包都已安装
3. 检查构建错误：查看 Storybook 构建输出中的任何错误
4. 清除缓存：如果遇到意外问题，尝试重启 Storybook

获取帮助

• 关于无障碍测试的问题，请参阅我们的 前端测试指南
• 关于无障碍最佳实践，请参阅我们的 无障碍最佳实践指南
• 关于特定组件的无障碍指导，请查看 Pajamas 组件文档
• 如果你发现需要全局更改的无障碍问题，请创建一个后续 issue，并添加标签：accessibility 和无障碍严重性标签，例如 accessibility:critical。 测试输出会为你指定严重性级别。