ui-screenshots

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.