playwright-record

Playwright Record

基于WebSocket和Playwright的自动化录制工具，通过WebSocket服务允许用户远程控制Playwright进行浏览器操作录制，并生成自动化测试脚本。

功能特点

• 启动本地WebSocket服务器（默认端口4362）
• 通过WebSocket接收指令控制Playwright
• 支持启动浏览器，录制用户操作
• 生成对应的自动化测试脚本
• 通过WebSocket将生成的脚本返回给客户端
• 支持生成和保存Playwright trace文件，便于调试和回放
• 支持通过PM2进行进程管理（启动、停止、重启、监控）

项目结构

已简化的项目结构如下：

playwright-record/
├── bin/
│   └── index.js            # CLI入口文件
├── src/
│   ├── core/
│   │   ├── executor.ts     # 执行器核心逻辑
│   │   ├── recorder.ts     # 录制器核心逻辑
│   │   └── server.ts       # WebSocket服务器核心逻辑
│   ├── commands/
│   ├── codegen/
│   ├── utils/
│   └── index.ts            # 主程序入口
├── examples/
│   └── client.html         # Web客户端示例
├── recordings/             # 录制的trace文件保存位置
├── package.json            # 项目配置
├── tsconfig.json           # TypeScript配置
└── README.md               # 项目说明

安装

# 安装依赖
npm install

# 构建项目
npm run build

# 全局安装（可选）
npm install -g .

使用方法

命令行使用

直接启动服务

# 启动服务（默认端口4362）
npx playwright-record serve

# 指定端口启动
npx playwright-record serve --port 8080

# 向后兼容的方式启动
npx playwright-record --port 8080

# 如果全局安装了，可以直接使用
playwright-record serve

使用PM2管理服务

# 使用PM2启动服务（默认端口4362）
npx playwright-record start

# 指定端口启动
npx playwright-record start --port 8080

# 指定进程名称
npx playwright-record start --name my-recorder

# 启用文件监视模式（文件变化时自动重启）
npx playwright-record start --watch

# 停止服务
npx playwright-record stop

# 停止指定名称的服务
npx playwright-record stop --name my-recorder

# 重启服务
npx playwright-record restart

# 列出所有录制服务进程（包括已停止的进程）
npx playwright-record list

# 从PM2中完全删除进程
npx playwright-record delete

# 从PM2中删除指定名称的进程
npx playwright-record delete --name my-recorder

# 查看服务日志
npx playwright-record logs

# 查看指定服务的日志
npx playwright-record logs --name my-recorder

# 查看更多行数的日志
npx playwright-record logs --lines 100

WebSocket 客户端

项目提供了一个简单的Web客户端示例，位于examples/client.html，可以在浏览器中打开使用。

也可以通过WebSocket API直接与服务交互：

// 客户端连接示例
const ws = new WebSocket('ws://localhost:4362');

// 监听消息
ws.onmessage = (event) => {
  const message = JSON.parse(event.data);

  if (message.type === 'response') {
    console.log('收到响应:', message.data);
    // 检查是否有trace文件路径
    if (message.command === 'stop' && message.data.tracePath) {
      console.log('Trace文件已保存:', message.data.tracePath);
    }
  } else if (message.type === 'notification') {
    console.log('收到通知:', message.message);
  } else if (message.type === 'code_update') {
    console.log('代码更新:', message.data);
  } else if (message.type === 'error') {
    console.error('错误:', message.message);
  }
};

// 开始录制 (可以选择是否保存trace文件)
function startRecording(url, saveTraces = true) {
  ws.send(JSON.stringify({
    command: 'start',
    params: {
      url: url || 'https://example.com',
      headless: false,
      viewport: { width: 1280, height: 720 },
      saveTraces: saveTraces
    }
  }));
}

// 停止录制
function stopRecording() {
  ws.send(JSON.stringify({
    command: 'stop'
  }));
}

// 获取状态
function getStatus() {
  ws.send(JSON.stringify({
    command: 'status'
  }));
}

Trace文件使用

录制过程中会自动保存trace文件到recordings目录。停止录制后，可以使用以下命令查看trace文件：

npx playwright show-trace <trace文件路径>

Trace文件包含了录制过程中的页面快照、网络请求、控制台日志等信息，可以帮助分析和调试自动化脚本。

支持的命令

WebSocket命令

命令	描述	参数
start	开始录制	url: 要录制的URL headless: 是否无头模式 viewport: 视口大小 saveTraces: 是否保存trace文件
stop	停止录制	无
status	获取录制状态	无

CLI命令

命令	描述	选项
serve	直接启动服务	-p, --port: 指定端口
start	使用PM2启动服务	-p, --port: 指定端口 -n, --name: 指定进程名称 -w, --watch: 启用文件监视模式
stop	停止服务	-n, --name: 指定进程名称
restart	重启服务	-n, --name: 指定进程名称
list	列出所有服务进程	无
delete	从PM2中删除进程	-n, --name: 指定进程名称
logs	查看服务日志	-n, --name: 指定进程名称 -l, --lines: 显示的日志行数

PM2进程管理

本工具集成了PM2进程管理功能，可以方便地管理录制服务的生命周期。PM2是一个流行的Node.js应用进程管理器，提供以下优势：

• 守护进程运行，确保服务持续可用
• 自动重启，当服务崩溃时自动恢复
• 日志管理，集中存储和查看日志
• 多实例管理，可以运行多个不同配置的服务实例

服务日志默认保存在用户主目录的.playwright-record/logs文件夹下。

PM2进程状态说明

在使用PM2管理进程时，需要了解以下几点：

• 停止 vs 删除：

  • stop命令只是停止进程运行，但进程仍然保留在PM2的管理列表中
  • delete命令会从PM2的管理列表中完全删除进程

• 进程状态：

  • 运行中：进程正在运行
  • 已停止：进程已停止，但仍保留在PM2列表中，可以重启
  • 其他状态：如错误、正在启动等

• 常见操作流程：

  • 启动服务：playwright-record start
  • 临时停止：playwright-record stop（可以稍后重启）
  • 重新启动：playwright-record restart
  • 查看状态：playwright-record list
  • 完全删除：playwright-record delete（从PM2中移除）

当执行stop命令后，list命令仍然会显示该进程，但状态会显示为已停止。如果要完全移除进程，请使用delete命令。

开发

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 使用 Biome.js 格式化代码
npm run format

# 使用 Biome.js 进行代码检查
npm run lint

# 使用 Biome.js 检查并自动修复问题
npm run check

代码规范

本项目使用 Biome.js 作为代码格式化和 lint 工具，确保代码风格统一和质量。相关配置位于项目根目录的 biome.json 文件中。

许可证

MIT