Midscene.js 调试工具套件：Playground与Chrome扩展实战指南
项目地址: https://gitcode.com/GitHub_Trending/mid/midscene 你是否还在为前端自动化脚本调试而烦恼？是否需要一个直观的界面来监控AI浏览器操作？本文将带你掌握Midscene.js调试工具套件的核心使用方法，通过Playground与Chrome扩展的实战操作，解决自动化脚本开发中的实时监控、会话管理和录制回放等关键问题。读完本文，你将能够快速搭建调试环境，高效管理自动化测试用例，并掌握高级调试技巧。
工具套件概述
Midscene.js调试工具套件包含两个核心组件：Playground与Chrome扩展。Playground提供了一个基于Web的通用测试环境，支持实时服务器状态监控和会话历史持久化；Chrome扩展则集成了Bridge模式和录制功能，可直接在浏览器环境中捕获和生成自动化脚本。
两者功能对比：
| 功能 | Playground | Chrome扩展 |
|---|---|---|
| 执行模式 | 远程执行 | 本地执行 |
| UI风格 | 聊天界面 | 弹出窗口+侧边栏 |
| 历史记录 | localStorage持久化 | 会话级存储 |
| 目标对象 | 远程设备/浏览器 | 当前标签页 |
| 核心功能 | 实时截图、命令发送 | 操作录制、脚本生成 |
架构设计
Playground采用客户端-服务器架构，通过UniversalPlayground组件实现跨设备兼容，核心源码位于apps/playground/src/App.tsx。Chrome扩展则利用Chrome的扩展API实现内容脚本注入和页面控制，主要功能模块在apps/chrome-extension/src/extension/目录下。
Playground实战指南
环境搭建
- 启动服务器
npx @midscene/playground
服务器默认在http://localhost:8080启动，提供WebSocket连接支持实时通信。
- 运行Playground客户端
# 安装依赖
npm install
# 启动开发服务器
npm run dev
访问http://localhost:3000即可打开Playground界面，项目配置文件位于apps/playground/rsbuild.config.ts。
核心功能使用
实时截图监控
Playground的ScreenshotViewer组件提供设备屏幕实时预览，支持自动轮询(5秒间隔)和手动刷新。核心实现位于apps/playground/src/components/screenshot-viewer/index.tsx，主要功能包括：
- 服务器连接状态检测
- 截图数据格式验证
- 错误处理与用户提示
- 时间戳格式化显示
组件界面包含设备名称、最后更新时间和刷新按钮，当服务器离线时会显示占位提示。
会话管理
Playground使用localStorage持久化会话历史，所有交互记录会自动保存。在开发过程中，可通过修改apps/playground/src/App.tsx中的localStorageProvider配置调整存储策略。
高级配置
修改服务器连接地址：
// 在App.tsx中修改
const playgroundSDK = new PlaygroundSDK({
serverUrl: 'http://your-custom-server:port'
});
Chrome扩展使用教程
安装与配置
开发模式安装
- 构建扩展：
cd apps/chrome-extension
pnpm run build
- 加载扩展：
- 打开Chrome浏览器，访问
chrome://extensions/ - 启用"开发者模式"
- 点击"加载已解压的扩展程序"，选择
apps/chrome-extension/dist目录
- 打开Chrome浏览器，访问
扩展目录结构：
chrome-extension/
├── dist/ # 构建输出目录
├── src/ # 源代码
│ ├── extension/ # 扩展核心组件
│ │ ├── bridge/ # Bridge模式UI
│ │ ├── recorder/ # 录制功能模块
│ │ └── popup/ # 弹出窗口组件
└── static/ # 静态资源
└── manifest.json # 扩展配置
录制与回放功能
操作录制
Chrome扩展的录制功能由RecordList组件实现，位于apps/chrome-extension/src/extension/recorder/components/RecordList.tsx。使用步骤：
- 点击扩展图标打开弹出窗口
- 点击"New Recording"按钮创建新会话
- 在当前页面进行操作，扩展会自动捕获用户交互
脚本生成
录制完成后，可通过"导出"按钮生成多种格式的自动化脚本：
- YAML格式：适用于Midscene.js运行时
- Playwright格式：可直接用于Playwright测试
生成逻辑在apps/chrome-extension/src/extension/recorder/generators/目录下，支持自定义模板扩展。
Bridge模式
Bridge模式允许通过本地终端控制浏览器，实现脚本与手动操作的混合执行。启用方法：
- 在扩展弹出窗口中点击"Bridge Mode"
- 在终端中运行：
midscene bridge
Bridge模式核心实现位于apps/chrome-extension/src/extension/bridge/index.tsx，通过WebSocket与本地终端建立安全连接。
常见问题解决
Playground连接问题
- 服务器未启动：检查终端是否有
@midscene/playground进程运行 - CORS错误：修改服务器配置允许跨域，参考apps/playground/demo/server.ts中的CORS设置
- 截图加载失败：查看浏览器控制台网络请求，确认
/screenshot接口是否返回正确的base64数据
Chrome扩展权限问题
- 内容脚本注入失败：检查static/manifest.json中的权限配置
- 录制无响应：确认扩展已在当前页面激活，可通过扩展管理页面的"背景页"查看日志
- 脚本生成错误：检查录制的事件序列是否完整，复杂交互可能需要手动调整生成的脚本
最佳实践与进阶技巧
测试用例管理
推荐使用Chrome扩展的会话管理功能组织测试用例，每个功能模块创建独立会话：
- 命名规范：
[功能]-[场景]-[版本]，如"登录-正常流程-v1" - 描述填写：记录测试环境、前置条件和预期结果
- 定期导出：重要用例导出为YAML文件保存，路径建议放在项目的
tests/目录下
调试技巧
-
Playground调试：
- 使用React DevTools检查组件状态
- 网络面板监控WebSocket帧
- 修改ScreenshotViewer.tsx调整轮询间隔
-
扩展调试：
- 弹出窗口调试：右键点击弹出界面选择"检查"
- 背景页调试：扩展管理页面点击"service worker"链接
- 内容脚本调试：在页面开发者工具的"Sources"面板中找到"Content scripts"
总结与展望
Midscene.js调试工具套件通过Playground和Chrome扩展的组合，解决了AI浏览器操作的可视化调试难题。Playground的远程监控能力适合多设备测试场景，Chrome扩展的录制功能则极大简化了脚本生成流程。
未来版本将增强以下功能：
- AI辅助的脚本优化建议
- 多设备同步录制
- 测试报告生成与导出
掌握这些工具将显著提升前端自动化测试的开发效率，建议结合项目的官方文档深入学习更多高级特性。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
