Back to Details

test-browser

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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 "已安装" || echo "未安装"
如需安装：
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 "已就绪" || (echo "正在安装..." && 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. Detect Dev Server Port

4. 检测开发服务器端口

<detect_port>
Determine the dev server port using this priority order:
Priority 1: Explicit argument If the user passed a port number (e.g., 
/test-browser 5000
or 
/test-browser --port 5000
), use that port directly.
Priority 2: CLAUDE.md / project instructions
bash
undefined
<detect_port>
按照以下优先级确定开发服务器端口：
优先级1：显式参数 如果用户传入了端口号（例如：
/test-browser 5000
或
/test-browser --port 5000
），直接使用该端口。
优先级2：CLAUDE.md / 项目说明
bash
undefined

Check CLAUDE.md for port references

检查CLAUDE.md中的端口引用

grep -Eio '(port\s*[:=]\s*|localhost:)([0-9]{4,5})' CLAUDE.md 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1

**Priority 3: package.json scripts**
```bash
grep -Eio '(port\s*[:=]\s*|localhost:)([0-9]{4,5})' CLAUDE.md 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1

**优先级3：package.json脚本**
```bash

Check dev/start scripts for --port flags

检查dev/start脚本中的--port参数

grep -Eo '--port[= ]+[0-9]{4,5}' package.json 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1

**Priority 4: Environment files**
```bash
grep -Eo '--port[= ]+[0-9]{4,5}' package.json 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1

**优先级4：环境文件**
```bash

Check .env, .env.local, .env.development for PORT=

检查.env、.env.local、.env.development中的PORT=

grep -h '^PORT=' .env .env.local .env.development 2>/dev/null | tail -1 | cut -d= -f2

**Priority 5: Default fallback**
If none of the above yields a port, default to `3000`.

Store the result in a `PORT` variable for use in all subsequent steps.

```bash
grep -h '^PORT=' .env .env.local .env.development 2>/dev/null | tail -1 | cut -d= -f2

**优先级5：默认回退**
如果以上方式都未找到端口，默认使用`3000`。

将结果存储在`PORT`变量中，供后续步骤使用。

```bash

Combined detection (run this)

组合检测命令（运行此命令）

PORT="${EXPLICIT_PORT:-}" if [ -z "$PORT" ]; then PORT=$(grep -Eio '(port\s*[:=]\s*|localhost:)([0-9]{4,5})' CLAUDE.md 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1) fi if [ -z "$PORT" ]; then PORT=$(grep -Eo '--port[= ]+[0-9]{4,5}' package.json 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1) fi if [ -z "$PORT" ]; then PORT=$(grep -h '^PORT=' .env .env.local .env.development 2>/dev/null | tail -1 | cut -d= -f2) fi PORT="${PORT:-3000}" echo "Using dev server port: $PORT"

</detect_port>
PORT="${EXPLICIT_PORT:-}" if [ -z "$PORT" ]; then PORT=$(grep -Eio '(port\s*[:=]\s*|localhost:)([0-9]{4,5})' CLAUDE.md 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1) fi if [ -z "$PORT" ]; then PORT=$(grep -Eo '--port[= ]+[0-9]{4,5}' package.json 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1) fi if [ -z "$PORT" ]; then PORT=$(grep -h '^PORT=' .env .env.local .env.development 2>/dev/null | tail -1 | cut -d= -f2) fi PORT="${PORT:-3000}" echo "使用开发服务器端口：$PORT"

</detect_port>

5. Verify Server is Running

5. 验证服务器是否运行

<check_server>
Before testing, verify the local server is accessible using the detected port:
bash
agent-browser open http://localhost:${PORT}
agent-browser snapshot -i
If server is not running, inform user:
markdown
**Server not running on port ${PORT}**

Please start your development server:
- Rails: `bin/dev` or `rails server`
- Node/Next.js: `npm run dev`
- Custom port: `/test-browser --port <your-port>`

Then run `/test-browser` again.
</check_server>
<check_server>
测试前，验证本地服务器是否可通过检测到的端口访问：
bash
agent-browser open http://localhost:${PORT}
agent-browser snapshot -i
如果服务器未运行，请告知用户：
markdown
**服务器未在端口${PORT}运行**

请启动您的开发服务器：
- Rails：`bin/dev`或`rails server`
- Node/Next.js：`npm run dev`
- 自定义端口：`/test-browser --port <your-port>`

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

6. Test Each Affected Page

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

<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:${PORT}/[route]"
agent-browser snapshot -i
Step 2: For headed mode (visual debugging)
bash
agent-browser --headed open "http://localhost:${PORT}/[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:${PORT}/[route]"
agent-browser snapshot -i
步骤2：有头模式（可视化调试）
bash
agent-browser --headed open "http://localhost:${PORT}/[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>

7. Human Verification (When Required)

7. 人工验证（必要时）

<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"请确认您已收到SMS验证码"
外部API"请确认[服务]集成功能正常"
使用AskUserQuestion工具：
markdown
**需要人工验证**

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

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

8. Handle Failures

8. 处理测试失败

<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>

9. Test Summary

9. 测试总结

<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:${PORT}
测试范围：PR #[编号] / [分支名称] 服务器：http://localhost:${PORT}

Pages Tested: [count]

已测试页面数量：[数量]

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

Console Errors: [count]

控制台错误数量：[数量]

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

Human Verifications: [count]

人工验证数量：[数量]

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

Failures: [count]

失败数量：[数量]

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

Created Todos: [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 (auto-detects port)

测试当前分支的变更（自动检测端口）

/test-browser
/test-browser

Test specific PR

测试特定PR

/test-browser 847
/test-browser 847

Test specific branch

测试特定分支

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

Test on a specific port

在指定端口上测试

/test-browser --port 5000
undefined
/test-browser --port 5000
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