进阶 / 工作流

测试与探索

同样是驱动浏览器，测试有两种截然不同的姿势：一种是把重复的手动检查固化成可复跑的回归套件，像前端的单元测试；另一种是像真实用户一样系统地把应用逛一遍，挖出 bug 与体验问题，并带上完整复现证据。 chrome-use 两样都能干 —— 前者用 chrome-use test，后者用 dogfood 探索式流程。

两种测试姿势

先分清楚要做哪一件事，再往下选章节。它们的目标、产物和运行方式都不一样。

🧷 写可复跑的测试套件

把「打开它、点一点、看看对不对」固化成 *.yaml 套件，退出码可直接进 CI。

🔬 探索式测试 / 挖 bug

像用户一样系统地逛应用，边探索边记录，每个问题都留下截图、录像和复现步骤。

写可复跑的测试套件

把「打开它、点一点、确认对不对」这种反复的手工活变成 可复跑的套件，就像前端的单元测试。每发现一个回归就补一条用例 —— 用得越多，套件越值钱。

运行一个套件

$ chrome-use test <suite.yaml> [--launch | --session <name>] [--json]

全部用例通过退出码为 0，任一失败为 1 —— 直接丢进 CI。
默认在一个 cu-test 会话里启动全新的隔离浏览器（确定、可复现），跑完即关。
传 --session <name> 可对着一个已连接的会话跑（比如通过 chrome-use extension connect 接上的真实 Chrome）。
失败的用例会自动把截图存到 cu-test-artifacts/<case>.png。

套件格式（YAML）

一个套件由可选的 setup（所有用例前跑一次）和一组 cases 组成。每条用例有 steps（要做的动作）和 assert（要成立的检查）。

chatgpt-smoke.yaml

suite: chatgpt smoke               # 标签（可选）
setup:                             # 所有用例前跑一次（可选）
  - account: chatgpt/huayue        # 注入一个 cookie-use 存好的登录（可选）
  - open: https://chatgpt.com/     # …或任意普通步骤
cases:
  - name: home loads logged in
    steps:                         # 步骤复用 chrome-use 自己的命令
      - open: https://chatgpt.com/
      - wait: { load: networkidle }
    assert:                        # 所有断言都成立，用例才通过
      - url: { contains: chatgpt.com }
      - visible: "#prompt-textarea"
  - name: composer takes text
    steps:
      - fill: { sel: "#prompt-textarea", text: "hi" }
    assert:
      - text: { sel: "#prompt-textarea", contains: hi }
      - eval: "!!window.__NEXT_DATA__"

Steps —— 动作

每个 step 是一个「单键映射」，键就是一个 chrome-use 命令。

Step	含义
`open: <url>`	导航
`click: <selector\|@ref>`	点击
`fill: { sel: <s>, text: <t> }`	清空后输入
`type: { sel: <s>, text: <t> }`	输入（不清空）
`press: <key>`	按键（如 `Enter`）
`wait: <ms>` / `wait: { load: networkidle }` / `wait: <selector>`	等待
`scroll: <up\|down\|...>` 或 `{ dir: down, px: 500 }`	滚动
`eval: "<js>"`	执行 JS

Assertions —— 检查

所有断言最终都编译成一个 truthy 的 eval。

Assert	通过条件
`url: { contains\|equals\|matches: <v> }`	页面 URL 匹配
`visible: <selector>`	元素存在且已布局
`hidden: <selector>`	元素不存在 / 未布局
`text: { sel: <s>, contains\|equals\|matches: <v> }`	元素文本匹配
`count: { sel: <s>, eq: <n> }`	恰好 N 个元素匹配
`eval: "<js>"`	该 JS 表达式为真

ℹ️ 断言和步骤的关系

steps 先按顺序全部跑完，assert 再逐条独立求值。想了解 wait 与断言的更多写法，见等待与断言；步骤里用到的每个命令都在命令参考里。

✅ 套件之外：expect 动词

不想写整套 YAML，只想在一串命令里断言？chrome-use expect <条件> 是套件 assert: 的命令行同胞 —— 同一套契约，成立退出 0、不成立退出 1，可直接串进 shell： chrome-use click @save && chrome-use expect "#toast" visible。它默认轮询到条件成立或超时。想把一整段「点这、填那、断言」写成单趟脚本，见单趟脚本化。

登录与多账号

account: <id> 会把一个 cookie-use 存好的登录注入测试会话。它可以用在两个地方：

setup: —— 所有用例前注入一次，整个套件都以那个账号运行。
用例的 steps: 里 —— 在套件中途切换账号。新登录会在该用例的下一次 open／导航时生效，所以把 account: 放在 open 之前。这就是在一个套件里测「管理员看得到 X、普通成员看不到」，或在账号间来回横跳的办法。

rbac.yaml —— 权限对比

setup:
  - account: myapp/admin           # 以 admin 开场
cases:
  - name: admin sees the settings tab
    steps:
      - open: https://app.example.com/
    assert:
      - visible: "#settings-tab"
  - name: member does NOT see it
    steps:
      - account: myapp/member      # 切账号，下一次 open 时生效
      - open: https://app.example.com/
    assert:
      - hidden: "#settings-tab"
  - name: back to admin
    steps:
      - account: myapp/admin
      - open: https://app.example.com/
    assert:
      - visible: "#settings-tab"

⚠️ 需要 cookie-use

account: 依赖已安装的 cookie-use；不用它就直接省掉这一行。一次失败的 account: 切换（id 写错、或没装 cookie-use）会让那条用例失败，并给出清晰的原因。账号相关的更多细节见登录与凭证。

工作流

先用 open／snapshot／eval 手动做一遍，摸清选择器。
把它写成一条用例，放进 *.yaml 套件。
chrome-use test suite.yaml —— 绿了就说明没问题；红了会显示失败的断言 + 一张截图。
之后又发现回归？补一条用例。在 CI 里跑整个套件。

ℹ️ v1 的限制

断言在步骤跑完后各自独立求值。暂时没有用例级重试、没有并行用例、也没有 snapshot／screenshot 的基线 diff（先用一个针对已知内容的 eval 断言代替）。步骤按顺序执行，某个步骤失败会立刻让该用例失败。

探索式测试与 bug 挖掘（dogfood）

另一种测试不预设脚本，而是系统地把一个 Web 应用逛一遍，找出 bug、UX 问题和其它毛病，并为每个发现产出完整的复现证据 —— 逐步截图、复现录像、详细复现步骤 —— 好让结果能直接交给对应团队。

✅ 只有目标 URL 是必填

其它都可以走默认：会话名取域名的 slug（vercel.com → vercel-com），输出目录用 ./dogfood-output/，范围就是整个应用。选定一个目标 URL 就能开跑；只有需要登录的站点才额外准备账号凭据。下面的示例统一用会话 dogfood、目录 dogfood-output/、目标 https://vercel.com，照着替换成你自己的即可。

⚠️ 用 chrome-use，别用 npx chrome-use

始终直接调 chrome-use —— 直接二进制走的是快速的 Rust 客户端；npx 绕道 Node.js，明显更慢。

六步流程

步骤	做什么
1. Initialize	建会话、输出目录、报告文件
2. Authenticate	需要就登录，保存状态
3. Orient	导航到起点，拍第一张 snapshot
4. Explore	系统地访问页面、测试功能
5. Document	边发现边截图 + 记录每个问题
6. Wrap up	更新汇总计数，关闭会话

初始化与登录

初始化 + 起会话

$ mkdir -p dogfood-output/screenshots dogfood-output/videos

# 起一个具名会话，导航到目标
$ chrome-use --session dogfood open https://vercel.com
$ chrome-use --session dogfood wait --load networkidle

需要登录时，用 snapshot -i 找到表单的 @ref，填好后提交，再把状态存起来备用。OTP／邮箱验证码要向用户询问，等回复后再输入。

登录并保存状态

$ chrome-use --session dogfood snapshot -i
# 找到登录表单的 ref，填入凭据
$ chrome-use --session dogfood fill @e1 "you@example.com"
$ chrome-use --session dogfood fill @e2 "your-password"
$ chrome-use --session dogfood click @e3
$ chrome-use --session dogfood wait --load networkidle

# 登录成功后保存状态，方便复用
$ chrome-use --session dogfood state save dogfood-output/auth-state.json

探索与取证

从主导航开始，逐个访问顶层区块；在每个区块里测试可交互元素（点按钮、填表单、开下拉／弹窗）；检查空状态、错误处理、边界输入；跑真实的端到端流程（增删改）。

⚠️ console / errors 默认是空的

这个 stealth fork 默认关闭控制台与错误捕获。要用 console／errors，得在起会话时带上 AGENT_BROWSER_CAPTURE_CONSOLE=1，例如 AGENT_BROWSER_CAPTURE_CONSOLE=1 chrome-use --session dogfood open <url>，否则它们返回空。

每个页面的四连击

$ chrome-use --session dogfood snapshot -i
$ chrome-use --session dogfood screenshot --annotate dogfood-output/screenshots/dashboard.png
$ chrome-use --session dogfood errors
$ chrome-use --session dogfood console

✅ 选对 snapshot 姿势

snapshot -i —— 找可点击／可填写的元素（按钮、输入框、链接）； snapshot（不带 flag）—— 读页面内容（文本、标题、数据列表）。

复现优先：交互型 vs 静态型

探索和记录是同一趟完成的：发现问题就停下来立刻记录，再继续。按问题类型选取证据的粒度。

交互 / 行为型问题

需要用户交互才能复现（功能、UX、动作触发的控制台报错）—— 用带录像和逐步截图的完整复现：先开录像，再以人的节奏走一遍步骤，每步截图，最后拍下损坏状态。

录像 + 逐步截图

# 1. 复现前先开录像
$ chrome-use --session dogfood record start dogfood-output/videos/issue-001-repro.webm

# 2. 以人的节奏走步骤，动作间停 1-2 秒，每步截图
$ chrome-use --session dogfood screenshot dogfood-output/screenshots/issue-001-step-1.png
$ sleep 1
# 执行动作（click / fill 等），再 sleep 1，再 step-2 截图……

# 3. 拍下损坏状态（先停顿让观者看清）
$ sleep 2
$ chrome-use --session dogfood screenshot --annotate dogfood-output/screenshots/issue-001-result.png

# 4. 停录像
$ chrome-use --session dogfood record stop

静态 / 加载即可见问题

无需交互就能看到（错别字、占位文本、截断文本、错位、加载即报的控制台错误）—— 一张标注截图就够，别录像、别多步复现，把「复现录像」设为 N/A。

静态问题：一张标注截图

$ chrome-use --session dogfood screenshot --annotate dogfood-output/screenshots/issue-002.png

报告长什么样

所有发现都汇进一份 Markdown 报告（比如 dogfood-output/report.md）：顶部一段按严重度分类的汇总计数，下面每个问题一个 ### ISSUE- 块，块里带上严重度、页面、复现步骤和证据文件路径。

dogfood-output/report.md

# Dogfood 报告 · vercel.com

## 汇总
- Critical: 0
- Major: 1
- Minor: 1

### ISSUE-001 · [Major] 保存后 Toast 一直不消失
- 页面: /dashboard/settings
- 复现步骤:
  1. 打开 Settings，改名后点 Save
  2. 等待 5 秒
- 期望: Toast 约 3 秒后消失
- 实际: Toast 一直停留
- 证据: screenshots/issue-001-result.png, videos/issue-001-repro.webm

### ISSUE-002 · [Minor] 页脚版权年份仍是 2019
- 页面: /
- 证据: screenshots/issue-002.png（复现录像: N/A）

收尾

目标是找出 5–10 个有充分记录的问题就收工 —— 证据的深度比数量更重要，5 个带完整复现胜过 20 个语焉不详的。之后回读报告、更新顶部的严重度计数（每个 ### ISSUE- 块都要反映在汇总总数里），最后关闭会话。

关闭会话

$ chrome-use --session dogfood close

几条硬规矩

⚠️ 别读被测应用的源码

你是以用户身份测试，不是审计代码。不要读被测应用的 HTML／JS／配置。所有发现都必须来自你在浏览器里观察到的现象。

复现是一切：每个问题都要有证据，但要匹配粒度 —— 交互型才需要录像和逐步截图，静态型只要一张标注截图。
收证前先验证可复现：录像／截图之前，至少重试一次确认能稳定复现；复现不稳定就不算有效问题。
增量写报告：一发现就追加进报告，别攒到最后。会话被打断也不丢发现。
永不删输出：中途不要 rm 截图、录像或报告，也不要关掉会话再重启。只往前走。
像人一样打字：录像时填表单用 type（逐字符），只有在不录像、追求速度时才用 fill。
为人调节录像节奏：动作间加 sleep 1、最终结果截图前加 sleep 2，让录像在 1x 下可看。
查控制台：很多问题在 UI 上看不见，却以 JS 报错或失败请求的形式出现。

接下来

⏳ 等待与断言

把 wait 和断言的写法吃透，套件才稳。

📚 命令参考

steps 里每个动词的完整用法都在这里。