核心用法 / Core Usage

Agent 翻车，更多是败在乱等，而不是选错元素。 点完、填完之后，页面还在动——这时候该等什么、怎么确认动作真的生效， 决定了你的脚本是稳还是脆。这一页讲清楚 wait 怎么等、 expect 怎么断言、--observe 怎么看变化， 以及 --if-present 怎么让可选步骤保持幂等。

选对等待条件 — wait

每次会改变页面的动作之后，都要挑一个具体的条件去等， 而不是拍脑袋 sleep 一个固定毫秒数。wait 支持这些形式：

$ chrome-use wait @e1                     # 直到某个元素出现
$ chrome-use wait 2000                    # 傻等，毫秒（最后手段）
$ chrome-use wait --text "Success"        # 直到页面上出现这段文字
$ chrome-use wait --url "**/dashboard"    # 直到 URL 匹配模式（glob）
$ chrome-use wait --load networkidle       # 直到网络空闲（导航后收尾）
$ chrome-use wait --load domcontentloaded  # 直到 DOMContentLoaded
$ chrome-use wait --fn "window.myApp.ready === true"  # 直到 JS 条件成立

任何会改变页面的动作之后，从下面三种里挑一个：

• 等你预期会出现的具体元素：wait @ref 或 wait --text "..."。
• 等 URL 变化：wait --url "**/new-page"。
• 等网络空闲（SPA 导航的万能兜底）：wait --load networkidle。

确认动作生效 — expect

动作做完之后，用断言去确认结果，而不是拉一张快照用眼睛看。 expect 是一个带退出码的 pass/fail 动词 （0 通过 / 1 为假 / 2 无法判断），所以它能和 &&、 chrome-use batch 组合，而且只花 ~1 行、不用你去读一整张快照。

$ chrome-use click @e8 && chrome-use expect "#toast" visible      # toast 弹出来了吗？
$ chrome-use expect count ".result" ">=" 1                        # 结果加载出来了吗？
$ chrome-use expect text @e3 contains "Saved"                    # 成功提示？
$ chrome-use expect url contains /dashboard                       # 导航落地了吗？
$ chrome-use expect "#spinner" gone                               # 加载完成了？
$ chrome-use requests --clear && chrome-use click @save \
    && chrome-use expect request /api/save --status 2xx           # POST 发出且 2xx？
$ chrome-use expect no-errors                                     # 没有 console 报错？

expect 自带等待

expect 会在超时时间内轮询、等条件成立， 所以你常常不需要再单独写一个 wait。支持的条件有：

• 元素状态：visible | hidden | gone | present；
• 数量：count <css> <op> <n>；
• 文本/值/属性：text|value|attr … equals|contains|matches；
• URL：url …；
• 网络请求：request <substr> [--status 2xx]；
• 控制台：no-errors。

--not 反转判断，--no-wait 只检查一次不轮询。

看清动作改了什么 — --observe

给一个会改变页面的动作（click / fill / type / select / check / press / eval） 加上 --observe，就不用你手动跑「动作 → wait → snapshot → diff」那一套了： 返回结果里会带一个 observed 增量——新增/移除的可交互行 （新的 toast、校验提示也会通过 alert 面通道带上）、URL 变化、发出的请求； 什么都没动就返回 {changed:false}。

$ chrome-use click @e8 --observe   # 一条 ~20-80 token 的回复里就看到弹出的对话框/toast/新行

一次填完整张表单 — form fill --map

与其写 N 步 fill / select / check， 不如传一个 {标签或选择器: 值} 的映射：它按 <label>、 aria-label、placeholder、name、CSS 逐个解析字段，自动派发到对应的控件类型 （字符串 → 文本/下拉/单选，true/false → 复选框）， 还能顺手提交（--submit "<文本|选择器>"），返回 {filled, submitted, errors}——errors 就是行内校验消息， 所以一次提交被拒会在同一次调用里告诉你为什么。

$ chrome-use form fill --map \
    '{"Email":"a@b.com","Country":"US","Subscribe":true}' \
    --submit "Sign up"

可选步骤 — --if-present

给任意基于选择器的动作加上 --if-present（别名 --optional）， 当目标不存在时它就变成一个空操作但成功（↷ skipped，退出码 0）， 而不是报错——不用事先读一遍页面判断，流程也能反复重跑。

$ chrome-use click ".cookie-accept" --if-present   # 关掉可能不存在的 cookie 横幅
$ chrome-use check "#opt-in" --if-present

下一步