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 Pattern	Route(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

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


</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 Type	What 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:

Document the failure:
- Screenshot the error state:
```
agent-browser screenshot error.png
```
- Note the exact reproduction steps

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

If "Fix now":
- Investigate the issue
- Propose a fix
- Apply fix
- Re-run the failing test

If "Create todo":

Create

{id}-pending-p1-browser-test-{description}.md

Continue testing

If "Skip":
- Log as skipped
- Continue testing

</failure_handling>

<failure_handling>

当测试失败时：

记录失败情况：
- 截取错误状态的截图：
```
agent-browser screenshot error.png
```
- 记录准确的复现步骤

询问用户如何继续：

markdown

**测试失败：[route]**

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

如何继续？
1. 立即修复 - 我会帮助调试和修复
2. 创建待办事项 - 添加到todos/中后续处理
3. 跳过 - 继续测试其他页面

如果选择“立即修复”：
- 调查问题
- 提出修复方案
- 应用修复
- 重新运行失败的测试
如果选择“创建待办事项”：
- 创建
```
{id}-pending-p1-browser-test-{description}.md
```
  文件
- 继续测试
如果选择“跳过”：
- 记录为已跳过
- 继续测试

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

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

Route	Status	Notes
`/users`	Pass
`/settings`	Pass
`/dashboard`	Fail	Console error: [msg]
`/checkout`	Skip	Requires 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 specific PR

测试特定PR

/test-browser 847

Test specific branch

测试特定分支

/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

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