Back to Details

test-browser

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Arguments

参数

[PR number, branch name, or 'current' for current branch]
[PR编号、分支名称，或使用'current'指代当前分支]

Browser Test Command

浏览器测试命令

<command_purpose>Run end-to-end browser tests on pages affected by a PR or branch changes using agent-browser CLI.</command_purpose>
<command_purpose>使用agent-browser CLI针对PR或分支变更影响的页面运行端到端浏览器测试。</command_purpose>

CRITICAL: Use agent-browser CLI Only

重要提示：仅使用agent-browser CLI

DO NOT use Chrome MCP tools (mcp__claude-in-chrome__*).
This command uses the 
agent-browser
CLI exclusively. The agent-browser CLI is a Bash-based tool from Vercel that runs headless Chromium. It is NOT the same as Chrome browser automation via MCP.
If you find yourself calling 
mcp__claude-in-chrome__*
tools, STOP. Use 
agent-browser
Bash commands instead.
请勿使用Chrome MCP工具（mcp__claude-in-chrome__*）。
本命令仅使用
agent-browser
CLI。agent-browser CLI是Vercel推出的基于Bash的工具，可运行无头Chromium。它与通过MCP实现的Chrome浏览器自动化并非同一工具。
若你发现自己在调用
mcp__claude-in-chrome__*
工具，请立即停止。改用
agent-browser
Bash命令。

Introduction

简介

<role>QA Engineer specializing in browser-based end-to-end testing</role>
This command tests affected pages in a real browser, catching issues that unit tests miss:
  • JavaScript integration bugs
  • CSS/layout regressions
  • User workflow breakages
  • Console errors
<role>专注于浏览器端到端测试的QA工程师</role>
本命令在真实浏览器中测试受影响的页面，能够捕捉单元测试遗漏的问题：
  • JavaScript集成bug
  • CSS/布局回归问题
  • 用户流程中断
  • 控制台错误

Prerequisites

前置条件

<requirements> - Local development server running (e.g., `bin/dev`, `rails server`, `npm run dev`) - agent-browser CLI installed (see Setup below) - Git repository with changes to test </requirements>
<requirements> - 本地开发服务器已启动（例如：`bin/dev`、`rails server`、`npm run dev`） - 已安装agent-browser CLI（详见下方设置步骤） - 包含待测试变更的Git仓库 </requirements>

Setup

设置

Check installation:
bash
command -v agent-browser >/dev/null 2>&1 && echo "Installed" || echo "NOT INSTALLED"
Install if needed:
bash
npm install -g agent-browser
agent-browser install  # Downloads Chromium (~160MB)
See the 
agent-browser
skill for detailed usage.
检查安装情况：
bash
command -v agent-browser >/dev/null 2>&1 && echo "Installed" || echo "NOT INSTALLED"
如需安装：
bash
npm install -g agent-browser
agent-browser install  # 下载Chromium（约160MB）
如需详细使用说明，请查看
agent-browser
相关文档。

Main Tasks

主要任务

0. Verify agent-browser Installation

0. 验证agent-browser安装

Before starting ANY browser testing, verify agent-browser is installed:
bash
command -v agent-browser >/dev/null 2>&1 && echo "Ready" || (echo "Installing..." && npm install -g agent-browser && agent-browser install)
If installation fails, inform the user and stop.
在开始任何浏览器测试前，先验证agent-browser是否已安装：
bash
command -v agent-browser >/dev/null 2>&1 && echo "Ready" || (echo "Installing..." && npm install -g agent-browser && agent-browser install)
若安装失败，请告知用户并停止操作。

1. Ask Browser Mode

1. 询问浏览器模式

<ask_browser_mode>
Before starting tests, ask user if they want to watch the browser:
Use AskUserQuestion with:
  • Question: "Do you want to watch the browser tests run?"
  • Options:
    1. Headed (watch) - Opens visible browser window so you can see tests run
    2. Headless (faster) - Runs in background, faster but invisible
Store the choice and use 
--headed
flag when user selects "Headed".
</ask_browser_mode>
<ask_browser_mode>
开始测试前，询问用户是否希望查看浏览器运行过程：
使用AskUserQuestion工具，内容如下：
  • 问题："你是否希望查看浏览器测试的运行过程？"
  • 选项：
    1. 有头模式（可查看） - 打开可见的浏览器窗口，以便你查看测试运行过程
    2. 无头模式（更快） - 在后台运行，速度更快但不可见
保存用户的选择，当用户选择“有头模式”时，使用
--headed
参数。
</ask_browser_mode>

2. Determine Test Scope

2. 确定测试范围

<test_target> $ARGUMENTS </test_target>
<determine_scope>
If PR number provided:
bash
gh pr view [number] --json files -q '.files[].path'
If 'current' or empty:
bash
git diff --name-only main...HEAD
If branch name provided:
bash
git diff --name-only main...[branch]
</determine_scope>
<test_target> $ARGUMENTS </test_target>
<determine_scope>
若提供了PR编号：
bash
gh pr view [number] --json files -q '.files[].path'
若为'current'或未提供参数：
bash
git diff --name-only main...HEAD
若提供了分支名称：
bash
git diff --name-only main...[branch]
</determine_scope>

3. Map Files to Routes

3. 文件与路由映射

<file_to_route_mapping>
Map changed files to testable routes:
File PatternRoute(s)
app/views/users/*
/users
, 
/users/:id
, 
/users/new
app/controllers/settings_controller.rb
/settings
app/javascript/controllers/*_controller.js
Pages using that Stimulus controller
app/components/*_component.rb
Pages rendering that component
app/views/layouts/*
All pages (test homepage at minimum)
app/assets/stylesheets/*
Visual regression on key pages
app/helpers/*_helper.rb
Pages using that helper
src/app/*
(Next.js)		Corresponding routes
src/components/*
Pages using those components
Build a list of URLs to test based on the mapping.
</file_to_route_mapping>
<file_to_route_mapping>
将变更文件映射到可测试的路由：
文件模式路由
app/views/users/*
/users
, 
/users/:id
, 
/users/new
app/controllers/settings_controller.rb
/settings
app/javascript/controllers/*_controller.js
使用该Stimulus控制器的页面
app/components/*_component.rb
渲染该组件的页面
app/views/layouts/*
所有页面（至少测试首页）
app/assets/stylesheets/*
关键页面的视觉回归测试
app/helpers/*_helper.rb
使用该助手的页面
src/app/*
(Next.js)		对应的路由
src/components/*
使用这些组件的页面
根据上述映射，构建待测试的URL列表。
</file_to_route_mapping>

4. Verify Server is Running

4. 验证服务器是否运行

<check_server>
Before testing, verify the local server is accessible:
bash
agent-browser open http://localhost:3000
agent-browser snapshot -i
If server is not running, inform user:
markdown
**Server not running**

Please start your development server:
- Rails: `bin/dev` or `rails server`
- Node/Next.js: `npm run dev`

Then run `/test-browser` again.
</check_server>
<check_server>
测试前，验证本地服务器是否可访问：
bash
agent-browser open http://localhost:3000
agent-browser snapshot -i
若服务器未运行，请告知用户：
markdown
**服务器未运行**

请启动你的开发服务器：
- Rails: `bin/dev` 或 `rails server`
- Node/Next.js: `npm run dev`

之后重新运行`/test-browser`。
</check_server>

5. Test Each Affected Page

5. 测试每个受影响的页面

<test_pages>
For each affected route, use agent-browser CLI commands (NOT Chrome MCP):
Step 1: Navigate and capture snapshot
bash
agent-browser open "http://localhost:3000/[route]"
agent-browser snapshot -i
Step 2: For headed mode (visual debugging)
bash
agent-browser --headed open "http://localhost:3000/[route]"
agent-browser --headed snapshot -i
Step 3: Verify key elements
  • Use 
    agent-browser snapshot -i
    to get interactive elements with refs
  • Page title/heading present
  • Primary content rendered
  • No error messages visible
  • Forms have expected fields
Step 4: Test critical interactions
bash
agent-browser click @e1  # Use ref from snapshot
agent-browser snapshot -i
Step 5: Take screenshots
bash
agent-browser screenshot page-name.png
agent-browser screenshot --full page-name-full.png  # Full page
</test_pages>
<test_pages>
针对每个受影响的路由，使用agent-browser CLI命令（请勿使用Chrome MCP工具）：
步骤1：导航并捕获快照
bash
agent-browser open "http://localhost:3000/[route]"
agent-browser snapshot -i
步骤2：有头模式（可视化调试）
bash
agent-browser --headed open "http://localhost:3000/[route]"
agent-browser --headed snapshot -i
步骤3：验证关键元素
  • 使用
    agent-browser snapshot -i
    获取带引用的交互元素
  • 页面标题/标题内容存在
  • 主要内容已渲染
  • 无可见错误提示
  • 表单包含预期字段
步骤4：测试关键交互
bash
agent-browser click @e1  # 使用快照中的引用
agent-browser snapshot -i
步骤5：截取屏幕截图
bash
agent-browser screenshot page-name.png
agent-browser screenshot --full page-name-full.png  # 完整页面截图
</test_pages>

6. Human Verification (When Required)

6. 人工验证（必要时）

<human_verification>
Pause for human input when testing touches:
Flow TypeWhat to Ask
OAuth"Please sign in with [provider] and confirm it works"
Email"Check your inbox for the test email and confirm receipt"
Payments"Complete a test purchase in sandbox mode"
SMS"Verify you received the SMS code"
External APIs"Confirm the [service] integration is working"
Use AskUserQuestion:
markdown
**Human Verification Needed**

This test touches the [flow type]. Please:
1. [Action to take]
2. [What to verify]

Did it work correctly?
1. Yes - continue testing
2. No - describe the issue
</human_verification>
<human_verification>
当测试涉及以下流程时，暂停并等待用户输入：
流程类型询问内容
OAuth"请使用[服务商]登录并确认功能正常"
邮件"检查你的收件箱，确认收到测试邮件"
支付"在沙箱模式下完成一笔测试购买"
SMS"验证你是否收到了短信验证码"
外部API"确认[服务]集成功能正常"
使用AskUserQuestion工具，内容如下：
markdown
**需要人工验证**

本次测试涉及[流程类型]。请：
1. [执行操作]
2. [验证内容]

功能是否正常？
1. 是 - 继续测试
2. 否 - 描述问题
</human_verification>

7. Handle Failures

7. 处理测试失败

<failure_handling>
When a test fails:
  1. Document the failure:
    • Screenshot the error state: 
      agent-browser screenshot error.png
    • Note the exact reproduction steps
  2. Ask user how to proceed:
    markdown
    **Test Failed: [route]**

Issue: [description]
Console errors: [if any]

How to proceed?
1. Fix now - I'll help debug and fix
2. Create todo - Add to todos/ for later
3. Skip - Continue testing other pages
  3. If "Fix now":
    • Investigate the issue
    • Propose a fix
    • Apply fix
    • Re-run the failing test
  4. If "Create todo":
    • Create 
      {id}-pending-p1-browser-test-{description}.md
    • Continue testing
  5. If "Skip":
    • Log as skipped
    • Continue testing
</failure_handling>
<failure_handling>
当测试失败时：
  1. 记录失败信息：
    • 截取错误状态的截图：
      agent-browser screenshot error.png
    • 记录准确的复现步骤
  2. 询问用户如何处理：
    markdown
    **测试失败：[route]**

问题：[描述]
控制台错误：[如有]

如何处理？
1. 立即修复 - 我将协助调试和修复
2. 创建待办事项 - 添加到todos/留待后续处理
3. 跳过 - 继续测试其他页面
  3. 若选择“立即修复”：
    • 调查问题
    • 提出修复方案
    • 应用修复
    • 重新运行失败的测试
  4. 若选择“创建待办事项”：
    • 创建文件
      {id}-pending-p1-browser-test-{description}.md
    • 继续测试
  5. 若选择“跳过”：
    • 记录为已跳过
    • 继续测试
</failure_handling>

8. Test Summary

8. 测试总结

<test_summary>
After all tests complete, present summary:
markdown
undefined
<test_summary>
所有测试完成后，呈现总结报告：
markdown
undefined

Browser Test Results

浏览器测试结果

Test Scope: PR #[number] / [branch name] Server: http://localhost:3000
测试范围：PR #[number] / [branch name] 服务器：http://localhost:3000

Pages Tested: [count]

已测试页面数量：[count]

RouteStatusNotes
/users
Pass
/settings
Pass
/dashboard
FailConsole error: [msg]
/checkout
SkipRequires payment credentials
路由状态备注
/users
通过
/settings
通过
/dashboard
失败控制台错误：[消息]
/checkout
跳过需要支付凭证

Console Errors: [count]

控制台错误数量：[count]

  • [List any errors found]
  • [列出所有发现的错误]

Human Verifications: [count]

人工验证数量：[count]

  • OAuth flow: Confirmed
  • Email delivery: Confirmed
  • OAuth流程：已确认
  • 邮件发送：已确认

Failures: [count]

失败数量：[count]

  • /dashboard
    - [issue description]
  • /dashboard
    - [问题描述]

Created Todos: [count]

已创建待办事项数量：[count]

  • 005-pending-p1-browser-test-dashboard-error.md
  • 005-pending-p1-browser-test-dashboard-error.md

Result: [PASS / FAIL / PARTIAL]

最终结果：[通过 / 失败 / 部分通过]


</test_summary>

</test_summary>

Quick Usage Examples

快速使用示例

bash
undefined
bash
undefined

Test current branch changes

测试当前分支的变更

/test-browser
/test-browser

Test specific PR

测试指定PR

/test-browser 847
/test-browser 847

Test specific branch

测试指定分支

/test-browser feature/new-dashboard
undefined
/test-browser feature/new-dashboard
undefined

agent-browser CLI Reference

agent-browser CLI参考

ALWAYS use these Bash commands. NEVER use mcp__claude-in-chrome__ tools.*
bash
undefined
请始终使用以下Bash命令。请勿使用mcp__claude-in-chrome__*工具。
bash
undefined

Navigation

导航

agent-browser open <url> # Navigate to URL agent-browser back # Go back agent-browser close # Close browser
agent-browser open <url> # 导航到指定URL agent-browser back # 返回上一页 agent-browser close # 关闭浏览器

Snapshots (get element refs)

快照（获取元素引用）

agent-browser snapshot -i # Interactive elements with refs (@e1, @e2, etc.) agent-browser snapshot -i --json # JSON output
agent-browser snapshot -i # 获取带引用的交互元素（@e1、@e2等） agent-browser snapshot -i --json # JSON格式输出

Interactions (use refs from snapshot)

交互操作（使用快照中的元素引用）

agent-browser click @e1 # Click element agent-browser fill @e1 "text" # Fill input agent-browser type @e1 "text" # Type without clearing agent-browser press Enter # Press key
agent-browser click @e1 # 点击元素 agent-browser fill @e1 "text" # 填充输入框 agent-browser type @e1 "text" # 输入内容（不清空原有内容） agent-browser press Enter # 按下按键

Screenshots

截图

agent-browser screenshot out.png # Viewport screenshot agent-browser screenshot --full out.png # Full page screenshot
agent-browser screenshot out.png # 视口截图 agent-browser screenshot --full out.png # 完整页面截图

Headed mode (visible browser)

有头模式（可见浏览器）

agent-browser --headed open <url> # Open with visible browser agent-browser --headed click @e1 # Click in visible browser
agent-browser --headed open <url> # 在可见浏览器中打开URL agent-browser --headed click @e1 # 在可见浏览器中点击元素

Wait

等待

agent-browser wait @e1 # Wait for element agent-browser wait 2000 # Wait milliseconds
undefined
agent-browser wait @e1 # 等待元素出现 agent-browser wait 2000 # 等待指定毫秒数
undefined