agentic-browser-testing

使用浏览器 Agent 探索范围明确的自然语言目标，并从应用中收集证据。将稳定、高频的关键路径保留为脚本。页面发生变化时，浏览器 Agent 可以调整导航方式，但其探索过程仍存在不确定性。必须由项目自身的预言独立确认结果，CI 才能接受。保留有界运行、跟踪记录、类型化证据报告，以及后续编写持久 Playwright 回归测试的途径。

快速导航

情况	前往
从头搭建目标驱动的运行	探索 + references/setup.md
判断特定流程适合 Agent 驱动还是脚本驱动	适用性：意图驱动还是脚本驱动
Agent 一次运行通过，下一次却失败	可重复性
“没有截图，它怎么点击？”	交互模型
运行缓慢／消耗大量 Token	成本与延迟
Agent 错误地报告成功	成功断言（预言）
流程稳定了——将其固化	毕业 → references/graduation-and-ci.md
根据目标阻止合并	CI 门禁 → references/graduation-and-ci.md
Canvas／没有无障碍树	Canvas 回退方案 → references/graduation-and-ci.md

探索问题

首先，检查项目根目录中的 .agents/qa-project-context.md，跳过其中已有答案的问题（技术栈、环境、种子数据／重置工具、模型访问权限）。

1. 是哪条流程，其 UI 变化频率如何？ 快速变化／实验性 UI 更适合意图驱动；稳定的关键路径（如登录）更适合脚本驱动。这决定了整体方案。
2. 是否有种子数据夹具和重置状态的方法？ 可重复比较需要受控数据和逐次运行的重置。如果两者都没有，就先从这一步开始。
3. 能否通过深层链接跳过身份验证，进入带种子数据的入口？ 每次都重新执行登录是最容易避免的成本；种子数据入口 URL 可以限定目标并减少步骤。
4. 明确无歧义的成功预言是什么？ 特定账户文本、/dashboard URL、订单号——再加上一种禁止状态。“没有错误”不算预言。
5. 目标是否渲染到 Canvas／WebGL？ 没有无障碍树就无法采用快照优先方案；应规划视觉回退方案，或为 Canvas 添加 ARIA。
6. 使用哪种模型，预算是多少？ 选择可用的模型版本，并预先设定步骤、时间和 Token 预算。记录已安装的适配器，以及服务实际返回的模型。

---

核心原则

1. 在适用场景中选择意图驱动的探索。 Agent 会读取目标，并根据当前无障碍树选择控件。将其观察到的成本、延迟和可重复性与脚本检查进行比较，再决定是否用于关键路径。基于角色的脚本定位器也能适应许多布局和 CSS 变化。

2. 控制差异并衡量可重复性。 固定受支持的模型设置，重置数据夹具，限制步骤数和运行时长，并使用独立预言进行评估。温度设为零并固定模型，可以降低部分变化，但不能保证导航过程或判定结果完全一致。启用 CI 门禁前，先多次运行正常和故障对照测试。

3. 预言必须独立于 Agent。 绝不能让 LLM 自行判定“看起来没问题”。成功必须是根据最终 browser_snapshot 进行的可检查断言——包含特定预期文本、一个 URL，以及一项用于检查禁止状态的否定断言——并由测试框架而非模型进行评估。

4. 优先使用无障碍树，最后才用像素。 browser_snapshot 会以机器可读格式返回角色、引用和无障碍名称。截图、像素坐标、视觉识别和 OCR 仅在 Canvas 场景中作为明确限定的最后手段，而非默认方案。

5. 目标是完成毕业转换，而非永久运行 Agent。 流程稳定后，将运行转换为持久的脚本化 tests/*.spec.ts，并使用基于角色的定位器。Agent 连续两周通过后，就应将其转变为快速、免费的回归测试——保留 Agent 用于探索，而不是守护已经稳定的路径。

---

适用场景：意图驱动还是脚本化

决策应按流程逐一做出，而非按项目做出。如果需要风险图谱，请先运行 risk-based-testing；获取图谱后，按此表决定路由。

流程特征	使用方式	原因
稳定、高频的关键路径（登录、支付）	脚本化 + 固定版本（playwright-automation）	每次 PR 都会运行，并使用维护好的操作序列和明确的断言。
快速变化／实验性 UI（每周都在改动的仪表板、正在进行的重新设计）	Agent 驱动／意图驱动	选择器会不断失效；目标不受布局变动影响。
难以定位、无法可靠选择的流程	Agent 驱动	Agent 会按角色／名称查找控件，而不是让你反向分析选择器。
探索性冒烟测试／“快乐路径是否还完全可用”	Agent 驱动	一个自然语言目标就能覆盖许多场景，无需维护脚本。
CI 中任何绝不能误判为通过的测试	脚本化，或带有严格判定标准的 Agent 驱动测试	非确定性会带来误判为通过的风险，必须主动加以限制。

**简单来说：**稳定的关键路径应保持脚本化并固定版本；将意图驱动 Agent 用于快速变化的 UI 和探索性冒烟测试。不要把所有工作都交给 Agent。应按流程衡量成本、延迟和可重复性；并非每项测试都应由 Agent 驱动。

---

交互模型（优先使用无障碍树）

Playwright MCP 不是使用屏幕截图和像素坐标进行计算机操作。它优先使用无障碍树：

1. 使用 browser_navigate 前往已植入种子数据的入口 URL。
2. browser_snapshot 会返回无障碍树——每个交互元素都包含 role、当前 ref 和 accessible name（来自 ARIA／标签）。引用和快照大小取决于实时页面；导航或 DOM 发生变化后，请刷新快照。
3. Agent 通过 ref 选取元素，并调用 browser_click 或 browser_type。
4. browser_wait_for 会等待文本出现或消失，而不是执行固定时长的休眠。
5. DOM 发生变化后，重新调用 browser_snapshot；基于该树进行断言。

普通控件应使用语义快照，因为它们会直接显示角色和无障碍名称。请在实际页面上衡量 token 用量和耗时。需要视觉信息时再使用屏幕截图；不要仅凭屏幕截图推断正确性。browser_take_screenshot 仅用于提供人工查看的证据，绝不能作为断言输入。

请参阅 references/setup.md，了解 MCP 注册信息、完整工具表和目标提示词。

---

可重复性：让 CI 中的运行值得信赖

如果一次运行通过、下一次运行却失败，而应用没有任何改动，这还不能算测试。解决办法绝不是“只要重试”，也不是提高温度来进行“更聪明”的探索——这些做法只会增加方差。应固定变量：

调节项	设置
模型	固定的模型 ID（例如 claude-haiku-4-5-20251001），绝不使用 latest
采样	使用所支持的最低采样方差；记录设置，但不要声称具有确定性
数据	使用已植入种子数据的夹具 + 在每次运行前重置／植入种子数据库
范围	限制步骤预算（maxSteps），例如 18；超出预算即失败，绝不自动重试
判定标准	根据最新的应用观测结果进行独立检查
证据	对无障碍树进行断言，绝不使用屏幕截图差异

避免使用：用于探索的 temperature: 0.7 或 1、重试直到通过的循环、waitForTimeout 休眠，以及基于屏幕截图的断言。这些做法都会掩盖而不是消除不稳定性。适配器配置示例见 references/setup.md；这些字段需要实际的宿主适配器才能生效。

---

成功断言：判定器（Agent 会在这里悄无声息地失败）

这是最棘手的失败模式：Agent 卡在登录页面，却报告成功，因为“页面已加载 / 没有错误 / 看起来不错”被当作成功，而且 LLM 可以自行评分。强制使用由测试框架检查的明确判定器——绝不能由 Agent 检查。

对于目标 “以现有用户身份登录，并确认仪表盘显示了正确的账户名称”：

SUCCESS (all must hold — assert against the final browser_snapshot):
  - URL matches /dashboard
  - Snapshot contains the specific expected account name text, e.g. "Acme Corp — Jane R."
NEGATIVE / forbidden state (fail fast if any is true):
  - Still on a URL matching /login  → FAIL
  - Snapshot contains role="alert" with "invalid credentials"  → FAIL
VERDICT: a project-owned oracle executes these checks; the evidence gate emits passed:true only after fresh, complete checks. The LLM does not decide.

正向检查（具体的账户名称 + /dashboard URL）能证明最终到达的位置；负向检查（必须不在登录页面）则能杜绝误判通过。“没有错误”“没有崩溃”“截图看起来正确”和“相信 Agent”都不是成功标准。

---

成本和延迟

将 Agent 的延迟和成本与脚本方案进行比较。对于小型浏览器工作流，模型往返可能占据主要开销。通过明确的预算控制不必要的工作：

• 步骤预算——将 maxSteps 设得较低并强制执行；减少往返次数，降低偏离风险。
• 模型选择——根据实测的任务准确率、延迟和成本，选择可用模型。如果服务提供商支持，请固定模型版本。
• 提示词缓存——缓存静态系统提示词、工具架构和目标；它们会在每次运行时重复出现。
• 通过预置入口限定范围——每次运行只设定一个狭窄目标，并通过深层链接绕过登录，而不是每次都重新执行登录流程。
• 快照大小——在支持的情况下，将快照限定在相关区域。测量载荷大小；大型 DOM 也会导致文本快照开销高昂。

应拒绝的倒退做法：“每一步都使用最大规模的模型”“提高步骤上限”“每一步都截屏”以及完全不设预算地运行。参见 references/setup.md。

---

毕业迁移与 CI 门禁

将已稳定的目标升级为持久的脚本化测试，并根据判定结果控制合并。详细说明见 references/graduation-and-ci.md；核心要点如下：

• 使用 Playwright Test Agents（planner / generator / healer，随 Playwright v1.56.0 发布）进行毕业迁移。npx playwright init-agents --loop=claude。planner 将测试计划写入 Markdown 文件 specs/<flow>.md；generator 将其转换为 tests/<flow>.spec.ts，使用经实时 DOM 验证的基于角色的定位器（getByRole、getByLabel、getByText）；healer 修复失效的定位器。这才是升级路径——不是“继续把它作为 Agent 运行”，不是录制点击操作，不是 page.locator('xpath=...')，也不是只使用 data-testid。
• 使用完整 QA Skills 检出中的 scripts/agent-result-gate.mjs 为 CI 设置门禁。它会运行经过审查的判定器命令，并要求提供针对确切运行、目标和构建的、带类型且非空的证据。failed 和 blocked 都会以非零状态退出。宿主 Agent 适配器必须另行强制执行步骤 / 时间预算；模型生成的 {"passed": true} 无法通过此门禁。
• **没有无障碍树的画布：**优先为画布添加 ARIA；作为有范围限制的最后手段，仅对该工作流启用 --caps=vision，以使用 browser_mouse_click_xy。browser_snapshot 无法用于原始画布，但不要将坐标操作作为默认做法，也不要放弃 Agent 式测试。

---

将脆弱脚本迁移为目标（诚实权衡）

将一个会重新输入登录信息并执行 6 个硬编码步骤的 80 行脚本，转换为一个包含明确成功断言的单一自然语言目标，对于频繁变化的工作流确实有益——但也要诚实地说明缺点：

• 非确定性 / 误判通过风险——运行可能会错误地通过；因此，严格的判定器和负向检查不可妥协。
• 成本 / 延迟——两者都要测量；强制执行步骤预算、墙钟时间限制和预置入口。
• 并非每项测试都应采用 Agent 式测试——稳定路径应继续使用脚本，并计划在此流程稳定后将其升级迁移回脚本化测试。

拒绝过度承诺：这并非“严格更好且毫无缺点”，不要“迁移一切”，也绝不要为了让测试通过而删除断言。

反模式

1. 下意识地编写脚本化的 Playwright 测试

“浏览器测试”会让人联想到代码生成，因此默认做法就是使用 page.goto / page.locator / await expect(page...) / 搜寻 data-testid。这完全偏离了重点。目标驱动型 Agent 会读取自然语言意图，并通过 browser_snapshot 探索，而不是使用预先编写的选择器。

2. “什么事都用 Agent”

Agent 探索的成本、延迟和行为都不稳定。稳定的关键路径 （登录）应保留为脚本并固定下来；对于快速变化的 UI，则采用意图驱动的方式。绝不要“始终使用 Agent”或“Agent 取代所有脚本化测试”。

3. 用重试或更高温度来解决不稳定问题

“再试一次”和为了让探索“更聪明”而提高温度，都会增加变化。真正有效的调节手段是温度设为 0、固定模型、使用种子数据、限定步骤预算，以及明确的判定结果。

4. 认为 computer-use 就是截图加像素坐标

Playwright MCP 优先使用无障碍树。默认采用视觉、截图、OCR 或 mouse_click_xy 会更慢、成本更高，也更不稳定。像素坐标只是用于画布场景的最后手段。

5. “没有错误 = 成功”（虚假通过）

接受“页面已加载 / 没有崩溃 / 看起来不错”这样的结果，并让大模型自行评分，正是 Agent 卡在登录页面时仍报告成功的原因。必须要求明确的预期文本、URL 和用于检查禁止状态的反向断言，并由测试框架进行评估。

6. 用更大的模型 / 更多步骤来加快速度

增大模型或提高步骤上限并不能证明可靠性。应在相同任务和测试夹具下比较实际结果，再根据这些证据选择预算和模型。

7. 不断运行 Agent，而不是让它升级为脚本

如果某个目标在如今已稳定的流程中连续两周通过，就应使用 Playwright Test Agents 将其转为脚本化的 tests/*.spec.ts。 “继续把它作为 Agent 运行”、记录点击操作，以及使用 xpath 定位器，都不是正确的升级方式。

8. CI 中使用散文式判定结果

返回一段供人工阅读的文字，或设置 continue-on-error: true，都会让失败的目标合并。运行失败时必须以非零状态码退出，并返回机器可读的布尔值。

---

完成标准

• 目标提示词以自然语言意图编写（目标中不得出现 page.locator / page.goto / data-testid），并包含带种子数据的 START 入口 URL。
• 定义明确的成功判定条件：明确的预期文本 AND URL 检查 AND 禁止状态的反向检查，并基于 browser_snapshot 进行断言，而不是截图。
• 运行配置固定受支持的模型版本和采样设置、maxSteps 预算及种子；不得使用 waitForTimeout，也不得反复重试直到通过。
• 交互以快照为先：browser_navigate / browser_snapshot / browser_click / browser_type / browser_wait_for；截图仅用于提供证据。
• 适配器会输出类型化活动记录；独立门禁会执行已批准的判定条件并写入 gate-result.json。缺失或受阻的检查会导致 CI 失败，未通过的检查也会导致 CI 失败。
• CI 会在每次运行时为临时状态设置种子或重置状态，并强制执行步骤预算和超时上限。
• 记录升级触发条件（例如：“连续两周通过 → 运行 init-agents，使用 getByRole 定位器生成 tests/<flow>.spec.ts”）。
• 如果任何目标使用 canvas/WebGL，则视觉回退方案（--caps=vision + browser_mouse_click_xy）仅限用于该流程，或者为画布添加 ARIA 标注。

---

相关技能

• playwright-automation — 编写和维护确定性的 Playwright 脚本化测试和 Page Objects。前往该技能编写持久化测试；此技能会将一次 Agent 运行升级为持久化测试。
• ai-system-testing — 测试产品自身的 LLM/AI 功能（提示词回归、模型输出质量）。此技能测试的是使用 Agent 的任意应用，而不是你的 AI 功能。
• exploratory-testing — 由人工进行的 SBTM 探索和漏洞搜寻。Agent 式冒烟测试的目标是自动化版本；对于由测试任务驱动的人工测试会话，请使用 exploratory-testing。
• test-reliability — 在运行时为脚本化的不稳定测试提供自愈定位器和隔离机制。测试升级后，此技能可与这里的确定性调节手段互补。
• qa-project-context — 通用依赖；提供上述每个问题都依赖的技术栈、环境、种子数据/重置工具和模型访问权限。

参考文件（位于 references/）

• setup.md — Playwright MCP 注册（.mcp.json）、快照工具表、包含成功/否定断言的自然语言目标提示词、确定性测试框架配置（固定模型、温度 0、maxSteps、种子、提示词缓存），以及成本/延迟调节手段。
• graduation-and-ci.md — Playwright Test Agents 晋级流水线（规划器 → specs/*.md、生成器 → 使用基于角色定位器的 tests/*.spec.ts、修复器）、使用可执行的独立证据门控的 GitHub Actions 门控流程，以及 canvas 的 --caps=vision 回退方案。
• gate-contract.md — 精确的门控配置、适配器活动记录和预期证据架构，以及一个有界 HTTP 示例。需要项目自有的宿主适配器；不附带模型运行器。