---
name: web-gui-tester
description: 纯 GUI 黑盒网页验收方法论——以真实用户视角在真实浏览器上点击/输入/滚动，用只读结构读取与截图双通道取证，产出带绝对路径证据的验收报告。含四阶段流程（场景判定与计划、环境准备、动作-观测循环、结论输出）、P0-P3 测试点优先级、瞬时态同轮前后截图、控制台错误的采集与降级、报告体例。Use when 需要验证网页/前端功能是否正常、复现前端 bug、检查交互反馈与布局样式、或只给一个 URL 让你「测一下」。
when_to_use: 用户要求测网页、验前端功能、复现页面 bug、检查交互反馈/布局/样式，或给出一个 URL 要求测试。前置：会话内具备交互式浏览器载体（见 control-browser skill 的载体判定）。
audience: nebflow-project
language: zh
status: active
last_verified: 2026-09-18
---

# Web GUI Tester — 纯 GUI 黑盒验收方法论

本 skill 只定义**测试方法**：怎么选测试点、怎么取证、怎么下结论。
**载体与交互纪律归 `control-browser` skill**（怎么起浏览器、怎么定位、失败怎么办）；
两者冲突时，载体自身的规则优先。

## 一、五条核心原则

1. **纯 GUI 黑盒**：只与页面上**可见且可操作**的元素交互，模拟真实用户行为。
   验证时允许截图与**只读**结构读取；**严禁**注入 JavaScript 去改页面状态、触发交互或绕过前端逻辑。
2. **忠实于页面实际行为**：结论必须来自页面实际行为，不许猜、不许推测。
   正常 GUI 操作走不通 ⇒ **停下并如实报告**，不要换别的手段把流程推过去。
3. **测试与修复分离**：测试期间不改被测代码。某个 bug 挡住路径 ⇒ 记录问题、跳过该路径、
   继续测不受影响的其他点。只有测试明确宣告结束后、且用户明确要求改代码，才开始修。
4. **结构与视觉交叉验证**（双通道铁律）：每个观测点都要有**只读结构读取**（DOM 状态/可访问树）
   与**已检视的截图**；两者必须互相印证、不可相互替代。
   **没有至少一张「已看过」的截图作为证据的测试点 = 不完整** —— 不得据此下 PASS/FAIL。
   **绝不裸看图下结论**：图与结构读数矛盾 ⇒ 判 FAIL 并**双证据一起上交**。
5. **遵守载体的使用规则**：用会话实际提供的交互式浏览器载体跑测试，先按 `control-browser`
   完成载体的开工前自检；本 skill 与其规则冲突时以载体的规则为准。

## 二、阶段一：场景判定与测试计划

按用户给的信息完整度分档：

**信息完整（给了明确步骤与预期）** ⇒ 跳过规划，直接进入后续阶段。

**信息部分（给了功能描述 / bug 描述 / 需求文档）** ⇒ 轻量规划：
1. 明确测试目标：要验证什么功能、或要复现什么 bug。
2. 定验收判据：什么算通过。
3. 直接执行，不请求确认。

**信息不足（只给一个 URL 或「测一下」）** ⇒ 完整规划：
1. **探页面**：打开页面并截图建立整体印象，判断页面类型（表单页 / 列表页 / 详情页 / 仪表盘）。
2. **识别功能**：列出页面核心交互元素与功能区。
3. **出测试计划**，按优先级组织：
   - **P0 主流程**：核心功能的正常路径（提交表单、完成搜索、切换标签）。
   - **P1 交互反馈**：动作后的反馈是否正确 —— 加载态、成功/失败提示、禁用态、跳转。
   - **P2 输入边界**：空输入、超长输入、特殊字符、重复提交。
   - **P3 布局与样式**：元素重叠、文本溢出、对齐一致性、视觉质量。
4. **先亮计划再开跑**：把计划给用户看，然后**不等确认**直接从 P0 开始；用户可随时打断或调整。
   **例外**：页面需要登录凭据、或测试会写入真实数据（下单、支付、删除）⇒ **停下先问用户**。

## 三、阶段二：测试环境准备（需要时）

正式测试开始前，可以用任何必要手段准备环境；此阶段不受黑盒限制。

**允许**：起/重启开发服务器与依赖服务；改配置文件、准备测试文件；初始化测试数据、建测试账号；
按载体支持的方式预置登录态或初始状态；做任何让被测功能**可达**的准备工作。

**约束**：
1. **准备与测试明确分界**：准备完成后显式宣告「环境准备完成，正式测试开始」，
   此后黑盒约束立即生效，不再做任何有副作用的注入。
2. **准备不得替代被测行为**：准备只能让功能**可达**，不得预先触发或完成被测功能
   （例：测下单流程时，不要在准备阶段直接往库里插一笔订单）。
3. **不得在测试中退回准备阶段绕开失败**：正式测试中发现环境问题 ⇒ 先宣告该测试点作废、
   回到本阶段重新准备、再从头重跑受影响测试点，并在最终结果里**如实报告**。
4. **记录全部准备动作**：最终报告里说明所有环境准备操作，让用户能区分「预置状态」与「测试本身产生的状态」。
5. **隔离**：被测实例用自己的端口、自己的数据目录；**宿主的 `:8080` 网关监听者永不触碰**；
   自起进程收尾自清并给清理后现读。

## 四、阶段三：执行 —— 动作 → 观测 → 动作

**可用手段**：载体提供的导航、定位、交互（点击/输入/滚动/按键）与观测（结构读取、截图）能力。
除非必要**不要读被测项目源码** —— 避免用代码分析替代真实测试。

### 动作：模拟真实用户行为

- 定位依据**只能来自对页面的实际观测**（DOM/可访问树快照、截图、或载体提供的等价事实）。
  **绝不猜**选择器、label 文案或 URL 形态。
- 多页/多标签环境里，**每批操作前先列出现有页并确认目标**，不凭记忆或位置假定目标页。
- **禁止**：
  - 任何有副作用的 JS 注入（赋值、派发事件、代码触发点击、改 DOM 或存储、发请求）——只允许无副作用读取。
  - 靠构造/改写 URL 绕过页面交互。
  - 用 Tab 键、快捷键、强制点击等非常规手段绕过失败的交互。
  - 用刷新、前进后退、改窗口大小**逃出**当前失败态。（一个测试点结束后，可以回到入口页重置状态再开下一个点。）
- **定位失败时**：不要原样重试。先重新观测（重取快照，必要时加截图）确认实际状态，
  再判断这是页面 bug（元素确实不存在）、还是定位问题（从新事实重建定位器）。
- **页面加载失败时**：超时/白屏/报错 ⇒ 截图记录当前状态、报为问题、跳过依赖该页的后续测试点。
- **载体不支持某操作时**（如文件上传、特定手势）：该点记为「本载体不支持」并跳过。
  **永不伪造成功**，也永不靠注入绕过。
- **响应式/多尺寸测试**：仅当测试点明确要求时才调整视口尺寸，测完恢复；
  **不得**用它逃出失败态。

### 观测：结构与视觉交叉验证

每一个**新的页面状态**（初始加载、以及每次交互之后）都要同时做结构验证与视觉验证，二者都不可省。
（本 skill 的性质就是视觉页面测试；若载体默认限制截图频率，按「用户要求做视觉测试」这一分支进行。）

**结构验证（只读）**：优先用载体提供的结构化读取能力（DOM/可访问树快照、元素文本与属性、
元素状态查询）。只读脚本求值（如读元素几何判断遮挡）是**最后手段**；
被载体或引擎拒绝时**不要换措辞重试**，改用结构化读取或基于截图判断。

**视觉验证**：
- 用载体规定的方式**获取并查看**截图：工具直接返回的图算「已查看」；
  **落盘到文件的截图必须用会话的文件/图片读取工具读一遍**，视觉验证才算完成。**拍了不看 ≠ 观测**。
- 载体落盘截图后，把返回的**绝对路径**当作源证据；不要假定浏览器 API 能存到任意调用方给定的路径。
- **同时保存证据**：用户没指定目录时，在工作目录建一个专用目录（如 `gui-test-screenshots/`），
  用**含测试点编号**的命名（如 `t1_before.png`）复制/另存。
  **载体只返回图片而未暴露路径时，不要编造路径** —— 以已查看的图作证据，并如实说明「未暴露持久路径」。
- 布局与遮挡可借助 DOM 几何辅助判断，但渲染质量、视觉审美**只能从截图判断**；
  任一情况下都必须有截图最终确认视觉结果 —— **结构验证绝不能替代截图**。

**观测时机** —— 以下每种情况都要做两类验证：
每个测试点开始时（记录初始状态）；每次交互后（点击、输入、导航、键盘、鼠标）；
每次页面状态变化后（导航、弹窗、通知、列表刷新、回显、按钮启用禁用）；
每个测试点结束时（记录最终状态）；页面含画布/SVG/图表/图片/视频等无法从 DOM 文本读全的内容时；
发现问题时（保存证据、为最终报告积累素材）。

**观测维度**：

| 维度 | 关注点 |
|---|---|
| 元素存在 | 关键 UI 元素是否存在且可见 |
| 内容正确 | 文本、数字等内容是否符合预期 |
| 状态变化 | 动作后 URL、元素出现/消失、文案更新是否符合预期 |
| 布局与遮挡 | 意外重叠、遮挡、截断、错位；区分「合理的浮层/吸顶导航」与真实渲染缺陷 |
| 渲染与设计 | 长文本溢出、异常换行、设计一致性 |
| 视觉质量 | 对比度、配色、字体、间距、对齐 |

### 瞬时态的截图要求

Toast、tooltip、加载指示、动画等短命状态可能在截图前消失。要抓到它们，**在同一个脚本/同一次调用内连续**完成：

1. 先拍一张「前」截图，记录动作前状态。
2. 执行 GUI 动作。
3. 等目标状态出现 —— **优先等具体元素或状态条件**，只在目标无法描述（纯视觉动画）时才用固定延时兜底。
4. 拍一张「后」截图，抓瞬时反馈。

然后按上文「视觉验证」要求**把两张都看过**。普通静态页面与稳定内容不需要这种同轮前后对照，
一张常规截图就够；但**截图仍必须拍、图内容仍必须检视**。

### 采集页面错误证据

载体若支持**只读**的控制台监听或日志读取 ⇒ 测试开始时即注册（只读，不违反黑盒原则），
全程收集 error 级日志与未捕获异常，最终报告里**单独列出**并标注各自发生的操作步骤。
本平台的交互载体（Playwright）原生支持 `console` / `pageerror` 监听 ⇒ **默认可采集，用它**。
载体确无此能力时，**不要**靠注入脚本绕过去，改用**页面上可见的错误表现**作证据
（错误文案、白屏/空区、失败资源占位、布局崩坏），截图并标注对应步骤，
并在报告里**如实说明「控制台信息未能采集」**。

## 五、阶段四：输出测试结论

测试结束后，基于每一条记录在案的观测汇总：

- 哪些测试点**通过**。
- 哪些测试点**失败** —— 含复现步骤与截图。
- 哪些测试点**因被阻塞而未能执行**。
- 测试中采集到的控制台错误，或观测到的页面错误表现。

**每个测试点（无论通过还是失败）都必须引用其对应的「已查看截图」**；
载体暴露了持久路径时给**绝对路径**（或其 `file://` URI），否则用返回的图片作证据并说明未暴露路径。

### 输出格式

- 用户指定了报告格式（落某个文件、特定格式、特定语言）⇒ **严格照办**。
- 未指定 ⇒ 默认输出图文交错的 Markdown 报告，用标准图片语法引用图片
  （如 `![登录页截图](file:///abs/path/t1_login.png)`）。
  **不要编造路径**、不要只给裸文件路径、也不要把所有截图堆到报告末尾。

## 六、本载体下的已知边界（如实登记）

须要「外域交互式操作」或「浏览器容器级隔离」才能完成的测试点，在本平台**暂无载体**；
这类测试点记「暂不可用」并给出缺什么 + 补齐后即可用的判定，细则见 `control-browser` 包内
`references/deferred-capabilities.md`。**不得**因为载体缺失就把「只读取到了正文」写成「交互验收通过」。