name: ui-screenshots description: Take UI screenshots using Playwright and attach them as PR comments. Use this skill to capture visual state of UI components for code review, visual regression testing, or documentation.

UI Screenshots Skill

Capture UI screenshots and attach them to pull requests for visual verification.

Prerequisites

1. UI Dependencies: Ensure UI dependencies are installed:

   cd apps/ui && npm install
   

2. Playwright Browser: Chromium browser must be available:

   npx playwright install chromium
   

   In restricted environments (cloud agents), older pre-installed chromium at /root/.cache/ms-playwright/chromium-1194/chrome-linux/chrome may work better.

3. Cloudinary Account (free tier available):

   • Create account at cloudinary.com
   • Get your CLOUDINARY_URL from the dashboard (format: cloudinary://API_KEY:API_SECRET@CLOUD_NAME)
   • Set environment variable: CLOUDINARY_URL

4. GitHub Token: GITHUB_TOKEN environment variable for PR comments.

Usage

Taking Screenshots

Run the e2e screenshot tests:

just e2e-screenshots

This captures screenshots to apps/ui/e2e/screenshots/ (gitignored, not committed).

Manual Screenshot Script

For custom screenshots, create a script like:

// screenshot.mjs
import { chromium } from 'playwright';

const browser = await chromium.launch({
  executablePath: process.env.PLAYWRIGHT_CHROMIUM_PATH,
  args: ['--no-sandbox', '--disable-gpu', '--single-process'],
});

const page = await browser.newPage();
await page.goto('http://localhost:9100/dev/components');
await page.waitForLoadState('networkidle');
await page.screenshot({ path: 'screenshot.png', fullPage: true });
await browser.close();

Run with:

PLAYWRIGHT_CHROMIUM_PATH=/root/.cache/ms-playwright/chromium-1194/chrome-linux/chrome \
  node screenshot.mjs

Attaching Screenshots to PR

Screenshots are NOT committed to the repo. They are uploaded to Cloudinary and embedded in PR comments:

# Use the helper script
.claude/skills/ui-screenshots/scripts/upload-screenshot.sh \
  apps/ui/e2e/screenshots/dev-components-full.png \
  195  # PR number

Integration with Smoke Tests

The smoke test skill can call this skill to capture UI state:

1. Run e2e screenshot tests as part of smoke testing
2. If a PR branch is detected, upload screenshots and add PR comment
3. Screenshots help reviewers verify visual changes

Troubleshooting

Browser crashes in restricted environments

Use the --single-process flag and specify an older chromium:

export PLAYWRIGHT_CHROMIUM_PATH=/root/.cache/ms-playwright/chromium-1194/chrome-linux/chrome

Page hangs on localhost

The dev server may not be running. Start it first:

cd apps/ui && npm run dev &
sleep 10  # Wait for server

Or run tests with webServer config (in playwright.config.ts).

Permission denied for /tmp

In sandboxed environments, shared memory may fail. Use --disable-dev-shm-usage flag.

Cloudinary upload fails

Verify CLOUDINARY_URL is set correctly:

• Format: cloudinary://API_KEY:API_SECRET@CLOUD_NAME
• Get from Cloudinary dashboard

Available Screenshots

The e2e tests capture these screenshots (stored locally, not in repo):

Script Reference

take-screenshot.sh

Take a screenshot of a URL:

.claude/skills/ui-screenshots/scripts/take-screenshot.sh [URL] [OUTPUT_PATH]

Example:

.claude/skills/ui-screenshots/scripts/take-screenshot.sh \
  http://localhost:9100/dev/components \
  apps/ui/e2e/screenshots/custom.png

upload-screenshot.sh

Upload screenshot to Cloudinary and add PR comment:

.claude/skills/ui-screenshots/scripts/upload-screenshot.sh <SCREENSHOT_PATH> <PR_NUMBER> [DESCRIPTION]

Example:

.claude/skills/ui-screenshots/scripts/upload-screenshot.sh \
  apps/ui/e2e/screenshots/dev-components-full.png \
  195 \
  "Dev components page showing message and tool call rendering"

check-config.sh

Check if cloud agent environment is configured:

.claude/skills/ui-screenshots/scripts/check-config.sh

Verifies: GITHUB_TOKEN, CLOUDINARY_URL, and Chromium availability.