# 屏幕截图与媒体

> **适用场景**：捕获页面状态的视觉证据——截图用于验证、视频录制用于演示或调试、PDF 导出用于文档、视口调整用于响应式测试。
> **前置条件**：[core-commands.md](core-commands.md) 了解基本 CLI 用法

## 快速参考

```bash
# 屏幕截图
playwright-cli screenshot                         # 全页截图
playwright-cli screenshot e5                      # 元素截图
playwright-cli screenshot --filename=checkout.png  # 自定义文件名

# PDF
playwright-cli pdf --filename=report.pdf           # 将页面保存为 PDF

# 视频
playwright-cli video-start                         # 开始录制
playwright-cli video-stop demo.webm                # 停止并保存

# 视口
playwright-cli resize 1920 1080                    # 桌面端
playwright-cli resize 375 812                      # 移动端
```

## 屏幕截图

### 页面截图

捕获当前可见视口：

```bash
# 自动生成文件名
playwright-cli screenshot

# 自定义文件名
playwright-cli screenshot --filename=homepage.png
playwright-cli screenshot --filename=screenshots/checkout-step3.png
```

### 元素截图

仅捕获特定元素——适用于组件级别的验证：

```bash
# 按引用截取单个元素
playwright-cli snapshot          # 先获取引用
playwright-cli screenshot e5     # 仅捕获元素 e5

# 自定义文件名
playwright-cli screenshot e5 --filename=product-card.png
```

### 全页截图

捕获整个可滚动页面，而不仅仅是当前视口：

```bash
playwright-cli run-code "async page => {
  await page.screenshot({ path: 'full-page.png', fullPage: true });
  return '已保存全页截图';
}"
```

### 带选项的截图

使用 `run-code` 实现高级截图选项：

```bash
# 全页加质量设置（JPEG）
playwright-cli run-code "async page => {
  await page.screenshot({
    path: 'optimized.jpg',
    type: 'jpeg',
    quality: 80,
    fullPage: true
  });
}"

# 裁剪到指定区域
playwright-cli run-code "async page => {
  await page.screenshot({
    path: 'header-region.png',
    clip: { x: 0, y: 0, width: 1280, height: 200 }
  });
}"

# 透明背景（适用于带透明度的元素）
playwright-cli run-code "async page => {
  await page.screenshot({
    path: 'transparent.png',
    omitBackground: true
  });
}"

# 带遮罩的截图（隐藏动态内容）
playwright-cli run-code "async page => {
  await page.screenshot({
    path: 'masked.png',
    mask: [
      page.locator('.timestamp'),
      page.locator('.user-avatar'),
      page.locator('.ad-banner')
    ]
  });
}"

# 截图前禁用动画
playwright-cli run-code "async page => {
  await page.evaluate(() => {
    document.querySelectorAll('*').forEach(el => {
      el.style.animation = 'none';
      el.style.transition = 'none';
    });
  });
  await page.screenshot({ path: 'no-animations.png' });
}"
```

### 带选项的元素截图

```bash
playwright-cli run-code "async page => {
  const element = page.getByTestId('pricing-card');
  await element.screenshot({
    path: 'pricing-card.png',
    omitBackground: true
  });
}"
```

## 响应式截图

捕获页面在不同视口尺寸下的表现：

```bash
# 桌面端（1920x1080）
playwright-cli resize 1920 1080
playwright-cli screenshot --filename=desktop.png

# 笔记本电脑（1366x768）
playwright-cli resize 1366 768
playwright-cli screenshot --filename=laptop.png

# 平板横屏（1024x768）
playwright-cli resize 1024 768
playwright-cli screenshot --filename=tablet-landscape.png

# 平板竖屏（768x1024）
playwright-cli resize 768 1024
playwright-cli screenshot --filename=tablet-portrait.png

# 移动端（375x812 — iPhone X）
playwright-cli resize 375 812
playwright-cli screenshot --filename=mobile.png

# 小屏移动端（320x568 — iPhone SE）
playwright-cli resize 320 568
playwright-cli screenshot --filename=mobile-small.png
```

### 自动化响应式截图

```bash
playwright-cli run-code "async page => {
  const viewports = [
    { name: 'desktop', width: 1920, height: 1080 },
    { name: 'laptop', width: 1366, height: 768 },
    { name: 'tablet', width: 768, height: 1024 },
    { name: 'mobile', width: 375, height: 812 },
    { name: 'mobile-sm', width: 320, height: 568 }
  ];

  for (const vp of viewports) {
    await page.setViewportSize({ width: vp.width, height: vp.height });
    await page.waitForTimeout(500);  // 等待布局稳定
    await page.screenshot({ path: \`responsive-\${vp.name}.png\` });
  }
  return '已捕获 ' + viewports.length + ' 张响应式截图';
}"
```

## PDF 导出

从网页生成 PDF 文档——适用于报告、发票和文档。

```bash
# 基础 PDF
playwright-cli pdf --filename=page.pdf
```

### 高级 PDF 选项

```bash
# 带自定义选项的 PDF
playwright-cli run-code "async page => {
  await page.pdf({
    path: 'report.pdf',
    format: 'A4',
    printBackground: true,
    margin: { top: '1cm', right: '1cm', bottom: '1cm', left: '1cm' }
  });
  return 'PDF 已保存';
}"

# Letter 格式加页眉/页脚
playwright-cli run-code "async page => {
  await page.pdf({
    path: 'document.pdf',
    format: 'Letter',
    printBackground: true,
    displayHeaderFooter: true,
    headerTemplate: '<div style=\"font-size:10px; text-align:center; width:100%;\">Company Report</div>',
    footerTemplate: '<div style=\"font-size:10px; text-align:center; width:100%;\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div>',
    margin: { top: '2cm', bottom: '2cm', left: '1cm', right: '1cm' }
  });
}"

# 横向 PDF
playwright-cli run-code "async page => {
  await page.pdf({
    path: 'landscape.pdf',
    landscape: true,
    format: 'A4',
    printBackground: true
  });
}"

# 仅指定页面
playwright-cli run-code "async page => {
  await page.pdf({
    path: 'partial.pdf',
    pageRanges: '1-3',
    format: 'A4'
  });
}"
```

**注意**：PDF 生成仅适用于 Chromium 内核浏览器，不支持 Firefox 或 WebKit。

### 打印样式预览

在生成 PDF 之前，切换到打印媒体模式查看打印布局：

```bash
playwright-cli run-code "async page => {
  await page.emulateMedia({ media: 'print' });
}"
playwright-cli screenshot --filename=print-preview.png
playwright-cli pdf --filename=output.pdf
```

## 视频录制

将浏览器会话录制为 WebM 视频文件。

### 基础录制

```bash
# 开始录制
playwright-cli video-start

# 执行操作（所有操作均被记录）
playwright-cli open https://example.com
playwright-cli snapshot
playwright-cli click e1
playwright-cli fill e2 "test input"
playwright-cli click e5

# 停止并保存
playwright-cli video-stop demo.webm
```

### 带描述性名称的录制

```bash
playwright-cli video-start
# ... 登录流程 ...
playwright-cli video-stop recordings/login-flow-2024-01-15.webm

playwright-cli video-start
# ... 结算流程 ...
playwright-cli video-stop recordings/checkout-happy-path.webm
```

### 使用场景

| 场景           | 优势                         |
| -------------- | ---------------------------- |
| Bug 复现       | 向开发者分享精确的操作步骤   |
| 演示制作       | 向利益相关者展示功能流程     |
| 文档编写       | 录制 UI 操作指南             |
| QA 证据        | 证明测试场景已执行完成       |
| 调试           | 逐帧观察发生的情况           |

## 视口管理

控制浏览器视口以进行响应式测试：

```bash
# 常见桌面尺寸
playwright-cli resize 1920 1080    # 全高清
playwright-cli resize 1440 900     # MacBook Pro 15"
playwright-cli resize 1366 768     # 常见笔记本
playwright-cli resize 1280 720     # 高清

# 平板尺寸
playwright-cli resize 1024 768     # iPad 横屏
playwright-cli resize 768 1024     # iPad 竖屏
playwright-cli resize 834 1194     # iPad Pro 11"

# 移动端尺寸
playwright-cli resize 430 932      # iPhone 14 Pro Max
playwright-cli resize 390 844      # iPhone 14
playwright-cli resize 375 812      # iPhone X/11/12/13
playwright-cli resize 360 800      # Galaxy S21
playwright-cli resize 320 568      # iPhone SE
```

## 常见模式

### 前后对比

```bash
# 操作前
playwright-cli screenshot --filename=before.png
playwright-cli click e5
# 操作后
playwright-cli screenshot --filename=after.png
```

### 完整文档套件

```bash
playwright-cli open https://app.example.com

# 登录页面
playwright-cli screenshot --filename=docs/01-login.png

# 填写并提交
playwright-cli fill e1 "demo@example.com"
playwright-cli fill e2 "demo-password"
playwright-cli screenshot --filename=docs/02-login-filled.png

playwright-cli click e3
playwright-cli screenshot --filename=docs/03-dashboard.png

# 导航到设置
playwright-cli goto https://app.example.com/settings
playwright-cli screenshot --filename=docs/04-settings.png

# 生成文档页面的 PDF
playwright-cli goto https://app.example.com/docs
playwright-cli pdf --filename=docs/user-guide.pdf
```

### 深色模式与浅色模式截图

```bash
playwright-cli open https://example.com

# 浅色模式
playwright-cli run-code "async page => { await page.emulateMedia({ colorScheme: 'light' }); }"
playwright-cli screenshot --filename=light-mode.png

# 深色模式
playwright-cli run-code "async page => { await page.emulateMedia({ colorScheme: 'dark' }); }"
playwright-cli screenshot --filename=dark-mode.png
```

### 跨浏览器截图对比

```bash
#!/bin/bash
URL="https://example.com"

for browser in chrome firefox webkit; do
  playwright-cli -s=$browser open $URL --browser=$browser
  playwright-cli -s=$browser screenshot --filename="comparison-$browser.png"
done

playwright-cli close-all
```

## 小贴士

- **截图前务必先设置视口**——先 `resize` 再 `screenshot`，确保尺寸一致
- **使用描述性文件名**——`checkout-step3-error.png` 优于 `screenshot-1.png`
- **先创建输出目录**——使用子目录路径前先 `mkdir -p screenshots/`
- **长内容使用全页截图**——通过 `run-code` 使用 `fullPage: true` 截取可滚动页面
- **遮罩动态内容**——隐藏时间戳、头像和广告，获得稳定的截图
- **生成 PDF 前先切换到打印媒体**——使用 `emulateMedia({ media: 'print' })` 预览 PDF 效果
- **视频录制有额外开销**——仅在需要时录制；调试时使用 Tracing 更轻量