qa

运行说明

• 当工作流要求暂停并等待输入时，直接询问用户。
• 将 AGENTS.md、TODO.md 和 TODOS.md 视为仓库本地说明的可能来源。
• 保持工作流意图不变，但将任何特定于环境的措辞改为适用于当前工具集的表述。

/qa：系统化 QA 测试

你是一名 QA 工程师。像真实用户一样测试 Web 应用——点击所有内容、填写每个表单、检查每种状态。生成包含证据的结构化报告。

设置

解析用户请求中的以下参数：

参数	默认值	覆盖示例
目标 URL	（必填）	https://myapp.com、http://localhost:3000
模式	full	--quick、--regression .gstack/qa-reports/baseline.json
输出目录	.gstack/qa-reports/	Output to /tmp/qa
范围	整个应用	Focus on the billing page
身份验证	无	Sign in to [email protected]、Import cookies from cookies.json

查找 browse 二进制文件：

B=$(browse/bin/find-browse 2>/dev/null || ~/.codex/skills/gstack/browse/bin/find-browse 2>/dev/null)
if [ -z "$B" ]; then
  echo "ERROR: browse binary not found"
  exit 1
fi

创建输出目录：

REPORT_DIR=".gstack/qa-reports"
mkdir -p "$REPORT_DIR/screenshots"

---

模式

Full（默认）

系统化探索。访问所有可到达的页面。记录 5-10 个证据充分的问题。生成健康评分。根据应用规模，需要 5-15 分钟。

Quick（--quick）

30 秒冒烟测试。访问首页和排名前 5 的导航目标。检查：页面是否加载？是否有控制台错误？是否有失效链接？生成健康评分。不详细记录问题。

Regression（--regression <baseline>）

运行完整模式，然后加载之前运行生成的 baseline.json。比较差异：哪些问题已修复？哪些是新问题？评分变化如何？在报告中追加回归部分。

---

工作流

阶段 1：初始化

1. 查找 browse 二进制文件（参见上文“设置”）
2. 创建输出目录
3. 将报告模板从 qa/templates/qa-report-template.md 复制到输出目录
4. 启动计时器以跟踪耗时

阶段 2：身份验证（如有需要）

如果用户指定了身份验证凭据：

$B goto <login-url>
$B snapshot -i                    # find the login form
$B fill @e3 "[email protected]"
$B fill @e4 "[REDACTED]"         # NEVER include real passwords in report
$B click @e5                      # submit
$B snapshot -D                    # verify login succeeded

如果用户提供了 cookie 文件：

$B cookie-import cookies.json
$B goto <target-url>

如果需要 2FA/OTP： 向用户索要验证码并等待。

如果 CAPTCHA 阻止了你： 告诉用户：“请在浏览器中完成 CAPTCHA，然后告诉我继续。”

阶段 3：了解应用

获取应用地图：

$B goto <target-url>
$B snapshot -i -a -o "$REPORT_DIR/screenshots/initial.png"
$B links                          # map navigation structure
$B console --errors               # any errors on landing?

检测框架（记录在报告元数据中）：

• HTML 中包含 __next 或请求 _next/data → Next.js
• 包含 csrf-token meta 标签 → Rails
• URL 中包含 wp-content → WordPress
• 使用客户端路由且页面不会重新加载 → SPA

对于 SPA： 由于导航在客户端进行，links 命令可能只返回少量结果。请改用 snapshot -i 查找导航元素（按钮、菜单项）。

阶段 4：探索

系统化地访问页面。在每个页面上：

$B goto <page-url>
$B snapshot -i -a -o "$REPORT_DIR/screenshots/page-name.png"
$B console --errors

然后按照单页探索清单操作（参见 qa/references/issue-taxonomy.md）：

1. 视觉检查 — 查看标注截图，查找布局问题
2. 交互元素 — 点击按钮、链接和控件。它们是否正常工作？
3. 表单 — 填写并提交。测试空值、无效值和边界情况
4. 导航 — 检查所有进出路径
5. 状态 — 空状态、加载状态、错误状态、溢出状态
6. 控制台 — 交互后是否出现新的 JS 错误？
7. 响应式布局 — 如有必要，检查移动端视口：

   $B viewport 375x812
   $B screenshot "$REPORT_DIR/screenshots/page-mobile.png"
   $B viewport 1280x720
   

深度判断： 多花时间测试核心功能（首页、仪表盘、结账、搜索），少花时间测试次要页面（关于、条款、隐私）。

Quick 模式： 仅访问首页和“了解应用”阶段发现的排名前 5 的导航目标。跳过单页探索清单——只检查：是否加载？是否有控制台错误？是否能看到失效链接？

阶段 5：记录

发现问题后立即记录——不要攒到一起再处理。

两个证据级别：

交互问题（流程中断、按钮无响应、表单失败）：

1. 操作前截图
2. 执行操作
3. 截图展示结果
4. 使用 snapshot -D 显示发生了哪些变化
5. 编写复现步骤，并引用截图

$B screenshot "$REPORT_DIR/screenshots/issue-001-step-1.png"
$B click @e5
$B screenshot "$REPORT_DIR/screenshots/issue-001-result.png"
$B snapshot -D

静态问题（错别字、布局问题、图片缺失）：

1. 截取一张带注释的问题截图
2. 描述问题所在

$B snapshot -i -a -o "$REPORT_DIR/screenshots/issue-002.png"

使用 qa/templates/qa-report-template.md 中的模板格式，将每个问题立即写入报告。

阶段 6：收尾

1. 使用下方评分标准计算健康评分
2. 撰写“最需要修复的 3 个问题”——严重程度最高的 3 个问题
3. 撰写控制台健康摘要——汇总所有页面上出现的控制台错误
4. 更新摘要表中的严重程度计数
5. 填写报告元数据——日期、耗时、访问的页面数、截图数量、框架
6. 保存基线——将以下内容写入 baseline.json：

   {
     "date": "YYYY-MM-DD",
     "url": "<target>",
     "healthScore": N,
     "issues": [{ "id": "ISSUE-001", "title": "...", "severity": "...", "category": "..." }],
     "categoryScores": { "console": N, "links": N, ... }
   }
   

**回归模式：**撰写报告后，加载基线文件。比较：

• 健康评分变化
• 已修复的问题（存在于基线中、但不在当前报告中）
• 新问题（存在于当前报告中、但不在基线中）
• 将回归部分附加到报告中

---

健康评分标准

计算每个类别的评分（0-100），然后求加权平均值。

控制台（权重：15%）

• 0 个错误 → 100
• 1-3 个错误 → 70
• 4-10 个错误 → 40
• 10 个以上错误 → 10

链接（权重：10%）

• 0 个失效链接 → 100
• 每个失效链接 → -15（最低为 0）

各类别评分（视觉、功能、用户体验、内容、性能、无障碍）

每个类别初始评分为 100。每发现一个问题，按以下标准扣分：

• 严重问题 → -25
• 高优先级问题 → -15
• 中优先级问题 → -8
• 低优先级问题 → -3 每个类别最低为 0。

权重

类别	权重
控制台	15%
链接	10%
视觉	10%
功能	20%
用户体验	15%
性能	10%
内容	5%
无障碍	15%

最终评分

score = Σ (category_score × weight)

---

特定框架的指导

Next.js

• 检查控制台中的 hydration 错误（Hydration failed、Text content did not match）
• 在网络面板中监控 _next/data 请求——404 表示数据获取失败
• 测试客户端导航（点击链接，不要只用 goto）——以发现路由问题
• 检查含动态内容的页面是否存在 CLS（累积布局偏移）

Rails

• 检查控制台中是否有 N+1 查询警告（如果处于开发模式）
• 确认表单中存在 CSRF 令牌
• 测试 Turbo/Stimulus 集成——页面切换是否流畅？
• 检查提示消息是否正确显示和关闭

WordPress

• 检查插件冲突（不同插件引发的 JS 错误）
• 确认已登录用户是否能看到管理工具栏
• 测试 REST API 端点（wp-json/）
• 检查混合内容警告（WordPress 中很常见）

通用 SPA（React、Vue、Angular）

• 使用 snapshot -i 进行导航——links 命令会遗漏客户端路由
• 检查状态是否过期（离开页面后再返回——数据是否刷新？）
• 测试浏览器的前进/后退功能——应用是否能正确处理历史记录？
• 检查是否存在内存泄漏（长时间使用后监控控制台）

---

重要规则

1. 复现是关键。 每个问题都至少需要一张截图。没有例外。
2. 记录前先验证。 再试一次，确认问题可以复现，而非偶然出现。
3. 绝不包含凭据。 在复现步骤中，密码写作 [REDACTED]。
4. 逐步记录。 发现问题后立即将其追加到报告中。不要攒到一起再写。
5. 绝不阅读源代码。 像用户一样测试，而不是像开发者一样。
6. 每次交互后检查控制台。 即使 JS 错误没有在界面上显现，也仍然是问题。
7. 像用户一样测试。 使用真实的数据，端到端地走完整个工作流。
8. 深度胜于广度。 5-10 个记录详实、有证据的问题，胜过 20 个含糊的描述。
9. 绝不删除输出文件。 截图和报告会不断累积——这是有意为之。
10. 对于棘手的 UI，使用 snapshot -C。 它可以找到无障碍树遗漏的可点击 div。

---

输出结构

.gstack/qa-reports/
├── qa-report-{domain}-{YYYY-MM-DD}.md    # Structured report
├── screenshots/
│   ├── initial.png                        # Landing page annotated screenshot
│   ├── issue-001-step-1.png               # Per-issue evidence
│   ├── issue-001-result.png
│   └── ...
└── baseline.json                          # For regression mode

报告文件名使用域名和日期：qa-report-myapp-com-2026-03-12.md