qa-browser-automation

QA 浏览器自动化

Agent 使用 Chrome MCP 进行实时浏览器测试，并使用四种 Python 工具执行确定性健康评分、无障碍审计、视觉回归跟踪和报告生成。

---

先澄清

开始 QA 检查前，先确定以下输入。如果缺少某项或描述含糊，且会影响结果，请先询问；如果不会影响结果，则使用合理的默认值，并说明所用默认值。

• **目标 URL/应用 + 身份验证：**要测试什么，以及如何登录（这是整个检查的对象）。
• **测试级别：**Quick / Standard / Deep / Exhaustive（决定范围、断点和耗时）。
• **修复自主权：**自动修复 P3/P4 并提交，还是仅报告 / 修改任何代码前先询问（决定是否修改工作树）。
• **WCAG 目标级别：**A / AA / AAA（决定无障碍通过标准）。

只询问对本次请求最重要的两到三项输入，不要询问完整列表。如果用户希望立即得到结果，就直接生成结果，并在顶部说明假设。

快速开始

# Score QA findings (0-100 weighted across 10 categories)
python scripts/qa_health_scorer.py findings.json --threshold 85 --baseline .qa-baselines/latest.json --save-baseline --json

# Audit HTML for WCAG 2.1 violations
python scripts/accessibility_auditor.py page.html --level AA --json

# Track visual regressions
python scripts/visual_regression_tracker.py --init --baseline-dir ./baselines
python scripts/visual_regression_tracker.py --register ./baselines
python scripts/visual_regression_tracker.py --baseline ./baselines --current ./screenshots --threshold 5

# Generate full QA report
python scripts/test_report_generator.py session_data.json --format markdown -o report.md

工具概览

工具	输入	输出
qa_health_scorer.py	Findings JSON	0-100 分、A-F 等级、类别细分、趋势数据
accessibility_auditor.py	HTML 文件（或 stdin）	按级别列出的 WCAG 违规，并提供修复指导
visual_regression_tracker.py	基准截图目录 + 当前截图目录	每个页面的通过/失败状态、变更百分比
test_report_generator.py	会话数据 JSON	包含建议的 Markdown 或 JSON 报告

健康评分器、无障碍审计器和回归跟踪器使用 --json 输出机器可读结果；报告生成器使用 --format json。健康评分器和回归跟踪器在失败时返回退出代码 1（适用于 CI）。

---

工作流 1：完整应用 QA 检查（11 个阶段）

阶段 1-2：预检和身份验证。

• 确认 git status 状态干净。如果不干净，则中止。
• 创建会话目录：.qa-sessions/{timestamp}/
• 如有需要，通过 Chrome MCP 进行身份验证。

阶段 3-4：熟悉并探索。

• 使用 mcp__claude-in-chrome__read_page 构建站点地图/页面地图。
• 浏览每条路由。使用 read_console_messages 检查错误，使用 read_network_requests 检查 4xx/5xx。
• 使用有效数据、空提交和边界值测试所有表单。

阶段 5：状态测试。

• 验证加载状态（骨架屏，而非空白）、空状态（引导用户执行首个操作）、错误状态、成功状态和部分状态。
• **每次交互的四种影子路径：**正常路径、nil 输入、空输入、上游错误。

阶段 6：跨设备和安全性。

• 调整窗口大小至 320px、768px、1024px、1440px、1920px。
• 检查触控目标（最小 44x44px）和布局偏移。
• 验证安全标头（CSP、HSTS、X-Frame-Options）和 Cookie 标志。

阶段 7-8：记录并评分。

• 记录每项发现并附上截图证据。没有证据就不记录发现。
• 按严重程度（P0-P4）和类别（10 个类别）分类。
• 运行：python scripts/qa_health_scorer.py findings.json --baseline .qa-baselines/latest.json

阶段 9：分类并修复。

• P3/P4：自动修复，原子化提交，并进行验证。
• P0/P1/P2：询问，出示证据，提出修复方案，等待批准。
• 每次修复后：重新运行检查。如果失败：git revert。
• 修复数量达到 50 项时立即停止。

阶段 10-11：回归检查和报告。

• 重新访问已修复的页面。确认没有新错误。
• 将评分保存为下一个基准：python scripts/qa_health_scorer.py findings.json --save-baseline（写入 .qa-baselines/{date}.json 和 .qa-baselines/latest.json）
• 生成报告：python scripts/test_report_generator.py session.json -o report.md

**验证检查点：**健康评分 >= 85。P0 发现为零。WCAG AA >= 95%。

---

工作流 2：视觉回归测试

# Set up baseline
python scripts/visual_regression_tracker.py --init --baseline-dir ./baselines
# Capture and register screenshots
python scripts/visual_regression_tracker.py --register ./baselines
# After changes, compare
python scripts/visual_regression_tracker.py --baseline ./baselines --current ./screenshots --threshold 5 --json
# Accept intentional changes
python scripts/visual_regression_tracker.py --update-baseline --baseline ./baselines --current ./screenshots

超过阈值（默认 5%）的页面会被标记为回归。跟踪器会比较图像文件的 SHA-256 哈希值和原始字节，而不是解码后的像素，因此变化百分比只是一个粗略信号；即使截图经过重新编码但视觉上完全相同，也仍可能被判定为有变化。

---

工作流 3：无障碍审计

python scripts/accessibility_auditor.py page.html --level AA --json
curl -s https://example.com | python scripts/accessibility_auditor.py - --level AAA

各级别检查的内容：

• A（必须修复）： 替代文本、页面语言、页面标题、标题层级、重复 ID、表单标签、空链接文本、媒体字幕和自动播放、main 和 nav 地标、正数 tabindex
• AA（应该修复）： 检查被 outline:none 移除的焦点指示器，并标记带有内联颜色样式的元素以供人工检查对比度。不会测量对比度，因为该工具无法计算样式
• AAA（有则更好）： 检查“点击这里”等通用链接文本（2.4.9）。不测量增强对比度，也不检查阅读水平；请手动审核这些内容

每项违规都包含：WCAG 标准、严重程度、元素选择器和修复指导。

---

测试级别

级别	时长	范围
快速	30s	控制台错误、失效链接、基础无障碍检查、调整移动端尺寸
标准	2-5 min	+ 前 10 个路由、表单、对比度、Core Web Vitals
深度	10-20 min	+ 完整站点地图、状态测试、WCAG AA、性能、视觉回归、安全标头
穷尽	30+ min	+ 每个元素、WCAG AAA、所有页面的性能、5 个断点、身份验证边界情况、内存泄漏

---

健康度评分系统

10 个加权类别，评分 0-100：

类别	权重	衡量内容
功能	18%	表单、CRUD、导航流程
无障碍	13%	WCAG 合规性、键盘导航
控制台错误	12%	JS 错误、未处理的拒绝
UX 流程	12%	合乎逻辑的导航、清晰的反馈
性能	12%	Core Web Vitals 达到阈值
视觉一致性	10%	布局偏移、对齐、z-index
失效链接	8%	HTTP 4xx/5xx、失效锚点
内容质量	5%	拼写、占位文本、截断
安全标头	5%	CSP、HSTS、Cookie 标志
移动端响应式	5%	断点、触控目标、无水平滚动

按严重程度扣分： P0：-30，P1：-18，P2：-10，P3：-4，P4：-1。

等级： A（90-100）、B（80-89）、C（70-79）、D（60-69）、F（0-59）。

---

安全控制

• 要求工作树干净 -- 如果 git status 显示有修改，则中止。
• 每个会话最多修复 50 项 -- 达到上限后强制停止。
• 风险累加值 -- 组件（+5）、样式（+2）、配置（+8）、回滚（+15）。达到预算的 25% 时停止。
• WTF 启发式规则 -- 连续 3 次修复验证失败后，彻底停止。
• 原子提交 -- 一个修复对应一个提交：fix(qa): [P{severity}] {description}

---

故障排除

问题	原因	解决方案
评分器退出代码为 1，但没有错误	评分低于 --threshold（默认 70）	检查输出中的评分；提高阈值或修复问题
审计器报告 parse-error	HTML 格式错误	确认文件完整；检查 curl 是否返回了重定向
回归跟踪器显示所有页面变化 100%	基线清单为空	在比较前运行 --init，然后运行 --register
问题默认归为 P3/功能	缺少 severity 或 category 键	在每个问题字典中都包含这两个键
Chrome MCP 在 SPA 导航后返回过期内容	DOM 已更新，但未完整加载页面	等待过渡完成，再次调用 read_page

---

参考资料

指南	路径
浏览器测试方法论	references/browser_testing_methodology.md
WCAG 合规指南	references/wcag_compliance_guide.md
性能基准	references/performance_benchmarks.md

---

范围与限制

涵盖范围：

• 通过 Chrome MCP 开展实时 QA 检查：发现页面、检查控制台和网络错误、表单、UI 状态、断点和安全标头，并遵循上述测试层级和安全控制措施。
• 使用 qa_health_scorer.py 根据 findings JSON 计算加权健康评分：0-100 分、A-F 等级、十个类别、基线趋势，以及低于 --threshold 时返回退出代码。
• 使用 accessibility_auditor.py 对保存的 HTML 执行 WCAG 2.1 静态检查，支持 A、AA 或 AAA 级别。
• 使用 visual_regression_tracker.py 跟踪截图基线，并使用 test_report_generator.py 生成 Markdown 或 JSON 格式的会话报告。

不涵盖范围：

• 编写和维护自动化端到端测试套件（参见 engineering/playwright-pro/）。
• 完整的无障碍计划，包括屏幕阅读器和键盘测试（参见 engineering/a11y-audit/）。
• 详细的性能分析（参见 engineering/performance-profiler/）。
• 除标头和 Cookie 检查以外的安全测试（参见 engineering/security-audit/）。

重要注意事项：

• Python 工具不会打开浏览器。浏览器操作依赖 Chrome MCP 是否可用，而评分器和报告生成器只会处理由人工或 Agent 记录的发现。
• accessibility_auditor.py 会解析静态 HTML。它无法计算样式，因此会将颜色对比度标记为需人工审查，而非进行测量；除非保存的 HTML 中包含 JavaScript 渲染的内容，否则这些内容也会被遗漏。
• visual_regression_tracker.py 比较图像文件的哈希值和字节，而非像素。其变更百分比只是一个粗略指标；即使截图重新编码后内容相同，也可能被判定为已变更。
• 修复流程会编辑并提交代码。上述干净工作树检查、修复上限和审批规则可以限制此行为，但健康评分通过并不代表应用没有缺陷。

---

集成点

技能	集成方式
code-reviewer	在 PR 审查上下文中提供健康评分和发现
senior-frontend	视觉回归基线与组件库保持一致
senior-devops	健康评分通过退出代码控制 CI/CD
senior-secops	安全标头相关发现升级至安全审查
incident-commander	P0 级发现触发事件响应

---

最后更新： 2026 年 4 月 版本： 2.1.0