@assertrx/dino 1.0.0

package/skills/playwright-cli/screenshots-and-media.md

@@ -0,0 +1,457 @@
+# Screenshots and Media
+
+> **When to use**: Capturing visual evidence of page state — screenshots for verification, video recordings for demos or debugging, PDF exports for documentation, viewport resizing for responsive testing.
+> **Prerequisites**: [core-commands.md](core-commands.md) for basic CLI usage
+
+## Quick Reference
+
+```bash
+# Screenshots
+playwright-cli screenshot                         # Full page screenshot
+playwright-cli screenshot e5                      # Element screenshot
+playwright-cli screenshot --filename=checkout.png # Custom filename
+
+# PDF
+playwright-cli pdf --filename=report.pdf          # Save page as PDF
+
+# Video
+playwright-cli video-start                        # Start recording
+playwright-cli video-stop demo.webm               # Stop and save
+
+# Viewport
+playwright-cli resize 1920 1080                   # Desktop
+playwright-cli resize 375 812                     # Mobile
+```
+
+## Screenshots
+
+### Page Screenshot
+
+Capture the entire visible viewport:
+
+```bash
+# Auto-generated filename
+playwright-cli screenshot
+
+# Custom filename
+playwright-cli screenshot --filename=homepage.png
+playwright-cli screenshot --filename=screenshots/checkout-step3.png
+```
+
+### Element Screenshot
+
+Capture a specific element only — useful for component-level verification:
+
+```bash
+# Screenshot a single element by ref
+playwright-cli snapshot          # Get refs first
+playwright-cli screenshot e5     # Capture just element e5
+
+# With custom filename
+playwright-cli screenshot e5 --filename=product-card.png
+```
+
+### Full-Page Screenshot
+
+Capture the entire scrollable page, not just the viewport:
+
+```bash
+playwright-cli run-code "async page => {
+  await page.screenshot({ path: 'full-page.png', fullPage: true });
+  return 'Saved full-page screenshot';
+}"
+```
+
+### Screenshot with Options
+
+Use `run-code` for advanced screenshot options:
+
+```bash
+# Full page with quality settings (JPEG)
+playwright-cli run-code "async page => {
+  await page.screenshot({
+    path: 'optimized.jpg',
+    type: 'jpeg',
+    quality: 80,
+    fullPage: true
+  });
+}"
+
+# Clip to specific region
+playwright-cli run-code "async page => {
+  await page.screenshot({
+    path: 'header-region.png',
+    clip: { x: 0, y: 0, width: 1280, height: 200 }
+  });
+}"
+
+# With transparent background (for elements with transparency)
+playwright-cli run-code "async page => {
+  await page.screenshot({
+    path: 'transparent.png',
+    omitBackground: true
+  });
+}"
+
+# Screenshot with mask (hide dynamic content)
+playwright-cli run-code "async page => {
+  await page.screenshot({
+    path: 'masked.png',
+    mask: [
+      page.locator('.timestamp'),
+      page.locator('.user-avatar'),
+      page.locator('.ad-banner')
+    ]
+  });
+}"
+
+# Disable animations before screenshot
+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' });
+}"
+```
+
+### Element Screenshot with Options
+
+```bash
+playwright-cli run-code "async page => {
+  const element = page.getByTestId('pricing-card');
+  await element.screenshot({
+    path: 'pricing-card.png',
+    omitBackground: true
+  });
+}"
+```
+
+## Responsive Screenshots
+
+Capture how the page looks at different viewport sizes:
+
+```bash
+# Desktop (1920x1080)
+playwright-cli resize 1920 1080
+playwright-cli screenshot --filename=desktop.png
+
+# Laptop (1366x768)
+playwright-cli resize 1366 768
+playwright-cli screenshot --filename=laptop.png
+
+# Tablet landscape (1024x768)
+playwright-cli resize 1024 768
+playwright-cli screenshot --filename=tablet-landscape.png
+
+# Tablet portrait (768x1024)
+playwright-cli resize 768 1024
+playwright-cli screenshot --filename=tablet-portrait.png
+
+# Mobile (375x812 — iPhone X)
+playwright-cli resize 375 812
+playwright-cli screenshot --filename=mobile.png
+
+# Mobile small (320x568 — iPhone SE)
+playwright-cli resize 320 568
+playwright-cli screenshot --filename=mobile-small.png
+```
+
+### Automated Responsive Screenshots
+
+```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);  // Allow layout to settle
+    await page.screenshot({ path: \`responsive-\${vp.name}.png\` });
+  }
+  return 'Captured ' + viewports.length + ' responsive screenshots';
+}"
+```
+
+## PDF Export
+
+Generate PDF documents from web pages — useful for reports, invoices, and documentation.
+
+```bash
+# Basic PDF
+playwright-cli pdf --filename=page.pdf
+```
+
+### Advanced PDF Options
+
+```bash
+# PDF with custom options
+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 saved';
+}"
+
+# Letter format with header/footer
+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' }
+  });
+}"
+
+# Landscape PDF
+playwright-cli run-code "async page => {
+  await page.pdf({
+    path: 'landscape.pdf',
+    landscape: true,
+    format: 'A4',
+    printBackground: true
+  });
+}"
+
+# Specific pages only
+playwright-cli run-code "async page => {
+  await page.pdf({
+    path: 'partial.pdf',
+    pageRanges: '1-3',
+    format: 'A4'
+  });
+}"
+```
+
+**Note**: PDF generation only works with Chromium-based browsers, not Firefox or WebKit.
+
+### Print Stylesheet Preview
+
+Before generating a PDF, switch to print media to see the print layout:
+
+```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
+```
+
+## Video Recording
+
+Record browser sessions as WebM video files.
+
+For simple "start recording now, stop later" flows, `video-start` and `video-stop` remain fine. For Playwright 1.59+ workflows that need precise start and stop control, action callouts, chapter titles, or richer review videos, prefer `page.screencast`.
+
+### Screencast API (Playwright 1.59+)
+
+Use `page.screencast` when you need a richer artifact than plain video recording.
+
+```bash
+# Start a screencast with an explicit output path
+playwright-cli run-code "async page => {
+  await page.screencast.start({
+    path: 'recordings/checkout-walkthrough.webm',
+    size: { width: 1280, height: 800 }
+  });
+  return 'Screencast started';
+}"
+
+# Stop and finalize the file
+playwright-cli run-code "async page => {
+  await page.screencast.stop();
+  return 'Screencast saved';
+}"
+```
+
+### Annotated Screencasts
+
+Playwright 1.59 adds built-in action annotations and chapter overlays, which are ideal for demos, debugging, and agent receipts.
+
+```bash
+playwright-cli run-code "async page => {
+  await page.screencast.start({ path: 'recordings/annotated-demo.webm' });
+  await page.screencast.showActions({
+    position: 'top-right',
+    duration: 900,
+    fontSize: 20
+  });
+  await page.screencast.showChapter('Checkout flow', {
+    description: 'Verify coupon entry and updated totals',
+    duration: 1500
+  });
+  return 'Annotated screencast started';
+}"
+
+# Perform the flow with normal playwright-cli commands here
+# ...
+
+playwright-cli run-code "async page => {
+  await page.screencast.showChapter('Done', {
+    description: 'Coupon applied and totals updated'
+  });
+  await page.screencast.stop();
+  return 'Annotated screencast saved';
+}"
+```
+
+### When To Use Screencast vs Video Recording
+
+| Need | Best choice |
+|------|-------------|
+| Fast ad-hoc browser capture from the CLI | `video-start` / `video-stop` |
+| Precise start and stop around one flow | `page.screencast.start()` / `stop()` |
+| Action callouts during recording | `page.screencast.showActions()` |
+| Chapter titles for walkthrough videos | `page.screencast.showChapter()` |
+| Agent evidence / review receipts | `page.screencast` |
+
+### Basic Recording
+
+```bash
+# Start recording
+playwright-cli video-start
+
+# Perform actions (everything is recorded)
+playwright-cli open https://example.com
+playwright-cli snapshot
+playwright-cli click e1
+playwright-cli fill e2 "test input"
+playwright-cli click e5
+
+# Stop and save
+playwright-cli video-stop demo.webm
+```
+
+### Recording with Descriptive Names
+
+```bash
+playwright-cli video-start
+# ... login flow ...
+playwright-cli video-stop recordings/login-flow-2024-01-15.webm
+
+playwright-cli video-start
+# ... checkout flow ...
+playwright-cli video-stop recordings/checkout-happy-path.webm
+```
+
+### Use Cases
+
+| Scenario | Benefit |
+|----------|---------|
+| Bug reproduction | Share exact steps with developers |
+| Demo creation | Show feature flows to stakeholders |
+| Documentation | Record UI walkthroughs |
+| QA evidence | Prove a test scenario was completed |
+| Debugging | Watch what happened frame-by-frame |
+
+## Viewport Management
+
+Control the browser viewport for responsive testing:
+
+```bash
+# Common desktop sizes
+playwright-cli resize 1920 1080    # Full HD
+playwright-cli resize 1440 900     # MacBook Pro 15"
+playwright-cli resize 1366 768     # Common laptop
+playwright-cli resize 1280 720     # HD
+
+# Tablet sizes
+playwright-cli resize 1024 768     # iPad landscape
+playwright-cli resize 768 1024     # iPad portrait
+playwright-cli resize 834 1194     # iPad Pro 11"
+
+# Mobile sizes
+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
+```
+
+## Common Patterns
+
+### Before/After Comparison
+
+```bash
+# Before action
+playwright-cli screenshot --filename=before.png
+playwright-cli click e5
+# After action
+playwright-cli screenshot --filename=after.png
+```
+
+### Full Documentation Suite
+
+```bash
+playwright-cli open https://app.example.com
+
+# Login page
+playwright-cli screenshot --filename=docs/01-login.png
+
+# Fill and submit
+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
+
+# Navigate to settings
+playwright-cli goto https://app.example.com/settings
+playwright-cli screenshot --filename=docs/04-settings.png
+
+# Generate PDF of documentation page
+playwright-cli goto https://app.example.com/docs
+playwright-cli pdf --filename=docs/user-guide.pdf
+```
+
+### Dark Mode vs Light Mode Screenshots
+
+```bash
+playwright-cli open https://example.com
+
+# Light mode
+playwright-cli run-code "async page => { await page.emulateMedia({ colorScheme: 'light' }); }"
+playwright-cli screenshot --filename=light-mode.png
+
+# Dark mode
+playwright-cli run-code "async page => { await page.emulateMedia({ colorScheme: 'dark' }); }"
+playwright-cli screenshot --filename=dark-mode.png
+```
+
+### Cross-Browser Screenshot Comparison
+
+```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
+```
+
+## Tips
+
+- **Always set viewport before screenshotting** — `resize` before `screenshot` for consistent dimensions
+- **Use descriptive filenames** — `checkout-step3-error.png` not `screenshot-1.png`
+- **Create output directories first** — `mkdir -p screenshots/` before using subdirectory paths
+- **Full-page for long content** — use `fullPage: true` via `run-code` for scrollable pages
+- **Mask dynamic content** — hide timestamps, avatars, and ads to get deterministic screenshots
+- **Print media before PDF** — `emulateMedia({ media: 'print' })` to see what the PDF will look like
+- **Video adds overhead** — only record when needed; tracing is lighter for debugging