browser-recording

浏览器录制技能

使用 Playwright 录制浏览器会话，为教程和文档创建 Web UI 交互视频。

适用场景

• 使用 Playwright 录制浏览器会话
• 创建 Web 应用演示录像

不适用场景

• 仅限终端的工作流——改用 scry:vhs-recording
• 静态截图——使用标准截图工具

概述

此技能使用 Playwright 内置的视频录制功能捕获浏览器交互。工作流如下：

1. 验证 Playwright 是否已安装
2. 执行启用了视频录制的 Playwright 规格文件
3. 获取录制的视频（WebM 格式）
4. 使用 gif-generation 技能转换为 GIF

💡 注意：Claude Code 2.0.72+ 内置了用于交互式浏览器控制的原生 Chrome 集成。此技能（Playwright）适用于自动化录制工作流、CI/CD 和跨浏览器支持。如需进行交互式调试和实时测试，可考虑使用原生 Chrome 集成。两种方式相辅相成——先通过 Chrome 交互式开发，再使用 Playwright 规格文件实现自动化。

必需的 TodoWrite 项

调用此技能时，请创建以下待办事项：

- [ ] Validate Playwright is installed and configured
- [ ] Check spec file exists at specified path
- [ ] Execute Playwright spec with video recording
- [ ] Locate and verify video output
- [ ] Convert video to GIF using gif-generation skill

验证：运行带有 --help 标志的命令，以确认其可用性。

流程

步骤 1：验证 Playwright 是否已安装

检查 Playwright 是否可用：

npx playwright --version

验证：运行带有 --help 标志的命令，以确认其可用性。

如果尚未安装，用户应运行：

npm install -D @playwright/test
npx playwright install chromium

验证：运行 pytest -v，确认测试通过。

步骤 2：检查规格文件

确认 Playwright 规格文件存在。规格文件应：

• 位于 specs/ 或 tests/ 目录中
• 扩展名为 .spec.ts 或 .spec.js
• 包含视频配置（参见 spec-execution 模块）

步骤 3：执行录制

启用视频功能运行规格文件：

npx playwright test <spec-file> --config=playwright.config.ts

验证：运行 pytest -v，确认测试通过。

配置必须启用视频录制。有关配置详情，请参阅 spec-execution 模块。

步骤 4：转换为 GIF

录制完成后，使用 gif-generation 技能将 WebM 视频转换为经过优化的 GIF：

**Verification:** Run the command with `--help` flag to verify availability.
Invoke scry:gif-generation with:
- input: <path-to-webm>
- output: <desired-gif-path>
- fps: 10 (recommended for tutorials)
- width: 800 (adjust based on content)

验证：运行带有 --help 标志的命令，以确认其可用性。

Playwright 规格文件示例

import { test, expect } from '@playwright/test';

test('demo workflow', async ({ page }) => {
  // Navigate to the application
  await page.goto('http://localhost:3000');

  // Wait for page to be ready
  await page.waitForLoadState('networkidle');

  // Perform demo actions
  await page.click('button[data-testid="start"]');
  await page.waitForTimeout(500); // Allow animation to complete

  await page.fill('input[name="query"]', 'example search');
  await page.waitForTimeout(300);

  await page.click('button[type="submit"]');
  await page.waitForSelector('.results');

  // Final pause to show results
  await page.waitForTimeout(1000);
});

验证：运行 pytest -v，确认测试通过。

Playwright 配置

创建或更新 playwright.config.ts：

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    video: {
      mode: 'on',
      size: { width: 1280, height: 720 }
    },
    viewport: { width: 1280, height: 720 },
    launchOptions: {
      slowMo: 100 // Slow down actions for visibility
    }
  },
  outputDir: './test-results',
});

验证：运行 pytest -v，确认测试通过。

退出条件

• Playwright 规格文件执行成功（退出代码为 0）
• 输出目录中存在视频文件
• 视频文件大小不为零
• GIF 转换已完成（如有请求）

错误处理

错误	解决方案
未安装 Playwright	运行 npm install -D @playwright/test
未安装浏览器	运行 npx playwright install chromium
找不到规格文件	检查路径和文件扩展名
未创建视频	检查 Playwright 配置是否已启用视频
视频文件为空	确认规格文件中的操作在测试结束前已完成

输出位置

默认输出路径：

• 视频：./test-results/<test-name>/video.webm
• 截图：./test-results/<test-name>/screenshot.png

模块参考

• 详细的 Playwright 执行选项请参阅 modules/spec-execution.md
• 视频格式和画质设置请参阅 modules/video-capture.md

另请参阅

• scry:gif-generation：将视频转换为经过优化的 GIF