acceptance-ui

验收 — UI

像真实用户一样在真实浏览器中操作应用：点击、输入、提交、重新加载，并断言屏幕上实际显示的内容。组件测试会模拟网络并验证组件自身的逻辑；这项测试则验证连接起来的整个栈——渲染、请求、响应、重新渲染、持久化。

由 acceptance-check 调用，并传入验收清单中的一部分条目；也可以直接针对前端变更运行。按清单顺序逐项执行。

1. 启动应用——并记录启动方式

阅读 docs/agents/project.md 中的 本地运行（开发）。使用记录的命令启动前端（以及它调用的任何后端）；如果没有记录，就自行查明启动方式并启动应用，在浏览器中确认应用可以加载，然后将命令写入 project.md 的 ## Run locally (dev) 部分。完成条件：应用可以加载，且命令已记录。

前置条件——身份验证、数据、环境。 如果流程需要已登录的会话、已填充数据的帐户或固定数据，或环境配置（环境变量、测试数据库），请查明仓库如何提供这些条件，并记录在 project.md 中——保存可复用的已登录状态（例如 storageState），而不是在每个测试用例中手动登录。测试若卡在登录页面或空白屏幕上，测到的是测试框架，而不是功能。

2. 确保具备端到端测试框架

如果仓库已采用其他端到端测试框架（Cypress、WebdriverIO、Nightwatch、原生移动端驱动），就使用该框架编写流程。如果尚无现成的端到端测试框架，默认使用 Playwright/Chromium。

检查是否已有 Playwright 测试框架：是否已安装 @playwright/test，且是否存在带有 Chromium 项目的 playwright.config.*。如果有，就使用它。如果没有，就进行设置：安装 @playwright/test，添加包含 chromium 项目和开发服务器 baseURL 的配置，指定测试目录，并在 project.md 中记录运行命令 （… playwright test --project=chromium）。完成条件：Playwright 命令可以针对 Chromium 运行，即使没有任何测试用例也可以，并且命令已记录。

3. 将每项检查流程转化为测试用例

针对清单中的每个 UI 项，编写一个 Playwright 测试用例，让它像用户一样操作：通过角色或标签定位元素（getByRole、getByLabel），输入并点击，然后断言可见结果——屏幕上的文字、已清空的输入框、列表顺序或显示的错误消息。如果验收标准要求“持久化”，就调用 page.reload() 并断言状态仍然存在。按照 project.md 中的约定，为每个测试用例添加需求 ID 标签（例如 test('…', { tag: '@CODE-N.M' }, …)）。

4. 在 Chromium 上运行并排查故障

在 Chromium 上以无头模式运行测试用例。任何失败都不能置之不理——应根据可观察到的测试结果进行归类。重新运行失败的测试用例：

• 在面向用户的断言中稳定失败——文字错误、状态错误，或应当渲染的元素缺失——属于产品缺陷。 必须使用子技能：debug；失败的测试用例就是能触发失败的测试闭环。 修复根本原因，并保留该测试用例作为回归测试。
• 非确定性故障（重新运行后通过）或测试框架故障——定位器不再匹配、缺少等待或发生竞态、缺少种子状态——属于测试用例缺陷，而非产品缺陷。让测试具备确定性（使用角色/标签定位器、等待断言、真实固定数据），然后重新运行。

只有在真实断言中稳定失败，才交由 debug。 完成条件：在全新的 Chromium 运行中，所有 UI 流程均通过。

5. 提交测试用例

测试用例是持久的产物——应提交并添加标签，以便纳入验证套件并由 finish-branch 重新运行。在 project.md 中记录任何新增的运行命令，并在清单中注明结果。完成条件：测试用例已提交、已添加标签且全部通过。