---
name: cents-playwright-regression
description: 运行和维护 Cents 的中文 Playwright 回归测试，按功能分类执行测试，并将每轮失败案例、截图和 trace 归档到被 gitignore 的测试报告目录。
---

# Cents Playwright 回归测试

## 适用场景

用户要求执行 Cents 的端到端回归测试、增加第一批功能案例、检查离线/同步/多币种/报销流程，或分析上一轮测试失败时使用本 skill。

## 目录约定

- 测试目录：`tests/e2e/`
- 功能目录和测试文件使用中文，并以 `01-`、`02-` 编号。
- 每轮报告目录：`test-reports/YYYYMMDD-HHmmss/`
- 总结：`SUMMARY.md`
- 失败归档：`failures/`，保持测试案例原本目录结构。
- 失败目录中保存 `失败说明.md`、截图和 Playwright trace。
- 测试报告、trace、截图不得提交 Git。

## 执行流程

1. 阅读 `docs/测试策略.md` 以及涉及功能的设计文档。
2. 检查工作区状态，不覆盖用户已有改动。
3. 默认执行手机端和桌面端两个项目：

   ```bash
   TEST_RUN_ID="$(date +%Y%m%d-%H%M%S)" npm run test:e2e
   ```

4. 失败时不要修改业务实现代码。先阅读测试输出、`失败说明.md`、截图和 trace。
5. 如需交互检查，使用：

   ```bash
   npx playwright show-trace test-reports/<轮次>/failures/<案例>/trace.zip
   ```

6. 在 `SUMMARY.md` 中记录通过数、失败数、环境、失败案例和判断；失败原因只描述证据，不擅自推断为业务 bug。

## 测试原则

- 测试真实用户路径和可观察行为，不测试 Vue 内部状态或实现函数。
- 主要使用角色、可访问名称、表单标签和 URL 定位；只有轮盘、同步图标、图表等难以稳定定位的元素才使用 `data-testid`。
- 不使用固定长等待。使用 `expect`、网络响应、可见状态或 URL 变化等待。
- 每个测试使用独立 BrowserContext 和独立测试数据。
- API 和汇率服务可以使用 Playwright route mock；不得连接生产数据库或修改生产数据。
- 离线案例必须分别覆盖真正断网、API 502/失败和请求超时。
- 业务代码失败时只记录失败，不为了让测试通过而放宽断言或修改实现。

## 第一批功能范围

- `01-账号`：登录、错误密码、刷新保会话、退出。
- `02-账本`：个人/共享账本显示、新增账本、默认币种。
- `03-快速记账`：金额、备注、个人账本自动关联、多账本、外币。
- `04-流水`：列表、详情、编辑、删除确认。
- `05-离线`：离线打开、离线记账、待同步标记、恢复同步。
- `06-多币种`：异步换算、失败降级、显示模式切换。
- `07-报销`：部分报销、超额拒绝、统计排除报销到账。

## 失败判断

- 断言失败：记录为产品行为失败。
- 启动失败、浏览器缺失、端口占用：记录为测试环境失败。
- API mock 未覆盖：记录为测试夹具缺口，不修改业务代码。
- 只有在测试断言与设计文档不一致时，才记录为测试设计问题，待确认后修改测试。