agent-browser

Agent Browser 测试技能

使用 Vercel 的 agent-browser CLI 进行浏览器自动化和端到端测试。通过基于 ref 的元素定位，实现可靠且便于 AI 使用的浏览器交互。

快速决策树

What do you need?
│
├─ Take a screenshot of a page?
│  └─ agent-browser open [url] && agent-browser screenshot
│
├─ Fill out a form?
│  └─ open → snapshot -i → fill @ref → click @submit → snapshot
│
├─ Test a login flow?
│  └─ See references/authentication.md
│
├─ Run an E2E test?
│  └─ See references/testing-patterns.md
│
├─ Scrape page content?
│  └─ agent-browser open [url] && agent-browser snapshot -i
│
└─ Debug element targeting?
   └─ agent-browser snapshot -i --format json

安装

# Install agent-browser globally
npm install -g agent-browser

# Install browser dependencies (Chromium)
agent-browser install

# Verify installation
agent-browser --version

核心概念：基于 Ref 的定位

Agent-browser 使用 ref（例如 @e1、@e2、@e3）来识别页面上的交互元素。这些 ref 会在你生成快照时分配。

# Take a snapshot with interactive elements labeled
agent-browser snapshot -i

# Output shows refs:
# @e1: [button] "Sign In"
# @e2: [input] Email field
# @e3: [input] Password field
# @e4: [button] "Submit"

# Use refs to interact
agent-browser click @e1
agent-browser fill @e2 "[email protected]"

重要提示： Ref 仅对当前会话有效，并会在页面发生变化时失效。导航或 DOM 更新后，务必重新生成快照。

基本工作流

# 1. Open the target URL
agent-browser open https://example.com

# 2. Take a snapshot to see the page and get refs
agent-browser snapshot -i

# 3. Interact with elements using refs
agent-browser click @e1
agent-browser fill @e2 "test value"

# 4. Take another snapshot to verify changes
agent-browser snapshot -i

常用命令速查

导航

agent-browser open <url>              # Navigate to URL
agent-browser back                    # Go back
agent-browser forward                 # Go forward
agent-browser refresh                 # Reload page

快照

agent-browser snapshot                # Text snapshot
agent-browser snapshot -i             # With interactive refs
agent-browser snapshot --format json  # JSON output
agent-browser screenshot [path]       # Save screenshot

交互

agent-browser click @ref              # Click element
agent-browser fill @ref "value"       # Fill input field
agent-browser select @ref "option"    # Select dropdown option
agent-browser hover @ref              # Hover over element
agent-browser press Enter             # Press keyboard key

语义定位器

agent-browser find role button "Submit"    # Find by ARIA role
agent-browser find text "Welcome"          # Find by visible text
agent-browser find label "Email"           # Find by label

等待

agent-browser wait visible @ref            # Wait for element visible
agent-browser wait hidden @ref             # Wait for element hidden
agent-browser wait network                 # Wait for network idle
agent-browser wait time 2000               # Wait milliseconds

会话管理

agent-browser session save mystate         # Save browser state
agent-browser session load mystate         # Load saved state
agent-browser session list                 # List saved sessions
agent-browser close                        # Close browser

安全说明

切勿提交以下文件：

• *.state - 浏览器会话状态文件包含 Cookie
• agent-browser-profile/ - 包含凭据的配置文件目录
• 可能包含敏感数据的截图

添加到 .gitignore：

*.state
agent-browser-profile/
.agent-browser/
screenshots/

与其他技能集成

与并行研究集成

# Research a topic, then verify claims on websites
parallel_research.py chat "Find pricing for Acme Corp"
# Then use agent-browser to verify on their actual pricing page
agent-browser open https://acme.com/pricing
agent-browser snapshot -i

与截图比较集成

# Take baseline screenshots for visual regression
agent-browser open https://myapp.com
agent-browser screenshot baseline.png

# After changes, compare
agent-browser screenshot current.png
# Use image comparison tool

使用表格中的表单数据

# Load test data from Google Sheets, run form tests
import subprocess
test_data = get_sheet_data("Form Test Cases")
for row in test_data:
    subprocess.run(["agent-browser", "fill", "@email", row["email"]])
    subprocess.run(["agent-browser", "fill", "@password", row["password"]])
    subprocess.run(["agent-browser", "click", "@submit"])

此技能包含的文件

• references/commands.md - 完整命令参考
• references/authentication.md - 登录流程模式
• references/testing-patterns.md - 端到端测试工作流
• references/snapshot-workflow.md - 深入了解 Ref 系统
• scripts/browser_test.py - Python 自动化封装程序

示例：完整的表单测试

# Open the registration page
agent-browser open https://example.com/register

# Get element refs
agent-browser snapshot -i

# Fill the form (refs from snapshot output)
agent-browser fill @e1 "John Doe"
agent-browser fill @e2 "[email protected]"
agent-browser fill @e3 "SecurePass123!"
agent-browser select @e4 "United States"
agent-browser click @e5  # Terms checkbox
agent-browser click @e6  # Submit button

# Wait for navigation and verify
agent-browser wait network
agent-browser snapshot -i

# Take confirmation screenshot
agent-browser screenshot registration-success.png

故障排查

未找到元素：

• 重新运行 snapshot -i，获取最新的 ref
• 使用语义定位器：agent-browser find text "Submit"
• 检查元素是否位于 iframe 中

页面未加载：

• 增加超时时间：agent-browser open <url> --timeout 30000
• 等待网络：agent-browser wait network

会话已过期：

• 在测试前保存状态：agent-browser session save backup
• 加载状态以恢复会话：agent-browser session load backup