ce-test-browser

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Browser Test Skill

浏览器测试技能

Run end-to-end browser tests on pages affected by a PR or branch changes using the

agent-browser

CLI.

使用

agent-browser

CLI针对PR或分支变更影响的页面运行端到端浏览器测试。

Use

agent-browser

Only For Browser Automation

仅使用

agent-browser

进行浏览器自动化

This workflow uses the

agent-browser

CLI exclusively. Do not use any alternative browser automation system, browser MCP integration, or built-in browser-control tool. If the platform offers multiple ways to control a browser, always choose

agent-browser

Use

agent-browser

for: opening pages, clicking elements, filling forms, taking screenshots, and scraping rendered content.

Platform-specific hints:

In Claude Code, do not use Chrome MCP tools (
```
mcp__claude-in-chrome__*
```
).
In Codex, do not substitute unrelated browsing tools.

此工作流仅使用

agent-browser

CLI。请勿使用任何替代浏览器自动化系统、浏览器MCP集成或内置浏览器控制工具。如果平台提供多种控制浏览器的方式，请始终选择

agent-browser

。

使用

agent-browser

完成以下操作：打开页面、点击元素、填写表单、截取屏幕截图以及抓取渲染内容。

平台特定提示：

在Claude Code中，请勿使用Chrome MCP工具（
```
mcp__claude-in-chrome__*
```
）。
在Codex中，请勿替换为无关的浏览工具。

Prerequisites

前提条件

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

本地开发服务器正在运行（例如：
```
bin/dev
```
、
```
rails server
```
、
```
npm run dev
```
）
已安装
```
agent-browser
```
CLI（请参阅下方设置步骤）
包含待测试变更的Git仓库

Setup

设置

Check whether

agent-browser

is installed:

bash

command -v agent-browser >/dev/null 2>&1 && echo "Installed" || echo "NOT INSTALLED"

If not installed, inform the user: "

agent-browser

is not installed. Run

/ce-setup

to install required dependencies." Then stop — this skill cannot function without agent-browser.

检查

agent-browser

是否已安装：

bash

command -v agent-browser >/dev/null 2>&1 && echo "Installed" || echo "NOT INSTALLED"

如果未安装，请告知用户："

agent-browser

未安装。运行

/ce-setup

以安装所需依赖。" 然后停止操作——没有agent-browser，此技能无法运行。

Workflow

工作流

1. Verify Installation

1. 验证安装

Before starting, verify

agent-browser

is available:

bash

command -v agent-browser >/dev/null 2>&1 && echo "Ready" || echo "NOT INSTALLED"

If not installed, inform the user: "

agent-browser

is not installed. Run

/ce-setup

to install required dependencies." Then stop.

开始前，验证

agent-browser

是否可用：

bash

command -v agent-browser >/dev/null 2>&1 && echo "Ready" || echo "NOT INSTALLED"

如果未安装，请告知用户："

agent-browser

未安装。运行

/ce-setup

以安装所需依赖。" 然后停止操作。

2. Ask Browser Mode

2. 询问浏览器模式

Ask the user whether to run headed or headless using the platform's blocking question tool:

AskUserQuestion

in Claude Code (call

ToolSearch

with

select:AskUserQuestion

first if its schema isn't loaded),

request_user_input

in Codex,

ask_user

in Gemini,

ask_user

in Pi (requires the

pi-ask-user

extension). Fall back to presenting options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question:

Do you want to watch the browser tests run?

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 the

--headed

flag when the user selects option 1.

使用平台的阻塞式提问工具询问用户是运行有头模式还是无头模式：Claude Code中使用

AskUserQuestion

（如果未加载其架构，先调用

ToolSearch

并指定

select:AskUserQuestion

），Codex中使用

request_user_input

，Gemini中使用

ask_user

，Pi中使用

ask_user

（需要

pi-ask-user

扩展）。仅当工具集中没有阻塞式工具或调用出错时（例如Codex编辑模式），才回退到在聊天中展示选项——不要因为需要加载架构而跳过。切勿静默跳过此问题：

您是否想要查看浏览器测试的运行过程？

1. 有头模式（可查看）- 打开可见的浏览器窗口，以便您查看测试运行
2. 无头模式（更快）- 在后台运行，速度更快但不可见

保存用户的选择，当用户选择选项1时，使用

--headed

标志。

3. Determine Test Scope

3. 确定测试范围

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]

如果提供了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]

4. Map Files to Routes

4. 将文件映射到路由

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.

将变更文件映射到可测试的路由：

文件模式	路由
`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列表。

5. Detect Dev Server Port

5. 检测开发服务器端口

Determine the dev server port using this priority:

Explicit argument — if the user passed
```
--port 5000
```
, use that directly
Project instructions — check
```
AGENTS.md
```
,
```
CLAUDE.md
```
, or other instruction files for port references
package.json — check dev/start scripts for
```
--port
```
flags
Environment files — check
```
.env
```
,
```
.env.local
```
,
```
.env.development
```
for
```
PORT=
```
Default — fall back to
```
3000
```

bash

PORT="${EXPLICIT_PORT:-}"
if [ -z "$PORT" ]; then
  PORT=$(grep -Eio '(port\s*[:=]\s*|localhost:)([0-9]{4,5})' AGENTS.md 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1)
  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
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"

按照以下优先级确定开发服务器端口：

显式参数 — 如果用户传入
```
--port 5000
```
，直接使用该端口
项目说明 — 检查
```
AGENTS.md
```
、
```
CLAUDE.md
```
或其他说明文件中的端口引用
package.json — 检查dev/start脚本中的
```
--port
```
标志
环境文件 — 检查
```
.env
```
、
```
.env.local
```
、
```
.env.development
```
中的
```
PORT=
```
配置
默认值 — 回退到
```
3000
```

bash

PORT="${EXPLICIT_PORT:-}"
if [ -z "$PORT" ]; then
  PORT=$(grep -Eio '(port\s*[:=]\s*|localhost:)([0-9]{4,5})' AGENTS.md 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1)
  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
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"

6. Verify Server is Running

6. 验证服务器是否运行

bash

agent-browser open http://localhost:${PORT}
agent-browser snapshot -i

If the server is not running, inform the user:

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: run this skill again with `--port <your-port>`

Then re-run this skill.

bash

agent-browser open http://localhost:${PORT}
agent-browser snapshot -i

如果服务器未运行，请告知用户：

服务器未在端口${PORT}运行

请启动您的开发服务器：
- Rails: `bin/dev` 或 `rails server`
- Node/Next.js: `npm run dev`
- 自定义端口：重新运行此技能并添加`--port <your-port>`参数

然后重新运行此技能。

7. Test Each Affected Page

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

For each affected route:

Navigate and capture snapshot:

bash

agent-browser open "http://localhost:${PORT}/[route]"
agent-browser snapshot -i

For headed mode:

bash

agent-browser --headed open "http://localhost:${PORT}/[route]"
agent-browser --headed snapshot -i

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

Test critical interactions:

bash

agent-browser click @e1
agent-browser snapshot -i

Take screenshots:

bash

agent-browser screenshot page-name.png
agent-browser screenshot --full page-name-full.png

针对每个受影响的路由：

导航并捕获快照：

bash

agent-browser open "http://localhost:${PORT}/[route]"
agent-browser snapshot -i

有头模式下：

bash

agent-browser --headed open "http://localhost:${PORT}/[route]"
agent-browser --headed snapshot -i

验证关键元素：

使用
```
agent-browser snapshot -i
```
获取带引用的交互元素
页面标题/标题存在
主要内容已渲染
无可见错误消息
表单包含预期字段

测试关键交互：

bash

agent-browser click @e1
agent-browser snapshot -i

截取屏幕截图：

bash

agent-browser screenshot page-name.png
agent-browser screenshot --full page-name-full.png

8. Human Verification (When Required)

8. 人工验证（必要时）

Pause for human input when testing touches flows that require external interaction:

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"

Ask the user (using the platform's question tool, or present numbered options and wait):

Human Verification Needed

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

Did it work correctly?
1. Yes - continue testing
2. No - describe the issue

当测试涉及需要外部交互的流程时，暂停以等待人工输入：

流程类型	询问内容
OAuth	"请使用[提供商]登录并确认功能正常"
邮件	"检查您的收件箱以获取测试邮件并确认已收到"
支付	"在沙箱模式下完成测试购买"
SMS	"验证您已收到SMS验证码"
外部API	"确认[服务]集成正常工作"

询问用户（使用平台的提问工具，或展示编号选项并等待）：

需要人工验证

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

是否正常工作？
1. 是 - 继续测试
2. 否 - 描述问题

9. Handle Failures

9. 处理失败

When a test fails:

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

Ask the user how to proceed:

Test Failed: [route]

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

How to proceed?
1. Fix now - debug and fix the failing test
2. Skip - continue testing other pages

If "Fix now": investigate, propose a fix, apply, re-run the failing test
If "Skip": log as skipped, continue

当测试失败时：

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

询问用户如何继续：

测试失败：[route]

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

如何继续？
1. 立即修复 - 调试并修复失败的测试
2. 跳过 - 继续测试其他页面

如果选择"立即修复"： 调查问题，提出修复方案，应用修复，重新运行失败的测试
如果选择"跳过"： 记录为已跳过，继续测试

10. Test Summary

10. 测试总结

After all tests complete, present a summary:

markdown

undefined

所有测试完成后，呈现总结：

markdown

undefined

Browser Test Results

浏览器测试结果

Test Scope: PR #[number] / [branch name] Server: http://localhost:${PORT}

测试范围： PR #[number] / [分支名称] 服务器： 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
```
- [问题描述]

Result: [PASS / FAIL / PARTIAL]

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

undefined

undefined

Quick Usage Examples

快速使用示例

bash

undefined

bash

undefined

Test current branch changes (auto-detects port)

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

/ce-test-browser

Test specific PR

测试特定PR

/ce-test-browser 847

Test specific branch

测试特定分支

/ce-test-browser feature/new-dashboard

Test on a specific port

在特定端口上测试

/ce-test-browser --port 5000

undefined

/ce-test-browser --port 5000

undefined

agent-browser CLI Reference

agent-browser CLI参考

Run

agent-browser --help

for all commands.

Key commands:

bash

undefined

运行

agent-browser --help

查看所有命令。

关键命令：

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> # 在可见浏览器中打开 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

ce-test-browser

Original

Translation

Browser Test Skill

浏览器测试技能

Use agent-browser Only For Browser Automation

仅使用agent-browser进行浏览器自动化

Prerequisites

前提条件

Setup

设置

Workflow

工作流

1. Verify Installation

1. 验证安装

2. Ask Browser Mode

2. 询问浏览器模式

3. Determine Test Scope

3. 确定测试范围

4. Map Files to Routes

4. 将文件映射到路由

5. Detect Dev Server Port

5. 检测开发服务器端口

6. Verify Server is Running

6. 验证服务器是否运行

7. Test Each Affected Page

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

8. Human Verification (When Required)

8. 人工验证（必要时）

9. Handle Failures

9. 处理失败

10. Test Summary

10. 测试总结

Browser Test Results

浏览器测试结果

Pages Tested: [count]

已测试页面：[数量]

Console Errors: [count]

控制台错误：[数量]

Human Verifications: [count]

人工验证：[数量]

Failures: [count]

失败项：[数量]

Result: [PASS / FAIL / PARTIAL]

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

Quick Usage Examples

快速使用示例

Test current branch changes (auto-detects port)

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

Test specific PR

测试特定PR

Test specific branch

测试特定分支

Test on a specific port

在特定端口上测试

agent-browser CLI Reference

agent-browser CLI参考

Navigation

导航

Snapshots (get element refs)

快照（获取元素引用）

Interactions (use refs from snapshot)

交互（使用快照中的引用）

Screenshots

屏幕截图

Headed mode (visible browser)

有头模式（可见浏览器）

Wait

等待

Use
`agent-browser`
Only For Browser Automation

仅使用
`agent-browser`
进行浏览器自动化