让 Codex 用真实浏览器证明页面可用

截图里一切正常，用户却按不到按钮

桌面截图对齐，手机截图也没有横向滚动。真正用手点提交时，按钮被透明导航层挡住，页面一点反应都没有。

视觉正确和任务可用，是两种证据。

浏览器验收的最小单位不是截图，而是一条用户动作链。 这节课会把打开、输入、点击、状态变化和结果回读写进场景矩阵，让每张图都知道自己在证明什么。

浏览器验收回答的是“用户能否完成”

测试和构建能证明代码满足某些约束，却不能自动证明菜单可点、抽屉没有溢出、错误态能恢复或移动端按钮没有被遮挡。浏览器验收要把用户故事转换成：

前置状态 → 用户动作 → 可见结果 → 可测事实 → 留存证据

本节使用下载的 acceptance-brief.md。你也可以把路径替换为自己的真实页面，但不要在练习中混入多个独立流程。

第一步：从风险而不是设备清单开始

阅读 brief，先标出风险：

• 固定桌面侧栏可能随正文滚走；
• 移动端抽屉可能仍占据页面宽度；
• 宽表格可能让整个页面横向溢出；
• 请求错误可能只显示空白；
• 重试可能重复提交或无法恢复。

然后选择最小矩阵：

视口	关键风险	必做动作
1280×720	固定侧栏与正文滚动	滚动到底，检查侧栏位置和内部滚动
390×844	抽屉、遮挡、横向溢出	打开/关闭导航，滚动表格，检查页面宽度

设备不是目的。每个视口都必须对应一个会改变验收结论的风险。

第二步：写成动作与事实

不合格：

检查移动端响应式。

合格：

前置：390×844，移动导航关闭。
动作：记录 documentElement.clientWidth 与 scrollWidth。
期望：两者都为 390；导航位于视口外且不占布局宽度。
动作：点击“打开导航”。
期望：抽屉左边缘为 0、宽 260px、可关闭；正文不横移。

把下载的矩阵中每一行补齐“前置、动作、期望、证据类型”。

第三步：让 Codex 启动真实环境

先读取项目说明并使用已有开发命令启动页面。
不要替换框架或创建新的演示页面。

按 acceptance-matrix.md 逐行验收：
- 每一步执行真实用户动作；
- 同时记录可见结果和 DOM 测量；
- 失败时保留实际值，不要为了完成报告修改期望；
- 截图文件名包含页面、视口和状态。

本轮只验收，不修改代码。

先只读验收能避免 agent 一看到差异就修改，导致你失去修复前证据。

第四步：检查桌面滚动行为

在 1280×720：

1. 记录侧栏矩形位置；
2. 滚动正文至少 1500px；
3. 再记录侧栏位置；
4. 如果侧栏内容超过视口，确认它内部可滚动；
5. 检查正文没有被固定区域覆盖。

报告应包含实际数值，例如滚动前后侧栏 top 都为 0、height 为 720，而不是“侧栏保持固定”。

第五步：检查移动抽屉与宽内容

在 390×844：

1. 导航关闭时记录 page clientWidth 与 scrollWidth；
2. 打开抽屉，测量 left、width、height；
3. 关闭抽屉，确认焦点或操作返回页面；
4. 找到宽表格，横向滚动表格容器；
5. 确认页面本身仍不横向滚动。

若直接给 body 设置 overflow-x: hidden，页面数值可能“正常”，但表格内容也可能被裁掉。验收必须同时检查“页面不溢出”和“宽内容仍可访问”。

第六步：主动触发四类状态

至少覆盖：

• 正常：真实数据或成功响应；
• 加载：网络等待期间有可理解反馈；
• 空：无内容时不是坏掉的空白；
• 错误：出现错误信息与恢复动作。

如果项目没有现成的错误注入方式，不要伪造“已验证”。把它列为验收阻塞，说明需要开发提供 mock、测试路由或网络拦截方法。

第七步：截图必须带台账

单独一张截图不能证明操作路径。每张记录：

文件名：
URL：
视口：
前置状态：
刚执行的动作：
截图中应注意：
对应验收项：

截图适合证明视觉状态；精确宽度、网络错误和键盘行为还需要 DOM、事件或日志证据。

第八步：从失败报告转成最小修复 brief

如果移动表格导致页面 scrollWidth=642，写：

观察到的差异
- 390px 视口下页面 scrollWidth 为 642px；
- 溢出从结果表格开始。

必须保留
- 表格全部列仍可通过容器内横向滚动访问；
- 桌面表格布局不变。

修复后重验
- 页面 clientWidth = scrollWidth = 390；
- 表格容器 scrollWidth 大于 clientWidth 且可滚动；
- 导航开关和桌面固定侧栏继续通过。

从最重要的那个按钮开始

为你的页面写三条场景：正常完成、缺失输入、移动端完成。每条都记录动作、可见事实和最终状态。

截图适合留下现场，不能替代点击。只有用户从起点走到结果，页面才算通过验收。

参考答案与完成检查

对照参考报告，确认它包含实际数值、失败状态和未验证项，而不是只有截图。

键盘验收不能由截图代替

使用 Tab 进入主要操作，确认焦点顺序与页面阅读顺序一致；打开移动抽屉后，焦点不应落到被遮挡的正文控件；关闭后应回到合理入口。记录实际焦点元素和动作。截图可以证明焦点样式在某一刻可见，却不能证明完整顺序、Escape 行为或操作后焦点恢复。

主流程还应在不使用鼠标的情况下完成一次，避免把“能看见”误当成“能操作”。

• 每个视口都对应明确风险
• 每条验收包含前置、动作、期望和证据
• 桌面侧栏经过真实滚动测试
• 移动抽屉与宽内容分别测量
• 正常、加载、空和错误状态均有结论
• 截图与台账一一对应