---
name: regression-test
description: >-
  E2E 回归测试 / 回归用例登记与执行。触发场景包括但不限于：
  「回归测试」「跑回归」「回归」「跑一下回归」「E2E 测试」「端到端测试」「E2E 回归」「上线前回归」「全量回归」「跑全量回归」「回归用例」「新增回归用例」「登记回归用例」「写回归测试」「回归报告」「测试报告」。
  任何要求执行、登记、编写回归测试或用例的场景都应触发。
  覆盖：用例登记双文件同步、Playwright 配置、截图 base64 内嵌、可视化报告质量、失败排查顺序、等待策略等完整规范。
---

# E2E 回归测试

⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `regression-test`，按 E2E 回归测试规范执行...」然后严格按照以下步骤执行，不得跳过。**

## ⚠️ 回归测试铁律

### 一、登记用例：双文件同步，缺一不可
- ⚠️ **新增一条回归用例，必须同时改两处**，只改一个会导致测试中心看不到新用例：
  - **Runner 脚本**（如 `superpowers-regression-runner.js`）：`TEST_CASES` 登记用例（id / name / command / cwd）+ `getVisualEvidenceDetails` 补验收详情。
  - **报告页面**（如 `上线前回归测试.html`）：`EMBEDDED_TEST_DATA` 数据 + scope 下拉选项 + test ID 常量 + `FILE_TO_TEST_MAP` 映射。

### 二、Playwright 配置
- ⚠️ **截图必须用 `{ mode: 'on', fullPage: true }`**，禁止用默认的 `'only-on-failure'`。后者意味着测试全过时一张图都没有，报告里全是空白的。
- ⚠️ **必须从正确的子目录执行测试**，禁止从项目根目录直接跑。根目录跑会导致配置文件中的相对路径（如 `.env`）解析错误，拿到错误的端口号。

### 三、截图证据必须 base64 内嵌
- ⚠️ **报告 HTML 里的截图必须以 `data:image/png;base64` 内嵌**，禁止用文件路径 / 相对链接引用外部图片。报告会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，报告里全是裂图，等于没有证据。
- ⚠️ **验证方法（返回值必须 > 0）**：`grep -c "data:image/png;base64" report.html`。返回 0 说明截图没内嵌成功，不算完成。

### 四、「完成」的定义：终端绿色 ≠ 做完
- ⚠️ **终端看到「全部通过」不等于工作完成**。真正的完成标志是三件事，缺一不可：① 确认测试中心在线（`/api/health`）；② 通过 API 触发可视化验收（`/api/run-visual`）；③ 确认报告里有内嵌截图（第三节的 grep > 0）。禁止看到终端绿色就告诉用户「做完了」——用户要的是能打开看的报告，不是终端日志。

### 五、失败排查顺序：先查基础设施
- ⚠️ **测试突然全部失败时，先检查外部依赖（数据库 / SSH 隧道、端口是否被抢）是否断开**，再改测试代码。禁止反复改测试代码去「绕过」基础设施问题。

### 六、等待策略：等元素，别等时间
- ⚠️ **页面 Loading 状态必须用元素可见性等待，禁止硬编码 `waitForTimeout`**。SPA 页面的正确等待顺序：先等关键元素出现（确认框架已挂载）→ 再等 Loading 状态消失（确认数据已返回）→ 最后才操作目标元素。顺序错了会出现「Loading 还没消失就点按钮 → 找不到 → 超时」。

### 七、可视化报告质量：新用例要达到 blog 用例水准
- ⚠️ **用例命名格式固定为「模块前缀-序号：中文场景描述」**（如「博客首页表单编辑后 iframe 刷新」），必须写清楚具体动作和期望结果，禁止写「测试一下」「验证功能」这类空话。这句命名会原样显示为报告里用例卡片的标题，是读者第一眼看到「这条用例在干嘛」的地方。
- ⚠️ **每次截图必须统一封装成一个截图函数，除了保存图片文件，还要输出一段结构化文本**，包含三部分：这张截图的文件名、专属说明文字、专属验证点清单。回归系统正是靠这条结构化文本才能把说明画在每张截图下面；漏了这一步，报告里那张图下面就是空的，或退化成一句放之四海皆可的套话——这正是其他用例报告不如 blog 好看的根本原因。
  - 说明文字固定格式「场景名：做了什么动作，出现了什么结果」（如「编辑弹窗：点击 Edit 后弹窗正确打开，显示 Blog 首页表单字段」）。
  - 验证点控制在 2-4 条，每条必须对应一个人眼可直接观察的界面状态或数据结果（如「编辑弹窗正常打开」「表单字段可编辑」），禁止写「功能正常」这种无法验证的话。
  - ⚠️ **说明文字和验证点必须一图一句、逐张不同，禁止用整条用例通用的一句套话覆盖所有截图。**
- ⚠️ **接入回归测试注册表时，必须补一条兜底业务说明**，只在某张截图漏加专属说明时才会被使用，主力仍是逐张配的专属说明。兜底说明包含三个字段：
  1. 关联的具体页面（写清楚是管理端还是用户端的哪一个页面，禁止写「相关页面」这种模糊说法）
  2. 一句话说明验证的具体业务规则（不是「测试了这个功能」，要说清是哪条具体规则或哪种数据结果）
  3. 三到五条检查点，同样要求每条对应一个可观察的界面状态或数据结果