内容
浏览器烟雾测试
MCP 浏览器烟雾测试适用于 [OpenCode](https://opencode.ai) — 基于 Playwright 的浏览器自动化 UI 测试。直接从 OpenCode 运行网页应用的烟，支持 24 种工具 前置条件
| 版本 |
|-------------|---------|
| Node.js | >= 18 |
| >= 3.8 |
| OpenCode | 已安装 |
快速安装
```bash
n-smoke init
```
命令行交互：
```
请选择安装位置：
[1] 全局 —所有项目 (~/.config/opencode)
[2] 本 仅适用于当前项目 (./opencode.json)
[ 取消
请选择 [1/2/3]：
```
过程：
1. 设置 Python 虚拟环境
2. 安装依赖项 (`fastplaywright`, ``, `Pillow`)
3. 安装 Chromium 浏览器
4. 配置 `opencode.json` + 技能文件
安装完成后，请重启 OpenCode。
### 初始化选项
| 命令 |
|---------|-------------|
| `npx browser-smoke init 交互式（询问全局/本地） |
| `npx browser-smoke init --global` | 全局，跳过提示 |
| `npx browser-smoke init --local` | 本地，跳过提示 |
| `npx browser-smoke init --print` | 预览配置而不安装 |
### 手动配置
如果 `init` 命令无法使用，请手动添加到 `opencode.json`：
```json
{
"mcp": {
"browser-smoke": {
"type": "local",
"command": [".browser-smoke/.venv/bin/python3", "-m", "server"],
"cwd": ".browser-smoke/mcp"
}
}
}
```
##列表（24 种 MCP 工具）
### 导航与页面
| 工具 | 描述 |
|------|-------------|
| `browser_open(url, headless?)` |。返回标题 + 状态码 + 截图 |
| `_tab(url)` | 打开新标签页，聚焦到新标签页 |
| `browser_get_tabs()` | 获取所有标签页（标题，URL，活动状态） |
| `browser_close()` | 关闭浏览器会话 |
| `browser_scroll(x?, y?)` | 滚动页面（默认：向下 200px） |
### DOM 交互
| 工具 | 描述 |
|------|-------------|
| `browser_extract_dom()` | 获取所有交互元素（按钮，输入框，链接）+ CSS 选择器 |
| `browser_click(selector)` | 根据 CSS 选择器点击元素 |
| `browser_type(selector, text)` | 在输入框中输入文本 |
| `browser_type_guess(selector, input_type?)` | 自动填充输入框（文本/邮箱/密码/搜索/数字） |
### 截图与视觉
| 工具 | 描述 |
|------|-------------|
| `browser_screenshot()` | 截图当前页面 |
| `browser_screenshot_diff(name, threshold?)` | 截图并与基准线对比。默认阈值 0.01（1%） |
| `browser_highlight(selector, color?, duration?)` | 高亮元素并添加轮廓 |
### JavaScript 与网络
| 工具 | 描述 |
|------|-------------|
| `browser_execute(js_code)` | 在页面上下文中执行 JavaScript 代码 |
| `browser_inject_script(script, url_pattern?)` | 在页面加载前注入 JavaScript 代码（模拟 API，polyfills） |
| `browser_network_capture(mode, patterns?)` | 拦截网络请求（模式：启动/停止/获取） |
| `browser_block_resources(patterns)` | 根据通配符模式阻止资源（\*.jpg，\*.png，analytics） |
### 控制台与错误
| 工具 | 描述 |
|------|-------------|
| `browser_console()` | 获取捕获的控制台日志 |
| `browser_errors()` | 获取捕获的 JavaScript 运行时错误 |
### Cookie 与存储
| 工具 | 描述 |
|------|-------------|
| `browser_get_cookies()` | 获取所有 Cookie |
| `browser_set_cookie(name, value, domain?, path?)` | 设置 Cookie |
| `browser_clear_cookies()` | 清除所有 Cookie |
| `browser_storage(mode, storage?, key?, value?)` | 访问本地存储/会话存储（全部/获取/设置/清除） |
### 报告
| 工具 | 描述 |
|------|-------------|
| `browser_report(results_json)` | 生成烟雾测试报告 Markdown |
### 后台
| 工具 | 描述 |
|------|-------------|
| `browser_offscreen(action, url?, js?)` | 用于后台处理的隐藏页面（打开/执行/关闭） |
## 使用指南
### 基本烟雾测试
1. 在 OpenCode 中加载 `browser-smoke` 技能
2. 测试流程：
```
browser_open(url="http://localhost:5173")
browser_extract_dom()
browser_click(selector="button:has-text('登录')")
browser_type(selector="input[type='email']", text="test@test.com")
browser_type(selector="input[type='password']", text="Test1234!")
browser_click(selector="button:has-text('提交')")
browser_screenshot()
browser_console()
browser_errors()
browser_report(results_json)
browser_close()
```
捕获
```python
browser_network_capture(mode="start", patterns="*.api.*,*.json")
# 进行交互...
browser_network_capture(mode="get") # 查看请求/响应
browser_network_capture(mode="stop")
```
### 脚本注入
```python
browser_inject_script(script="window.__TEST_MODE__=true")
browser_open(url="http://localhost:5173")
browser_execute(js_code="window.__TEST_MODE__") # → true
```
### 视觉回归
```python
browser_open(url="http://localhost:5173")
browser_screenshot_diff(name="首页") # 基准线（首次运行）
# 代码更改后...
browser_screenshot_diff(name="首页") # 与基准线对比
```
## 技能集成
安装后，`browser-smoke` 技能会自动注册。在 OpenCode 中：
```
skill browser-smoke
```
该技能提供完整的烟雾测试方法论和故障分析循环。
## 故障排除
| 问题 | 解决方案 |
|---------|--------|
| `browser_screenshot_diff` 失败 | 确保 `mcp/tools/browser.py` 有权限访问 artifacts 目录 |
| Chromium 错误 | 重新运行 `playwright install chromium` |
| 连接被拒绝 | 确保目标应用正在运行（`npm run dev` 等） |
| 未找到 Python | 运行 `python3 --version`，如果报错请先安装 Python |
## 开发
```bash
git clone https://github.com/sukirman1901/browser-sm
