Skip to content

testdino-hq/playwright-skill / playwright-cli

playwright-cli

Verified

Automates browser interactions for testing and validating your own web applications using playwright-cli. Use when you need terminal-first browser control for navigation, form filling, screenshots, tracing, bound browser sessions, debugging, or generating Playwright test code. Only use against applications you own or have explicit authorization to test.

FileKindSize
SKILL.mdskill md10.5 KB
advanced-workflows.mdmarkdown18.3 KB
core-commands.mdmarkdown11.4 KB
device-emulation.mdmarkdown13.3 KB
request-mocking.mdmarkdown10.1 KB
running-custom-code.mdmarkdown14.8 KB
screenshots-and-media.mdmarkdown14.0 KB
session-management.mdmarkdown12.1 KB
storage-and-auth.mdmarkdown11.2 KB
test-generation.mdmarkdown10.9 KB
tracing-and-debugging.mdmarkdown14.7 KB

screenshots-and-media.md

View on GitHub
# 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 demo.webm               # Start recording (browser must be open)
playwright-cli video-stop                         # 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; `video-chapter "Title" --description="..." --duration=2000` and `video-show-actions --position=top-right` (undo with `video-hide-actions`) add chapters and action callouts without `run-code`. 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,
    style: { title: 'font-size: 20px' } // 1.64+: replaces the deprecated fontSize option
  });
  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';
}"
```

### Smoother, Styled Recordings (Playwright 1.64+)

1.64 makes recordings good enough to publish as walkthroughs:

- **`fps`** on `screencast.start()`, `recordVideo` and the test `video` option. Use 30 to 60 for demos. Firefox and WebKit currently cap at 25.
- **`showActions({ style })`** takes CSS declarations for the click `point`, the target `highlight` and the action `title`. It replaces `fontSize`, which is deprecated.
- The cursor now stays visible at the last action point, survives navigations, and moves along an eased path, so viewers can follow it.
- Output is VP9 instead of VP8: smaller files, less CPU.

```bash
playwright-cli run-code "async page => {
  await page.screencast.start({
    path: 'recordings/release-demo.webm',
    size: { width: 1920, height: 1080 },
    fps: 60
  });
  await page.screencast.showActions({
    style: {
      point: 'width: 20px; height: 20px; border-radius: 50%; background: red',
      highlight: 'outline: 2px solid #333; background: rgba(0, 128, 255, .15)',
      title: 'font-size: 16px'
    }
  });
  return 'Recording at 60fps';
}"
```

The same options work in the test runner config, so a demo spec can record itself:

```typescript
// playwright.config.ts
use: {
  video: {
    mode: 'on',
    size: { width: 1920, height: 1080 },
    fps: 60,
    show: { actions: { style: { title: 'font-size: 16px' } } },
  },
},
```

### 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
# Open the browser, then start recording
playwright-cli open
playwright-cli video-start demo.webm

# Perform actions (everything is recorded)
playwright-cli goto 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
```

### Recording with Descriptive Names

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

playwright-cli video-start recordings/checkout-happy-path.webm
# ... checkout flow ...
playwright-cli video-stop
```

### 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
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall