configure-ux-testing

/configure:ux-testing

检查并配置 UX 测试基础设施，使用 Playwright 作为端到端、无障碍和视觉回归测试的主要工具。

何时使用此技能

适合使用此技能的情况……	适合采用其他方法的情况……
为项目搭建 Playwright 端到端测试基础设施	运行现有的 Playwright 测试（使用 bun test:e2e 或 test-runner agent）
为项目添加基于 axe-core 的无障碍测试	对线上网站进行手动无障碍审计
配置基于截图断言的视觉回归测试	调试某个特定的失败端到端测试（使用 system-debugging agent）
配置 Playwright CLI 或 MCP，以便 Claude 自动化浏览器操作	编写单个测试用例（使用 playwright-testing skill）
创建用于执行端到端和无障碍测试的 CI/CD 工作流	配置单元测试或集成测试（使用 /configure:tests）

上下文

• 包管理器：!find . -maxdepth 1 \( -name 'package.json' -o -name 'bun.lock' -o -name 'bun.lockb' \)
• Playwright 配置：!find . -maxdepth 1 -name 'playwright.config.*'
• 已安装 Playwright：!find . -maxdepth 1 -name 'package.json' -exec grep -l '@playwright/test' {} +
• 已安装 Axe-core：!find . -maxdepth 1 -name 'package.json' -exec grep -l '@axe-core/playwright' {} +
• 端到端测试目录：!find . -maxdepth 2 -type d \( -name 'e2e' -o -name 'tests' \)
• 视觉快照：!find . -maxdepth 4 -type d -name '__snapshots__'
• MCP 配置：!find . -maxdepth 1 -name '.mcp.json'
• CI 工作流：!find . -path '*/.github/workflows/*' -maxdepth 3 -name 'e2e*'

UX 测试技术栈：

• Playwright - 跨浏览器端到端测试（主要工具）
• axe-core - 自动化无障碍测试（符合 WCAG）
• Playwright screenshots - 视觉回归测试
• Playwright CLI - 通过 CLI 自动化浏览器操作（适用于可访问 shell 的 AI Agent，优先使用）
• Playwright MCP - 通过 MCP 自动化浏览器操作（适用于沙盒环境的备用方案）

参数

从命令参数中解析：

• --check-only：仅报告状态，不提供修复方案
• --fix：自动应用所有修复，不提示确认
• --a11y：重点配置无障碍测试
• --visual：重点配置视觉回归测试

执行

执行此 UX 测试配置检查：

步骤 1：获取最新工具版本

配置前确认最新版本：

1. @playwright/test：查看 playwright.dev 或 npm
2. @axe-core/playwright：查看 npm
3. @playwright/cli：查看 npm
4. playwright MCP：查看 npm

使用 WebSearch 或 WebFetch 确认当前版本。

步骤 2：检测现有 UX 测试基础设施

运行检测脚本，扫描项目中的 Playwright / axe-core 信号 （package.json 依赖项和配置 glob）、e2e 目录 / __snapshots__ / e2e 工作流， 以及 playwright MCP 服务条目：

bash "${CLAUDE_SKILL_DIR}/scripts/configure-ux-testing.sh" --home-dir "$HOME" --project-dir "$(pwd)"

解析输出中的 STATUS= 和 ISSUES: 块。KEY=VALUE 行 会报告 PLAYWRIGHT_CONFIG、PLAYWRIGHT_DEP、AXE_CORE_DEP、E2E_DIR、 VISUAL_SNAPSHOTS、E2E_WORKFLOW、PLAYWRIGHT_MCP，以及汇总项 PLAYWRIGHT_DETECTED / UX_SIGNALS_PRESENT。

步骤 3：生成合规性报告

打印格式化的合规性报告，展示 Playwright 核心、无障碍测试、视觉回归和 MCP 集成的状态。

如果设置了 --check-only，则在此处停止。

合规性报告格式请参阅 REFERENCE.md。

步骤 4：安装依赖项（如果设置了 --fix 或用户确认）

# Core Playwright
bun add --dev @playwright/test

# Accessibility testing
bun add --dev @axe-core/playwright

# Install browsers
bunx playwright install

第 5 步：创建 Playwright 配置

创建 playwright.config.ts，其中包含：

• 桌面浏览器项目（Chromium、Firefox、WebKit）
• 移动端视口项目（Pixel 5、iPhone 13）
• 专用的 a11y 测试项目（仅 Chromium）
• 自动启动本地开发服务的 WebServer
• 失败时的跟踪记录／截图／视频设置
• 用于 CI 的 JSON 和 JUnit 报告器

完整的 playwright.config.ts 模板请参见 REFERENCE.md。

第 6 步：创建无障碍测试辅助工具

创建 tests/e2e/helpers/a11y.ts，其中包含：

• expectNoA11yViolations(page, options) - 断言不存在 WCAG 违规
• getA11yReport(page, options) - 生成详细的 a11y 报告
• 可配置的 WCAG 级别（wcag2a、wcag2aa、wcag21aa、wcag22aa）
• 支持包含／排除规则
• 格式化的违规输出

完整的 a11y 辅助工具代码请参见 REFERENCE.md。

第 7 步：创建示例测试文件

创建示例测试：

1. tests/e2e/homepage.a11y.spec.ts - 首页无障碍测试（WCAG 2.1 AA 违规、交互后的检查、完整报告）
2. tests/e2e/visual.spec.ts - 视觉回归测试（整页截图、组件截图、响应式布局、深色模式）

完整的示例测试文件请参见 REFERENCE.md。

第 8 步：添加 npm 脚本

更新 package.json，添加测试脚本：

{
  "scripts": {
    "test:e2e": "playwright test",
    "test:e2e:headed": "playwright test --headed",
    "test:e2e:debug": "playwright test --debug",
    "test:e2e:ui": "playwright test --ui",
    "test:a11y": "playwright test --project=a11y",
    "test:visual": "playwright test visual.spec.ts",
    "test:visual:update": "playwright test visual.spec.ts --update-snapshots",
    "playwright:codegen": "playwright codegen http://localhost:3000",
    "playwright:report": "playwright show-report"
  }
}

第 9 步：配置浏览器自动化（可选）

根据 Agent 的运行环境，选择合适的浏览器自动化方案：

选项 A：Playwright CLI（有 Shell 访问权限时优先使用）

Playwright CLI（@playwright/cli）用于 AI Agent 浏览器自动化时，令牌效率比 MCP 高 4～10 倍（每项任务约 27K 对比 114K 令牌）。快照和截图会保存到磁盘，而不是注入上下文。

# Global install
npm install -g @playwright/cli@latest

# Or project-local
bun add --dev @playwright/cli

这使 Claude 能够通过 CLI 命令浏览页面、截取屏幕截图、填写表单、点击元素并捕获页面快照。命令参考请参见 playwright-cli 技能。

选项 B：Playwright MCP（适用于没有 Shell 访问权限的沙盒环境）

在没有 Shell 访问权限的环境（Claude Desktop、基于浏览器的 Agent）中运行时，使用 MCP：

{
  "mcpServers": {
    "playwright": {
      "command": "bunx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

第 10 步：创建 CI/CD 工作流

创建 .github/workflows/e2e.yml，并行运行以下任务：

• E2E 测试（所有浏览器）
• 无障碍测试（仅 Chromium）
• 上传报告和失败截图等构件

完整的 CI 工作流模板请参见 REFERENCE.md。

第 11 步：更新标准跟踪信息

更新 .project-standards.yaml：

components:
  ux_testing: "2025.1"
  ux_testing_framework: "playwright"
  ux_testing_a11y: true
  ux_testing_a11y_level: "wcag21aa"
  ux_testing_visual: true
  ux_testing_cli: true
  ux_testing_mcp: false

第 12 步：报告配置结果

打印配置内容、添加的脚本和 CI/CD 设置的摘要。说明后续步骤，包括启动开发服务器、运行测试、更新快照和打开交互式 UI。

结果报告格式请参见 REFERENCE.md。

Agent 优化

上下文	命令
快速合规性检查	/configure:ux-testing --check-only
自动修复所有问题	/configure:ux-testing --fix
仅关注无障碍	/configure:ux-testing --a11y
仅关注视觉回归	/configure:ux-testing --visual
精简运行 E2E 测试	bunx playwright test --reporter=line
仅运行 a11y 测试	bunx playwright test --project=a11y --reporter=dot

标志

标志	描述
--check-only	仅报告状态，不提供修复方案
--fix	无需提示，自动应用所有修复
--a11y	专注于无障碍测试配置
--visual	专注于视觉回归测试配置

错误处理

• 未找到包管理器：无法安装依赖项，提供手动操作步骤
• 未配置开发服务器：提醒手动配置 baseURL
• 未安装浏览器：提示运行 bunx playwright install
• 现有配置冲突：保留用户配置，并建议合并

另请参阅

• /configure:tests - 单元测试和集成测试配置
• /configure:all - 运行所有合规性检查
• 技能：playwright-testing、playwright-cli、accessibility-implementation
• Agent：用于实现 UX 设计的 ux-implementation
• Playwright 文档：https://playwright.dev
• axe-core 文档：https://www.deque.com/axe