Back to Details

playwright-responsive-screenshots

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Playwright Responsive Screenshots

Playwright 响应式截图

Quick Start

快速开始

Capture screenshots across standard breakpoints in one command:
Capture responsive screenshots of https://example.com at mobile, tablet, and desktop breakpoints
This skill automates:
  • Browser window resizing to standard breakpoints
  • Layout settling wait times
  • Full-page screenshot capture
  • Organized file naming with breakpoint identifiers
  • Optional comparison report generation
通过一条命令在标准断点处捕获截图：
Capture responsive screenshots of https://example.com at mobile, tablet, and desktop breakpoints
该Skill可自动完成以下操作：
  • 将浏览器窗口调整至标准断点尺寸
  • 等待布局稳定的时长控制
  • 捕获全页截图
  • 按断点标识整理文件命名
  • 可选生成对比报告

Table of Contents

目录

  1. When to Use This Skill
  2. What This Skill Does
  3. Standard Breakpoints
  4. Instructions 4.1. Basic Screenshot Capture 4.2. Custom Breakpoints 4.3. Multiple Pages 4.4. With Comparison Report
  5. Supporting Files
  6. Expected Outcomes
  7. Requirements
  8. Red Flags to Avoid
  1. 何时使用该Skill
  2. 该Skill的功能
  3. 标准断点
  4. 使用说明 4.1. 基础截图捕获 4.2. 自定义断点 4.3. 多页面截图 4.4. 生成对比报告
  5. 支持文件
  6. 预期结果
  7. 要求
  8. 注意事项

When to Use This Skill

何时使用该Skill

Explicit Triggers:
  • "Test responsive design for [URL]"
  • "Screenshot at breakpoints"
  • "Capture mobile and desktop views of [page]"
  • "Validate responsive layout"
  • "Generate screenshots for design review"
Implicit Triggers:
  • User mentions testing across devices
  • Request for multi-device validation
  • Need to document responsive behavior
  • Visual regression testing setup
  • Design system breakpoint validation
Debugging Scenarios:
  • Layout breaks at certain viewport widths
  • Media query verification needed
  • CSS breakpoint testing
  • Responsive component validation
明确触发场景：
  • "测试[URL]的响应式设计"
  • "在断点处截图"
  • "捕获[页面]的移动端和桌面端视图"
  • "验证响应式布局"
  • "为设计评审生成截图"
隐含触发场景：
  • 用户提及跨设备测试
  • 请求多设备验证
  • 需要记录响应式表现
  • 视觉回归测试搭建
  • 设计系统断点验证
调试场景：
  • 布局在特定视口宽度下出现问题
  • 需要验证媒体查询
  • CSS断点测试
  • 响应式组件验证

What This Skill Does

该Skill的功能

This skill provides an automated workflow for capturing screenshots at multiple viewport sizes:
  1. Define breakpoints - Use standard or custom viewport dimensions
  2. Navigate to target - Open the URL in Playwright browser
  3. Resize and capture - For each breakpoint: resize window, wait for layout, screenshot
  4. Organize output - Name files with breakpoint identifiers (e.g., 
    homepage-mobile.png
    )
  5. Generate report - Optional comparison table with screenshot paths
Key Benefits:
  • Consistent viewport sizes across captures
  • Proper layout settling before screenshots
  • Organized file naming convention
  • Full-page screenshots by default
  • Reproducible test results
该Skill提供自动化工作流，用于在多个视口尺寸下捕获截图：
  1. 定义断点 - 使用标准或自定义视口尺寸
  2. 导航至目标页面 - 在Playwright浏览器中打开目标URL
  3. 调整尺寸并捕获 - 针对每个断点：调整窗口大小、等待布局稳定、捕获截图
  4. 整理输出 - 按断点标识命名文件（例如：
    homepage-mobile.png
    ）
  5. 生成报告 - 可选生成包含截图路径的对比表格
核心优势：
  • 捕获过程中保持一致的视口尺寸
  • 截图前等待布局稳定
  • 规范的文件命名规则
  • 默认捕获全页截图
  • 可复现的测试结果

Standard Breakpoints

标准断点

This skill uses industry-standard breakpoints by default:
Device CategoryWidth × HeightCommon Devices
Mobile375 × 667iPhone SE, iPhone 12/13/14
Tablet768 × 1024iPad, iPad Mini, Android tablets
Desktop1920 × 1080Standard HD desktop/laptop
Breakpoint Selection Rationale:
  • Mobile: Most common iPhone viewport (covers ~40% of mobile traffic)
  • Tablet: Standard iPad portrait orientation
  • Desktop: 1080p standard (most common desktop resolution)
When to Use Custom Breakpoints:
  • Testing specific device models
  • Validating custom media query breakpoints
  • Client-specific device requirements
  • Edge case viewport testing (ultra-wide, small tablets, etc.)
该Skill默认使用行业标准断点：
设备类别宽 × 高常见设备
移动端375 × 667iPhone SE、iPhone 12/13/14
平板端768 × 1024iPad、iPad Mini、安卓平板
桌面端1920 × 1080标准1080p桌面/笔记本电脑
断点选择依据：
  • 移动端：最常用的iPhone视口（覆盖约40%的移动流量）
  • 平板端：标准iPad竖屏方向
  • 桌面端：1080p标准分辨率（最常用的桌面分辨率）
何时使用自定义断点：
  • 测试特定设备型号
  • 验证自定义媒体查询断点
  • 客户指定的设备要求
  • 极端场景视口测试（超宽屏、小尺寸平板等）

Instructions

使用说明

4.1. Basic Screenshot Capture

4.1. 基础截图捕获

Workflow:
  1. Define target and breakpoints
    URL: https://example.com/page
Breakpoints: mobile, tablet, desktop (standard)
  2. Navigate to page
    • Use 
      browser_navigate
      to open URL
    • Verify page loads successfully
  3. For each breakpoint:
    • Resize browser window using 
      browser_resize
    • Wait for layout to settle using 
      browser_wait_for
      (1 second minimum)
    • Capture full-page screenshot using 
      browser_take_screenshot
      with 
      fullPage: true
    • Name file descriptively: 
      {page-name}-{breakpoint}.png
  4. Organize screenshots
    • Save to predictable location (e.g., 
      screenshots/
      )
    • Group by page or breakpoint as appropriate
  5. Confirm completion
    • Report number of screenshots captured
    • List file paths for user verification
Example:
User: "Capture responsive screenshots of https://myapp.dev/dashboard"

Assistant workflow:
1. browser_navigate to https://myapp.dev/dashboard
2. browser_resize(375, 667) → wait 1s → browser_take_screenshot("dashboard-mobile.png", fullPage: true)
3. browser_resize(768, 1024) → wait 1s → browser_take_screenshot("dashboard-tablet.png", fullPage: true)
4. browser_resize(1920, 1080) → wait 1s → browser_take_screenshot("dashboard-desktop.png", fullPage: true)
5. Report: "Captured 3 screenshots: dashboard-mobile.png, dashboard-tablet.png, dashboard-desktop.png"
工作流：
  1. 定义目标页面和断点
    URL: https://example.com/page
Breakpoints: mobile, tablet, desktop (standard)
  2. 导航至页面
    • 使用
      browser_navigate
      打开URL
    • 验证页面加载成功
  3. 针对每个断点：
    • 使用
      browser_resize
      调整浏览器窗口大小
    • 使用
      browser_wait_for
      等待布局稳定（至少1秒）
    • 使用
      browser_take_screenshot
      并设置
      fullPage: true
      捕获全页截图
    • 规范命名文件：
      {页面名称}-{断点标识}.png
  4. 整理截图
    • 保存至可预测的位置（例如：
      screenshots/
      ）
    • 根据页面或断点进行分组
  5. 确认完成
    • 报告捕获的截图数量
    • 列出文件路径供用户验证
示例：
用户: "Capture responsive screenshots of https://myapp.dev/dashboard"

助手工作流:
1. browser_navigate 至 https://myapp.dev/dashboard
2. browser_resize(375, 667) → 等待1秒 → browser_take_screenshot("dashboard-mobile.png", fullPage: true)
3. browser_resize(768, 1024) → 等待1秒 → browser_take_screenshot("dashboard-tablet.png", fullPage: true)
4. browser_resize(1920, 1080) → 等待1秒 → browser_take_screenshot("dashboard-desktop.png", fullPage: true)
5. 报告: "Captured 3 screenshots: dashboard-mobile.png, dashboard-tablet.png, dashboard-desktop.png"

4.2. Custom Breakpoints

4.2. 自定义断点

When user specifies custom viewport sizes:
  1. Parse breakpoint specifications
    • Accept formats: "414x896" or "414 x 896" or "width: 414, height: 896"
    • Validate dimensions are reasonable (width 200-3840, height 200-2160)
  2. Name custom breakpoints descriptively
    • Use width for identifier: "homepage-414w.png"
    • Or use user-provided labels: "homepage-iphone14pro.png"
  3. Follow same workflow
    • Navigate → Resize → Wait → Capture
    • Apply 1-second wait minimum after resize
Example:
User: "Screenshot https://app.com at 414x896 (iPhone 14 Pro) and 393x851 (Pixel 7)"

Assistant workflow:
1. browser_navigate to https://app.com
2. browser_resize(414, 896) → wait 1s → browser_take_screenshot("app-iphone14pro.png", fullPage: true)
3. browser_resize(393, 851) → wait 1s → browser_take_screenshot("app-pixel7.png", fullPage: true)
当用户指定自定义视口尺寸时：
  1. 解析断点规格
    • 支持格式："414x896" 或 "414 x 896" 或 "width: 414, height: 896"
    • 验证尺寸合理性（宽度200-3840，高度200-2160）
  2. 为自定义断点设置描述性名称
    • 使用宽度作为标识："homepage-414w.png"
    • 或使用用户提供的标签："homepage-iphone14pro.png"
  3. 遵循相同工作流
    • 导航 → 调整尺寸 → 等待 → 捕获
    • 调整尺寸后至少等待1秒
示例：
用户: "Screenshot https://app.com at 414x896 (iPhone 14 Pro) and 393x851 (Pixel 7)"

助手工作流:
1. browser_navigate 至 https://app.com
2. browser_resize(414, 896) → 等待1秒 → browser_take_screenshot("app-iphone14pro.png", fullPage: true)
3. browser_resize(393, 851) → 等待1秒 → browser_take_screenshot("app-pixel7.png", fullPage: true)

4.3. Multiple Pages

4.3. 多页面截图

For testing multiple pages at standard breakpoints:
  1. Create page list
    • Extract page names from URLs for file naming
    • Examples: "/dashboard" → "dashboard", "/settings/profile" → "settings-profile"
  2. Nested loop structure
    • Outer loop: pages
    • Inner loop: breakpoints
    • Alternative: breakpoints outer, pages inner (user preference)
  3. Naming convention
    • {page-name}-{breakpoint}.png
    • Example: 
      dashboard-mobile.png
      , 
      dashboard-tablet.png
      , 
      settings-mobile.png
  4. Optimize navigation
    • Navigate once per page (before breakpoint loop)
    • Resize/capture without re-navigating
Example:
User: "Capture responsive screenshots for /home, /products, and /about pages on https://shop.com"

Assistant workflow:
For each page in ["/home", "/products", "/about"]:
  1. browser_navigate to https://shop.com{page}
  2. For each breakpoint in [mobile, tablet, desktop]:
     - browser_resize(width, height)
     - browser_wait_for(1 second)
     - browser_take_screenshot("{page-name}-{breakpoint}.png", fullPage: true)

Result: 9 screenshots (3 pages × 3 breakpoints)
针对多页面进行标准断点测试：
  1. 创建页面列表
    • 从URL中提取页面名称用于文件命名
    • 示例："/dashboard" → "dashboard"，"/settings/profile" → "settings-profile"
  2. 嵌套循环结构
    • 外层循环：页面
    • 内层循环：断点
    • 备选方案：外层循环为断点，内层为页面（根据用户偏好）
  3. 命名规则
    • {页面名称}-{断点标识}.png
    • 示例：
      dashboard-mobile.png
      、
      dashboard-tablet.png
      、
      settings-mobile.png
  4. 优化导航流程
    • 每个页面仅导航一次（在断点循环之前）
    • 无需重新导航，直接调整尺寸/捕获截图
示例：
用户: "Capture responsive screenshots for /home, /products, and /about pages on https://shop.com"

助手工作流:
针对每个页面 ["/home", "/products", "/about"]:
  1. browser_navigate 至 https://shop.com{page}
  2. 针对每个断点 [mobile, tablet, desktop]:
     - browser_resize(width, height)
     - browser_wait_for(1 second)
     - browser_take_screenshot("{page-name}-{breakpoint}.png", fullPage: true)

结果: 9张截图（3个页面 × 3个断点）

4.4. With Comparison Report

4.4. 生成对比报告

Generate markdown report after screenshot capture:
  1. Capture screenshots (as above)
  2. Create markdown table with embedded images and metadata
  3. Save to 
    screenshots/report.md
    (or user-specified location)
  4. Include timestamp, URL, dimensions, and layout notes
See 
examples/examples.md
for full report template example.
截图捕获后生成Markdown报告：
  1. 捕获截图（操作如上）
  2. 创建包含嵌入式图片和元数据的Markdown表格
  3. 保存至
    screenshots/report.md
    （或用户指定位置）
  4. 包含时间戳、URL、尺寸和布局说明
完整报告模板示例请查看
examples/examples.md
。

Supporting Files

支持文件

references/playwright-api.md

references/playwright-api.md

Playwright MCP tool reference for screenshot operations:
  • browser_navigate
    - Navigation and URL handling
  • browser_resize
    - Viewport dimension control
  • browser_wait_for
    - Waiting strategies for layout settling
  • browser_take_screenshot
    - Screenshot capture options
Playwright MCP工具截图操作参考：
  • browser_navigate
    - 导航和URL处理
  • browser_resize
    - 视口尺寸控制
  • browser_wait_for
    - 布局稳定等待策略
  • browser_take_screenshot
    - 截图捕获选项

examples/examples.md

examples/examples.md

Comprehensive screenshot capture examples:
  • Standard breakpoint captures
  • Custom device viewports
  • Multi-page workflows
  • Report generation
  • Edge cases (ultra-wide, mobile landscape, etc.)
全面的截图捕获示例：
  • 标准断点捕获
  • 自定义设备视口
  • 多页面工作流
  • 报告生成
  • 极端场景（超宽屏、移动端横屏等）

scripts/validate_screenshots.py

scripts/validate_screenshots.py

Python utility to validate screenshot dimensions match expected breakpoints.
用于验证截图尺寸是否符合预期断点的Python工具。

Expected Outcomes

预期结果

Successful Screenshot Capture

截图捕获成功

✅ Responsive Screenshots Captured

URL: https://example.com/homepage
Breakpoints: mobile, tablet, desktop
Pages: 1

Screenshots:
  ✓ homepage-mobile.png (375×667, 234KB)
  ✓ homepage-tablet.png (768×1024, 512KB)
  ✓ homepage-desktop.png (1920×1080, 1.2MB)

Location: /Users/username/screenshots/
Total time: 8.3 seconds

All screenshots captured successfully. Full-page screenshots enabled.
✅ Responsive Screenshots Captured

URL: https://example.com/homepage
Breakpoints: mobile, tablet, desktop
Pages: 1

Screenshots:
  ✓ homepage-mobile.png (375×667, 234KB)
  ✓ homepage-tablet.png (768×1024, 512KB)
  ✓ homepage-desktop.png (1920×1080, 1.2MB)

Location: /Users/username/screenshots/
Total time: 8.3 seconds

All screenshots captured successfully. Full-page screenshots enabled.

With Comparison Report

生成对比报告

✅ Responsive Screenshots Captured with Report

URL: https://shop.com
Breakpoints: mobile, tablet, desktop
Pages: 3 (/home, /products, /about)

Screenshots: 9 total
  ✓ home-mobile.png, home-tablet.png, home-desktop.png
  ✓ products-mobile.png, products-tablet.png, products-desktop.png
  ✓ about-mobile.png, about-tablet.png, about-desktop.png

Report: screenshots/report.md

View comparison report for side-by-side layout analysis.
✅ Responsive Screenshots Captured with Report

URL: https://shop.com
Breakpoints: mobile, tablet, desktop
Pages: 3 (/home, /products, /about)

Screenshots: 9 total
  ✓ home-mobile.png, home-tablet.png, home-desktop.png
  ✓ products-mobile.png, products-tablet.png, products-desktop.png
  ✓ about-mobile.png, about-tablet.png, about-desktop.png

Report: screenshots/report.md

View comparison report for side-by-side layout analysis.

Validation Failure

验证失败

❌ Screenshot Capture Failed

URL: https://broken-site.com
Issue: Page failed to load (timeout after 30s)

Breakpoint progress:
  ✗ mobile - not attempted (navigation failed)
  ✗ tablet - not attempted
  ✗ desktop - not attempted

Recommendation: Verify URL is accessible and site is responding.
❌ Screenshot Capture Failed

URL: https://broken-site.com
Issue: Page failed to load (timeout after 30s)

Breakpoint progress:
  ✗ mobile - not attempted (navigation failed)
  ✗ tablet - not attempted
  ✗ desktop - not attempted

Recommendation: Verify URL is accessible and site is responding.

Requirements

要求

Playwright MCP Tools:
  • browser_navigate
    - Navigate to URLs
  • browser_resize
    - Set viewport dimensions
  • browser_wait_for
    - Wait for layout settling
  • browser_take_screenshot
    - Capture screenshots
Browser Requirements:
  • Playwright browser installed and configured
  • Sufficient viewport size support (minimum 200×200, maximum 3840×2160)
File System:
  • Write permissions for screenshot output directory
  • Sufficient disk space (estimate ~1-2MB per desktop screenshot)
Network:
  • Access to target URLs
  • Stable connection for page loading
Playwright MCP工具：
  • browser_navigate
    - 导航至URL
  • browser_resize
    - 设置视口尺寸
  • browser_wait_for
    - 等待布局稳定
  • browser_take_screenshot
    - 捕获截图
浏览器要求：
  • 已安装并配置Playwright浏览器
  • 支持足够的视口尺寸（最小200×200，最大3840×2160）
文件系统：
  • 截图输出目录的写入权限
  • 足够的磁盘空间（预估每张桌面截图约1-2MB）
网络：
  • 可访问目标URL
  • 稳定的页面加载网络连接

Red Flags to Avoid

注意事项

  1. ❌ Skipping layout settling wait - Always wait minimum 1s after resize
  2. ❌ Not using fullPage: true - Missing content below fold
  3. ❌ Inconsistent file naming - Use 
    {page-name}-{breakpoint}.png
  4. ❌ Unreasonable viewport dimensions - Validate 200-3840 width, 200-2160 height
  5. ❌ Re-navigating for each breakpoint - Navigate once, resize in loop
  6. ❌ Ignoring page load failures - Verify navigation success first
  7. ❌ Missing screenshot organization - Use dedicated output directory
  8. ❌ Not reporting file locations - Provide absolute paths
  9. ❌ Forgetting viewport height - Always specify both width and height
  10. ❌ Not validating custom breakpoints - Parse and validate dimensions
  1. ❌ 跳过布局稳定等待 - 调整尺寸后至少等待1秒
  2. ❌ 未设置fullPage: true - 会遗漏折叠区域下方的内容
  3. ❌ 文件命名不一致 - 请使用
    {页面名称}-{断点标识}.png
    规则
  4. ❌ 不合理的视口尺寸 - 验证尺寸在200-3840宽度、200-2160高度范围内
  5. ❌ 每个断点都重新导航 - 仅导航一次，在循环中调整尺寸
  6. ❌ 忽略页面加载失败 - 首先验证导航是否成功
  7. ❌ 未整理截图 - 使用专用的输出目录
  8. ❌ 未报告文件位置 - 提供绝对路径
  9. ❌ 遗漏视口高度 - 始终同时指定宽度和高度
  10. ❌ 未验证自定义断点 - 解析并验证尺寸合理性

Notes

说明

Performance: Adjust wait times (500ms static, 1s standard, 2-3s SPAs). Navigate once per page. Breakpoints: Use actual device viewports, not arbitrary sizes. Document custom breakpoints. Quality: PNG for UI (lossless), JPEG for photos (smaller). Screenshots serve as visual regression baselines.
性能： 根据场景调整等待时长（静态页面500ms，标准1秒，单页应用2-3秒）。每个页面仅导航一次。 断点： 使用真实设备视口，而非任意尺寸。记录自定义断点信息。 质量： UI截图使用PNG格式（无损），照片使用JPEG格式（文件更小）。截图可作为视觉回归测试基准。