skillhub-147-playwright-skill/playwright-cli/screenshots-and-media.md

屏幕截图与媒体

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

快速参考

# 屏幕截图
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                      # 移动端

屏幕截图

页面截图

捕获当前可见视口：

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

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

元素截图

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

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

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

全页截图

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

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

带选项的截图

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

# 全页加质量设置（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' });
}"

带选项的元素截图

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

响应式截图

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

# 桌面端（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

自动化响应式截图

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 文档——适用于报告、发票和文档。

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

高级 PDF 选项

# 带自定义选项的 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 之前，切换到打印媒体模式查看打印布局：

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 视频文件。

基础录制

# 开始录制
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

带描述性名称的录制

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 证据	证明测试场景已执行完成
调试	逐帧观察发生的情况

视口管理

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

# 常见桌面尺寸
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

常见模式

前后对比

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

完整文档套件

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

深色模式与浅色模式截图

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

跨浏览器截图对比

#!/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 更轻量